Éric
Bischoff
2021-10-04
KDE Gear 21.08
KDE
KTuberling
technical reference

# Technical References

&ktuberling; offers a gentle and rewarding introduction to &kde; customization and programming. The application can be extended. For example, without any coding, new playgrounds can be added by changing the graphics files. By adding appropriate sound files, translators can change the sounds to their native tongue!

If you extend or add to the game please consider sending your additions to the maintainer Alex Fiestas for inclusion in future releases.

## For Artists

To create a new &ktuberling; playground you have to:

- Draw the playground in a &SVG; file, there you have to:

  - Name the place where items can dragged background.

  - Name each of the draggable items with an unique name.

- Create a `.theme` file, it has to follow this schema:

      <playground gameboard="yourSVGFile" name="theDesktopFile">
      <object name="itemName" sound="soundName" scale="someValue" />
      ...
      ...
      ...
      </playground>

  - yourSVGFile is the name of the &SVG; file that has the drawing.

  - theDesktopFile is the name of the desktop file that has the name of the theme.

  - For each object you need a `<object>` entry. itemName is the unique name you used on the &SVG; file, soundName is the sound name that will be played when dragging it, see the `sounds/soundthemes.HOWTO` file from source code for more information.

  - `scale` is optional and someValue is the scale factor that will be used when drawing this object outside the warehouse, if not specified is 1.

- Create a `.desktop` file, it has to follow this schema:

      [KTuberlingTheme]
      Name=themeName

  - themeName is the name that identifies the theme, will be shown in the Playground menu.

- If you are adding the theme to &ktuberling; repository, add `.svg`, `.theme`, and `.desktop` files to `FILES` section of the `CMakeLists.txt` into the `pics/` folder.

- If you want to install it for yourself, place `.svg`, `.theme`, and `.desktop` files into the `ktuberling/pics` folder in ``qtpaths` `--paths GenericDataLocation``

## For Translators

Besides the usual `.po` files mechanism for translating program labels and prompts, the sounds can be localized too.

To create a new &ktuberling; sound theme you have to:

- Record the sounds in OGG Vorbis rc3 file format.

- Create a `yourLanguageTwoLetterCode.soundtheme` file, it has to follow this schema:

      <language code="yourLanguageTwoLetterCode">
      <sound name="soundName" file="relativePath" />
      ...
      ...
      ...
      </language>

  - yourLanguageTwoLetterCode is your language two letter code, for example gl for Galician.

  - For each sound a `<sound>` entry. soundName should match with the soundName specified in the playground theme (see the `pics/themes.HOWTO` from source code). relativePath should be the relative path you are going to install the file with this sound to, typically it will be `someUniquePath/soundName.format` (someUniquePath can be your language two letter code for example).

- If you are adding the sound theme to &ktuberling; in your language folder:

  - Add the sound files and the `.soundtheme` files into the `data/kdegames/ktuberling` folder of your language translations.

  - On that very same dir you need a `CMakeLists.txt` file describing how to install the files, typically it will be.

        FILE( GLOB oggfiles *.ogg )
        INSTALL( FILES ${oggfiles} DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/yourLanguageTwoLetterCode )
        INSTALL( FILES yourLanguageTwoLetterCode.soundtheme DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/ )

- If you want to install it for yourself:

  - Place `yourLanguageTwoLetterCode.soundtheme` file into the `ktuberling/sounds` folder in ``qtpaths` `--paths GenericDataLocation``

  - Place your sound files into the `ktuberling/sounds/someUniquePath` folder in ``qtpaths` `--paths GenericDataLocation``

Information on how to work with the translation mechanisms in &kde; is available in The &kde; Translation HOWTO.

## For Programmers

&ktuberling; isn't really difficult to extend for programmers.

### C++ classes

`TopLevel`

  Top-level window and basic program management.

`PlayGround`

  Description of one of the game levels.

`ToDraw`

  Description of one of the graphical objects to be drawn.

`SoundFactory`

  Description of one of the languages and its sounds.

`Action`

  One of the user's manipulation in the undo/redo stack.