# The &khangman; Handbook

## Introduction

&khangman; is a game based on the well-known hangman game. It is aimed for children aged 6+. The game has four levels of difficulty: Animals (animals words), Easy, Medium and Hard. A word is picked in random, the letters are hidden, and you must guess the word by trying one letter after another. Each time you guess a wrong letter, part of a picture of a hangman is drawn. You must guess the word before being hanged! You have 10 tries.

My son Joachim, who was at the time 9 and a half years old, gave me the idea of this game in June 2000.

## Using &khangman;

Here's a screenshot of &khangman; when you start it for the first time &khangman; screenshot

Here you can see &khangman; as it is the first time you run it. Level is Easy, language is default (English here), there is no background theme and the hangman pictures are not transparent. Any changes in level, language or background mode are written in the configuration file and restored in your next game.

Please note how easy it is to change the level and the background mode, just click on the combo boxes on the toolbar. Getting a new word and quitting the game are also easily done by clicking on the corresponding buttons on the toolbar.

### General usage

A word is displayed, hidden. You know how many letters there are in the word. You have to guess the word by trying one letter after another. The word is picked at random and it is not the same as the previous word.

All words are nouns (no verbs, no adjectives, &etc;).

It is not important whether you type in lowercase or uppercase. The program converts all input into lowercase except for German words which begin with an uppercase letter. The program does that automatically.

The current level and current language are displayed in the status bar.

Each time you guess a letter that is not in the word, another part of the hangman is drawn. You have 10 tries to guess the word. After that, the correct answer is displayed.

There are 4 levels: easy, medium, hard and animals, plus levels for other topics in some languages. The program scans for all data files in all languages.

In the easy level, the words are quite simple and related to everyday life. It is suitable for children from 6 to 9. The animals level contains only names of animals so they are easier to find. Some of them are easy, others are more difficult. In the medium level, the words are longer and more difficult. It is suitable for ages 9+. The hard level is just that, hard, &ie; the words are difficult to spell and not very well known. This level is challenging, even for adults.

After a word is guessed (or the hangman is completed), you are prompted for another word and you can either use the Y or N keys or the mouse to answer yes or no. If you say No, the game quits. If you say Yes, another word is ready to be guessed.

You type the letter you want to try in the field (the mouse cursor is ready in the field) and you hit the &Enter; key. If the letter belongs to the word, it takes its place, as many times as it appears in the word. If the letter does not belong to the word, it goes in the Misses field and a further part of the hangman is drawn on the right. You have ten tries and after that you lose and the correct word is displayed.

During the game, you can choose to start a new game by going in the Game menu and choosing New or clicking on the New icon on the toolbar. You can also change the level with the level button on the toolbar (this will bring you a new word for the new level).

Future improvement will allow you to create your own words file or to load a file different from the four included ones.

You can play &khangman; in thirteen languages: Brazilian Portuguese, Catalan, Czech, Danish, Dutch, English, Finnish, French, German, Italian, Portuguese, Spanish and Swedish. You can easily change the Language by going in the Languages menu and choosing another language.

Please note that you can now type the special characters in a language by displaying the Special Characters Toolbar. This toolbar holds buttons with an icon of each special character per language like é in French for example. Clicking on such a button will write the corresponding letter in the input line and you validate your choice with Enter. You can of course also use the keyboard layout corresponding to the language. This toolbar can be shown or hidden. The setting is restored next time you play &khangman;.

Please note that for Czech special characters you will need a font that supports these characters so you can see them displayed. Choosing Arial in KDE Control Center as a general font and adjusting all fonts will work fine.

### A few tips

Try to guess the vowels first. Then have a go with the most common consonants: l, t, r, n, s

When you see io, try n after that, in French and English.

In Brazilian Portuguese, Catalan, Spanish and Portuguese, the accented vowels can be discovered when you type the non accented corresponding vowel. For example, all the accented a are displayed in the word when you type a. This is when Settings Type Accented Letters is not checked. When Settings Type Accented Letters is checked, then you have to type the accented letters yourself. When you type a, only a is displayed and you have to type for example ã for this letter to be displayed.

Did you know? In English, the most common letter is e (12.7%), followed by t (9.1%) then a (8.2%), i (7.0%) and n (6.7%).

## Menubar and toolbars

### The Main &khangman; Window

The Game menu has 2 items: New and Quit.

New brings you a new game, &ie; a new word to guess, in the same level you already are. Quit quits the game by closing the main window and writing the actual settings in the configuration file.

The Languages menu has thirteen menu items: Brazilian Portuguese, Catalan, Czech, Danish, Dutch, English, Finnish, French, German, Italian, Portuguese, Spanish and Swedish. As default, if your &kde; language is one of those thirteen, then it is set as default otherwise English is chosen. After your first game, the language you set up the last time you used &khangman; is restored.

The Settings menu allows you to configure &khangman; easily. First, Toolbars and Show Status bar give you the possibility to hide/show the Toolbars and Status bar.

