The KTuberling Handbook

# The KTuberling Handbook

Éric Bischoff `<e.bischoff@noos.fr>`

Paul E. Ahlquist, Jr. `<pea@ahlquist.org>`

Eugene Trounev `<eugene.trounev@gmail.com>`

Reviewer: Lauri Watts
Revision KDE Gear 21.08 (2021-10-04)

Copyright © 1999, 2000, 2002, 2006 Éric Bischoff

Copyright © 2001 Paul E. Ahlquist, Jr.

Legal Notice

Potato Guy is a game intended for small children.

List of Tables

4.1. Toolbar Buttons

Chapter 1. Introduction
Introduction

# Chapter 1. Introduction

Gametype: Toy

Number of possible players: One

Potato Guy is a simple constructor game suitable for children and adults alike. The idea of the game is based around a once popular doll making concept. A potato was decorated with various small artifacts to make it look more like a tiny person. Potato Guy however, goes much further in terms of content and adds a surprising variety of different themes.

Chapter 2. How to Play
How to Play

# Chapter 2. How to Play

Potato Guy is a game intended for small children. Of course, it may be suitable for adults who have remained young at heart.

It is a “potato editor”. That means that you can drag and drop eyes, mouths, mustache, and other parts of face and goodies onto a potato-like guy. Similarly, you have other playgrounds with different themes.

There is no winner for the game. The only purpose is to make the funniest faces you can.

Potato Guy can also “speak”. It will spell out the name of the objects you drag and drop. It will “speak” in a language that you can choose. You can even use it to learn a bit of vocabulary in foreign languages.

Chapter 3. Rules and Tips
Rules and Tips

# Chapter 3. Rules and Tips

## Mouse Operation

There are two areas in the main window:

- “Playground” area.

- “Objects” area, where you select objects to place on your playground.

### Note

An actual look of the application screen may change depending on a “playground” selected.

### Placing an Object

To drag an object, move the mouse pointer to the “objects” area and click on it. Then move it to the “playground” area and click again.

### Note

Size of the objects may change while dragging. Some of the oversized objects have been scaled down to feet into the “objects” area.

### Moving an Object

Once dropped in the “playground” area, an object can be moved. Just click on the object to select it, move it to the new place and click again to drop it. When you drop it, it goes on top of other objects that were partially hiding it. This trick is useful for getting the glasses and eyes placed correctly.

### Removing an Object

To remove an object that has been dropped in the “playground” area, drag it back from the “playground” area to the “objects” area.

Chapter 4. Interface Overview
Interface Overview

# Chapter 4. Interface Overview

## The Tool Bar

The toolbar provides buttons for the commonly used functions.

Table 4.1. Toolbar Buttons

Button | Name | Menu Equivalent | Action
--- | --- | --- | ---
| New | Game → New | Resets the “playground” area. This cleans all parts of the playground so a new decoration may be created.
| Load… | Game → Load… | Opens an existing `.tuberling` file from the disk.
| Save | Game → Save | Saves your creation to your home folder, or to some other folder on your disk. The `.tuberling` is saved to a small file where only the position of objects are saved.
| Print… | Game → Print… | Prints your picture.
| Undo | Edit → Undo | Undoes last operation.
| Redo | Edit → Redo | Re-does last operation.

The Menu Items
The Menu Items

## The Menu Items

### The Game Menu

Game → New (Ctrl+N)

  Clears the “playground” area.

Game → Load… (Ctrl+O)

  Opens an existing `.tuberling` file from your disk.

Game → Save (Ctrl+S)

  Saves your creation. The tuberling is saved to a small file where only the position of objects are saved.

Game → Save as Picture…

  Creates a graphics file containing a picture of your tuberling.

Game → Print… (Ctrl+P)

  Prints your tuberling picture.

Game → Quit (Ctrl+Q)

  Quit Potato Guy.

### The Edit Menu

Edit → Undo (Ctrl+Z)

  Undo the last “object” placement.

Edit → Redo (Ctrl+Shift+Z)

  Re-does the last “object” placement. This menu option is active only if you have previously used Undo.

Edit → Copy (Ctrl+C)

  Copy the “playground” area to the clipboard.

### The View Menu

View → Full Screen Mode (Ctrl+Shift+F)

  Toggles the graphic interface to full screen mode.

### The Playground Menu

Playground → Lock Aspect Ratio

  This option preserves the playground aspect ratio when resizing the Potato Guy window. When the playground aspect ratio does not match the one of the window the background is filled with the one specified in the theme.

Playground → `Playground Name`

  Switches to the playground.

It will contain the playgrounds installed in your system.

Potato Guy remembers the last chosen playground the next time it starts up.

### The Speech Menu

Speech → No Sound

  Toggles sound off.

Speech → `Language Name`

  Toggles sound on and speaks the selected language.

Potato Guy remembers of this option the next time it starts up.

### The Settings and Help Menus

Additionally Potato Guy has the common KDE Settings and Help menu items, for more information read the sections about the Settings Menu and Help Menu of the KDE Fundamentals.

Chapter 5. Frequently Asked Questions
Frequently Asked Questions

# Chapter 5. Frequently Asked Questions

5.1. I want to change the way this game looks. Can I?
5.2. Can I use the keyboard to play this game?
5.3. I have made a great picture and I want to share it with my friends. Can I save it as an image?

5.1. | I want to change the way this game looks. Can I?
| Yes you can. Refer to this section of 'Interface Overview' for details.
5.2. | Can I use the keyboard to play this game?
| No. This game cannot be played using keyboard.
5.3. | I have made a great picture and I want to share it with my friends. Can I save it as an image?
| Yes. To save the current session as an image refer to this section of 'Interface Overview' for details.

Chapter 6. Technical References
Technical References

# Chapter 6. Technical References

Éric Bischoff

Revision KDE Gear 21.08 (2021-10-04)

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
For Translators

## 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
For Programmers

## 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.

Chapter 7. Credits and License
Credits and License

# Chapter 7. Credits and License

KTuberling

- Alex Fiestas `(alex AT eyeos.org)` - current Maintainer

- John Calhoun - Original idea, original pictures and English sounds

- Éric Bischoff `(e.bischoff AT noos.fr)` - KDE Programming

- François-Xavier Duranceau `(duranceau AT free.fr)` - Tests, advice and help

- Peter Silva `(peter.silva AT videotron.ca)` - Proofreading of the documentation

- Paul E. Ahlquist, Jr. `(pea AT ahlquist.org)` - Bettering of documentation

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.