# The KTuberling Handbook

Eric
Bischoff

    ebisch@cybercable.tm.fr

28/06/1999
0.01.01

This document was last updated for ktuberling version 0.1.1. Please make any comments and additions to the author.

KDE
KTuberling
game
potato
tuberling

## Introduction

KTuberling 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, moustache, and other parts of face and goodies onto a potato-like guy.

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

There is a museum (like a "Madame Tusseau" gallery) where you can find many funny examples of decorated potatoes. Of course, you can send your own creations to the programmer, Eric Bischoff, who will include them in the museum if he gets some spare time.

## Installation

### How to obtain ktuberling

ktuberling is a game application for the KDE project http://www.kde.org. Ktuberling can be found on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements

In order to successfully compile ktuberling, you need the latest versions of `libkdecore`, `libkdeui`, `libkfile`, `libkfm`, and `libmediatooli`. All required libraries as well as ktuberling itself can be found on ftp://ftp.kde.org/pub/kde/.

### Compilation and installation

In order to compile and install ktuberling on your system, type the following in the base directory of the ktuberling distribution:

    % ./configure
    % make
    % make install

## Onscreen Fundamentals

### Mouse Operation

There are two parts in the main window : on the left side, there is the "potato" area where you can drop objects (eyebrows, noses, spectacles, ...) from the part on the right side, the "objects" area.

To drag an object, move the mouse pointer to the "objects" area, click on the object you want to drag, but do not release the mouse button until you have moved the mouse pointer to the location in the "potato" area where you want to drop the object.

Once dropped in the "potato" area, an object can be moved around in that area. Just click on it to select it for further drag and drop. When you click on it, it goes on top of other objects that were partially hiding it.

To remove an object that has been dropped in the "potato" area, drag it back from the "potato" area to the "objects" area.

### The Menu Items

#### The File Menu

New

  Resets the "potato" area.

Open

  Opens an existing tuberling file from the museum or from somewhere else if you wish.

Save

  Saves your creation to the museum, or to somewhere else if you wish. The tuberling is saved to a low weight file where only the position of objects are saved.

Save as picture

  Creates a file holding the picture of your tuberling. Available file formats are XPM, JPEG, PNG and BMP.

Print

  Prints your picture (PostScript (TM) format).

Quit

  Quits KTuberling.

#### The Edit Menu

Copy

  Copies the potato area as a picture to the clipboard.

Undo

  Undoes last operation.

Redo

  Re-does last operation.

#### The Options Menu

Sound

  Toggles sound on/off. If kaudioplayer isn't running, this menu item is greyed out.

#### The Help Menu

Contents

  Displays this handbook.

About KTuberling

  Satisfies ego of authors.

About KDE

  Tells about one of the greatest Linux-related projects.

### The Tool Bar

#### "New" Button

Resets the "potato" area.

#### "Open" Button

Opens an existing tuberling file from the museum or from somewhere else if you wish.

#### "Save" Button

Saves your creation to the museum, or to somewhere else if you wish. The tuberling is saved to a low weight file where only the position of objects are saved.

#### "Print" Button

Prints your picture (PostScript (TM) format).

#### "Undo" Button

Undoes last operation.

#### "Redo" Button

Redoes last operation.

#### "Help" Button

Displays this handbook.

### Keyboard usage

You can redefine nearly all keyboard bindings, but the following defaults are just fine :

Ctrl-N

  Resets the "Potato" area

Ctrl-O

  Opens an existing tuberling file from the museum or from somewhere else if you wish.

Ctrl-S

  Saves your creation to the museum, or to somewhere else if you wish. The tuberling is saved to a low weight file where only the position of objects are saved.

Ctrl-P

  Prints your picture (PostScript (TM) format).

Ctrl-Q

  Quits KTuberling.

Ctrl-C

  Copies the potato area as a picture to the clipboard.

Ctrl-Z

  Undoes last operation.

Ctrl-A

  Re-does last operation. (This key binding is not redefinable).

F1

  Displays this handbook.

## Technical reference

### For graphists

KTuberling allows many changes in the graphical appearance: the gamebard's size and shape, the number of objects that can be moved onto it, their size and the category they belong to can be redefined. But the labels of the various groups of objects (noses, eyes, goodies...) can't be changed. Neither can the sounds associated to objects be changed.

The pictures are located in the 'pics' directory. There are two pictures, named 'gameboard.xpm' and the other one 'masks.xpm'. The first one holds the gameboard and the grid where the user can pick objects. The second one contains the masks of those pictures, used to delimitate their borders and, sometimes, to give them some transparency (spectacles). There is also a text file in this directory, named 'layout.txt'. One can find there - and change - all information related to the positions of the pictures and masks of objects, define new objects, and assign sounds to objects. The program needs not beeing recompiled when changing the number and position of objects.

Here comes the structure of layout.txt. It only contains integer numbers in decimal form, separated by whitespace, and followed by comments. The comments are ignored.

The first line describes the area (gameboard) where objects can be dropped to. The first four numbers indicate the position of the 'landing area' (left, top, right, bottom), whereas the fifth number indicates the sound associated with it (defined in source file 'categories.h').

The second line indicates the number of texts that follow on the next lines. Those texts cannot be modified, but they can be drawn somewhere else on the gameboard.

The next lines describe the position of the texts describing the categories of objects, one text per line. The first four numbers indicate the position of the text (left, top, right, bottom), whereas the fifth number indicates the number of the text to draw (defined in source file 'categories.h').

Then comes the number of objects described in the next lines. Change this number if you want to add or remove objects.

The last lines describe the position of the pictures (in 'gameboard.xpm') and masks (in 'masks.xpm') of the objects, and the sound associated with them. The first four numbers are the coordinates of the rectangle (left, top, bottom, right) of the picture, the next four one are the coordinates of the rectangle (same order) of the mask, and the last one is the sound number (defined in source file 'categories.h'). Several objects can be associated with the same sound.

### For translators

Besides the usual .po files mechanism, translators have to know that the sounds can be localized too. If the various translators have recording devices, they can register their voice and store it into .wav files in a new subdirectory of the sounds directory. Then they can translate the sound file name in the .po file.

For example, if destination language is italian, translators can register their voice in .wav files located in /opt/kde/share/apps/ktuberling/sounds/it. Then they can translate file names like "en/hat.wav" to names like "it/capello.wav".

### For programmers

KTuberling isn't really difficult to extend for programmers.

#### C++ classes

TopLevel

  Top-level window and basic program management

ToDraw

  Description of one of the graphical "objects" to be drawn

#### .tuberling files structure

A .tuberling file holds all the necessary data to redraw a tuberling. It can be edited with an ordinary text editor.

There is one graphical object per line, in the order that is used to draw them. Each line contains 5 numbers: the identifier of the object, and the rectangle where it should be drawn (left, top, right, bottom). The numbers are separated by whitespaces.

## Epilogue

### Credits

- John Calhoun - Original idea, pictures and english sounds

- Eric Bischoff ebisch@cybercable.tm.fr - KDE Programming

- François-xavier Duranceau duranceau@free.fr - Tests, advice and help

- Peter Silva peter.silva@videotron.ca - Proofreading of the documentation

This game is dedicated to my little daughter Sunniva Bischoff

Thanks to Apple Computer and to the Linux PPC project for having made ports of Linux to the Macintosh. KTuberling would never have existed without that!

### License

ktuberling is published under the terms of the GNU General Public License (GPL). There is no warranty that this program works or for whatever.