There are two toolbars: the main one which is the one on top with the buttons and combo boxes and the Characters toolbar which, when it is shown, is on the bottom. This toolbar has buttons with the special characters for each language: accented letters and other special characters. This allows users to easily play in another language without having to configure a new keyboard layout. You click on a special letter and it is displayed as the letter to try. Pressing &Enter; will make the program see if the letter is present in the word or not. The toolbar can be hidden if you don't want it. This is saved in the configuration file so if the toolbar is hidden, it will be hidden next time you run &khangman;.

It is of course possible to move the toolbars around. Put the mouse cursor on the small handle on the left of the toolbar, press the &LMB; and drag the toolbar to position it on the screen where you want it. If you point the mouse on one of the toolbars and press the right mouse button, a context menu appears to let you choose different options for the toolbar.

Configure Shortcuts... is a standard &kde; setting that allows you to choose different shortcut keys for different actions. For example, &Ctrl;Q is the standard shortcut for Quit.

Configure Toolbars... is also a standard &kde; menu item that allows you to add or suppress items from the toolbar. When Full-Screen Mode is checked, it brings you in full-screen mode, with only the toolbar on top and &khangman; occupies the whole screen. On the main toolbar, the icon Back to Normal Size allows you to come back from full-screen mode to the window size you had before.

Transparent Pictures gives you the choice of having the hangman pictures transparent or not, depending on whether it is checked or not.

Softer Hangman Pictures gives you the choice of having the last of the hangman pictures softer. That means that the man is not hanged but he is holding the rope with his hand. This is more suitable for younger children.

Type Accented Letters is a mode only available in Catalan, Brazilian-Portuguese and Spanish. If it is checked, then the user has to type accented letters like ã to get them shown in the word. If that option is not checked, then a normal vowel will discover all the accented ones, for example trying a will discover ã and other accented a if present in the word.

Enable Hint is available only in French and Italian. If you check that option in those two languages, you can &RMB; click anywhere on the game and get a hint shown for four seconds. This hint should help you to guess the word.

Please note that transparent pictures for the hangman are not enabled in No Background mode. Transparency is only available with a picture background. By default, transparency is enabled.

&khangman; blue theme &khangman; blue theme

Here you have &khangman; with the Blue theme, transparent hangman pictures, Catalan language and level Easy. The Characters toolbar is shown here.

The level is chosen with a combo box and you have easy, medium, animals and hard. Easy is related to common objects a child aged six or seven knows. Medium regards nouns a bit more challenging, hard is quite difficult and animals is only animals nouns.

All words are nouns. No verbs, no adjectives. The chosen level is then displayed on the status bar.

Only letters are allowed to be typed in the field.

## Command Reference

### Menus and shortcut keys

#### The Game Menu

&Ctrl;N Game New

- New game (&ie; new word)

&Ctrl;Q Game Quit

- Quits &khangman;

#### The Languages Menu

Languages Languages

- Choose the language for the words

#### The Settings Menu

Settings Toolbars Show Main

- Toggle the Main Toolbar

Settings Toolbars Show Characters

- Toggle the Characters Toolbar

Settings Show Status bar

- Toggle the Status bar

&Ctrl;T Settings Transparent Pictures

- Toggle the transparency for the hangman pictures

&Ctrl;S Settings Softer Hangman Pictures

- Toggle softer/original hangman pictures

&Ctrl;A Settings Type Accented Letters

- Allow to type accented letters on their own (in Brazilian Portuguese, Catalan, Portuguese and Spanish)

&Ctrl;H Settings Enable Hint

- Allow to view a hint on right-click (only in French and Italian)

&Ctrl;&Shift;F Settings Full-Screen Mode

- Toggle the full-screen mode

Settings Configure Shortcuts...

- Configure the keyboard keys you use to access the different actions.

Settings Configure Toolbars...

- Configure the items you want to put in the toolbar

#### The Help Menu

&help.menu.documentation;

## Developer's Guide to &khangman;

### How to add words in a new language for the game

Thanks to Stefan Asserhäll, it is very easy to add a new language directly to the game. The procedure described here can also be found in the `khangman` source folder in the file `README.languages`. However, as there are already thirteen languages, it will be difficult to add others as the menu will be too long. So please follow the procedure below but instead of committing your files you send them to me tarred and gzipped. That way I'll make your language available on the &khangman; web page. Next &khangman; release (with &kde; 3.3) will have a wizard to easily download and install new languages.

Download the latest cvs version of &khangman;. The words are stored in 4 separate files, one for each level. The files are in `/khangman/data/language_code`. The file `easy.txt` is for level easy, the file `medium.txt` is for level medium, the file `animals.txt` is for level animals and the file `hard.txt` is for level hard.

1. Enter the following commands in a &konsole; to create the folder and files for the new language:

       ./add_language language_code

   Here you must replace `language_code` with your language code.

2. Edit all indicated text files in the new folder with a text editor, and replace each word with a translated word. It is not really important that the exact meaning is preserved, but try to keep the length and level of difficulty roughly the same.

   You can just translate the words but you can also adapt them following the level and add new words if you want. For example, table is in level easy in English but in your language, it can be level medium. Feel free to adapt the files to your language needs. The number of words in a file is not important, you can add some if you want.

   Remember that all words are nouns.

   Note that you must use UTF-8 encoding when editing the files. If your editor cannot do this, try using &kwrite; or &kate;. When opening a file in &kwrite; or &kate; you can select utf8 encoding with the combo box at the top of the file open dialog.

   Please keep the actual english filenames in your `language_code` dir.

3. Enter the following command to install the new data files:

       make
       make install

   You may have to become `root` to run `make install`, depending on your installation.

4. Run the game and check that your language has been added:

       khangman

5. Commit the new language files with the following command:

       cvs commit -m "Added new language name_of_your_language"

If you want to have hints in the new language, then you will have more work to do. You will have to use the kvtml format and the best thing to do is to have a look at the French or Italian data. The tag `o` is for the word and `t` for the hint. Try to match the hint with the level of difficulty. The level Easy will require an easy hint but the level Hard will require the definition in the dictionary. Try not to use words of the same family in the hint, that would give the word away too easily!

An example of a kvtml file is as follow:

    <?xml version="1.0"?>
    <!DOCTYPE kvtml SYSTEM "kvoctrain.dtd">
    <kvtml>
    <e>
    <o>cane</o>
    <t>è il tuo animale domestico preferito</t>
    </e>
    ...
    ...
    </kvtml>

### Planned Features for &khangman;

As the number of languages increases for the data, it will be necessary to stop adding them in the program. We plan to have only a few languages such as English, French, German and Spanish shipped with &khangman; and the other languages will be available in the i18n module and as download. &khangman; will make use of the `KNewStuff` class to have a wizard that will allow the user to download and install easily some additional languages. This will also be done for &klettres; and &kstars; as we don't want to increase the size of the &package; module.

Another planned feature is of course to have hints in every language.

What can also be done is to use other kvtml files like the ones that are on the KDE-Edu website to play &khangman;. For example, imagine you can play the capitals of the world, the hint will tell you the country and you have to guess the capital. Or learn words in another language, the hint is the word in your language, the word to guess is the translation in the new language.

## Questions and Answers

&reporting.bugs; &updating.documentation;

I have an error message telling me the pictures cannot be found.

The game installs by default in `/usr/local/kde` so add `/usr/local/kde/bin` to your path and set the `KDEDIR` variable to `/usr/local/kde` before running the game. An easy way is to configure &khangman; with the option `--prefix`=$`KDEDIR` where $`KDEDIR` is where the rest of &kde; is installed. This could vary widely, depending on the distribution and operating system you.

&khangman; does not start correctly after I upgraded to one of the &kde; 3.2 versions

There might be a problem due to the change of the configuration file. Please remove the `khangmanrc` file in your `$HOME/.kde/share/config` folder.

## Credits and License

&khangman;

Program copyright 2001-2003 Anne-Marie Mahfouf annma AT kde DOT org

Contributors:

- Hangman graphics: Renaud Blanchard kisukuma AT chez DOT com

- Sounds: Ludovic Grossard ludovic.grossard AT libertysurf DOT fr

- Blue theme, icons and code: Primoz Anzur zerokode AT yahoo DOT com

- Swedish data files, coding help, transparent pictures and i18n fixes: Stefan Asserhäll stefan DOT asserhall AT telia DOT com

- Nature theme: Joe Bolin jbolin AT users DOT sourceforge DOT net

- Softer Hangman Pictures: Matt Howe mdhowe AT bigfoot DOT com

- Spanish data files: eXParTaKus expartakus AT expartakus DOT com

- Danish data files: Erik Kjaer Pedersen erik AT mpim-bonn DOT mpg DOT de

- Finnish data files: Niko Lewman niko DOT lewman AT edu DOT hel DOT fi

- Brazilian Portuguese data files: João Sebastião de Oliveira Bueno gwidion AT mpc DOT com DOT br

- Catalan data files: Antoni Bella bella5 AT teleline DOT es

- Italian data files: Giovanni Venturi jumpyj AT tiscali DOT it

- Dutch data files: Rinse rinse AT kde DOT nl

- Portuguese data files: Pedro Morais morais AT kde DOT org

- Coding help: Robert Gogolok robertgogolok AT gmx DOT de

- Coding help: Benjamin Meyer ben AT meyerhome DOT net

- Code fixes: Lubos Lunàk l.lunak AT kde DOT org

- Code fixes: Albert Astals Cid tsdgeos AT terra DOT es

Documentation copyright 2001-2003 Anne-Marie Mahfouf annma AT kde DOT org

&underFDL; &underGPL;

## Installation

### How to obtain &khangman;

&install.intro.documentation;

### Compilation and installation

&install.compile.documentation;
&documentation.index;