# The &khangman; Handbook

## Introduction

&khangman; is a game based on the well-known hangman game. It is aimed at children aged six and over. The game has four levels of difficulty: Animals (animals words), Easy, Medium and Hard. A word is picked at 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.

## 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 Animals, language is default (English here, the default is your current &kde; language if the data exists), the theme is "Sea". Any changes in level, language or theme (background) are written in the configuration file and restored in your next game.

Please note how easy it is to change the level and the theme, 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 chosen and its letters are displayed as an underscore (_) symbol. You know how many letters there are in the word. You have to guess the word by trying one letter after another. You enter the letter in the text box and you either press the Enter key or click on the Guess button to see if the letter belongs or not to the word.

The word is picked at random and it is not the same as the previous word.

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

Usually, it is not important whether you type in lowercase or uppercase. The program converts all input into lowercase (except for German words beginning with an uppercase letter). The program does that automatically.

The current level and current language are displayed in the statusbar.

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 text box (the mouse cursor is ready in the text box) 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 (in &kde; 4) will allow you to create your own words file.

### Playing in different languages

You can play &khangman; in twenty-four languages: Brazilian Portuguese, Bulgarian, Catalan, Czech, Danish, Dutch, English, Finnish, French, German, Hungarian, Irish (Gaelic), Italian, Norwegian (Bokmål), Norwegian (Nynorsk), Portuguese, Spanish, Serbian (Latin and Cyrillic), Slovenian, Tajik, Swedish, Russian and Turkish.

By default, after the first installation of &khangman;, only English and your &kde; language if it is one of the above and if you have the corresponding kde-i18n package will be installed. For example if you are a Danish user and if you have &kde; in Danish, in Languages you will see two items: English and Danish and Danish will be the default.

You can still play &khangman; in other languages. It is very easy to add new data in &khangman;. All you need is a working Internet connection. You click on the File menu and then on Get Words in New Language.... A dialog appears, similar to this one:

The Get New Words dialog for &khangman; The Get New Words dialog for &khangman;

Click on the language name you want to install and then on the Install button. If the language is successfully installed, a green tick is displayed in front of the language name. You click on the Close button to close the Get New Words dialog (if you want another language, you get repeat these steps).

You can then easily change the language by going in the Languages and choose the new 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 you need Arial and URW Bookman fonts in order to display the special characters correctly in some languages. Provided you have those fonts installed, &khangman; will automatically use them. If you see small squares instead of letters, then you may not have one of these fonts installed. Type `fonts:/` into the &konqueror; address bar to check which fonts you have installed.

### A few tips

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

corresponding: 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 Type accented letters on the Languages page of &khangman;'s configuration dialog is not checked. When 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 3 items: New, Get Words in New Language... and Quit.

New brings you a new game, &ie; a new word to guess, in the same level you already are. Get Words in New Language... will display the Get New Stuff dialog to allow you to download data in a new language. Quit quits the game by closing the main window and writing the actual settings in the configuration file.

The Level menu allows you to choose the level, &ie; the difficulty of the word to guess.

The Languages menu allows you to change the language the words are displayed in.

The Look menu proposes two themes: the Sea Theme and the Desert Theme. The background and the font colors changes for each theme.

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

There are two toolbars: the main one which is the one on top with the buttons and combo boxes and the Special 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 dialog 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.

&khangman; Desert theme &khangman; Desert theme

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

The level is chosen with a combo box in the toolbar or via the Level menu in the menubar. The available levels are 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 statusbar.

Only letters are allowed to be typed in the text box.

### Available Settings

A toolbar is provided for quick access to some settings. You can click on a button to have a new game (i.e. a new word), or to quit the game. The level and the theme are easily changed via 2 combo boxes on the toolbar.

In Settings, Configure &khangman;... you will find tree pages. The first one is for General settings.

#### General Settings

&khangman; General settings &khangman; General settings

Require more guesses for duplicate letters: this is unchecked as default. When unchecked, if you try the letter "a" and the word has several as, they will be all displayed. For example if the word is "potato" and you try "o", both os will be diaplayed. If you check this option however, only the first "o" will be displayed and you will have to try it one more time to display the second "o" in "potato". This increases the difficulty.

Do not display the 'Congratulations! You won!' dialog: the default is unchecked, that means that when you win a game, a message box will be displayed to tell you that you won and ask you if you want to play again. If you check this option, this dialog is not displayed anymore, instead a new game starts directly after 3 seconds.

In the Sounds section, if you check Enable sounds then a sound will be played on new game and another sound will be played when you win a game.

#### Languages Settings

The Languages Settings tab allows you to set some settings specific to some languages. If the settings are not available for the language you are playing in then those settings will be grayed and disabled so you cannot choose them.

&khangman; Languages Settings &khangman; Languages Settings

Some languages also have hints to help you guess the word. The hint is shown by a right-click and gives a short definition of the word to guess. If this setting is enabled and if you check the option Show hints, 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 more easily.

Type accented letters is available for Brazilian Portuguese, Catalan, Portuguese and Spanish in &khangman;'s configuration dialog. If you check Type accented letters then you will have to type all accented vowels (like ã). If this remains unchecked, when you type any vowel, all accented vowels will be displayed as well.

#### Timers Settings

The Timers Settings tab allows you to Set the time for displaying the hint and to Set the time for Already Guessed Letter tooltip.

&khangman; Timers Settings &khangman; Timers Settings

Set the time for displaying the hint: allows you to set a greater time for showing the hint label. It is necessary to increase the time for younger children for example as they read more slowly than adults.

Set the time for displaying the Already Guessed Letter allows you to increase or decrease the time for displaying the Already Guessed Letter tooltip. This tooltip is a label which appears when you tried a letter that was already tried. Some people will want not to see it for long while children will need time to understand it and thus will need to set the display for a longer duration.

## Command Reference

### Menus and Shortcut Keys

#### The Game Menu

&Ctrl;N Game New

- New game (&ie; new word)

&Ctrl;G Game Get Words in New Language...

- Display the KNewStuff dialog which lists all the data available in the different languages.

&Ctrl;Q Game Quit

- Quits &khangman;

#### The Level Menu

Level Animals

- Choose the list of animals words to guess

Level Easy

- Choose the list of easy words to guess

Level Medium

- Choose the list of medium difficulty words to guess

Level Hard

- Choose the list of difficult words to guess

#### The Language Menu

Language English

- Choose the English language for the words to guess.

  All other installed languages are displayed as items in this menu as well.

#### The Look Menu

Look Sea Theme

- Choose the Sea background picture and associated font colors

Look Desert Theme

- Choose the Desert background picture and associated font colors

#### The Settings Menu

Settings Toolbars Main (&khangman;)

- Toggle the Main Toolbar

Settings Toolbars Special Characters (&khangman;)

- Toggle the Characters Toolbar

Settings Show Statusbar

- Toggle the statusbar

Settings Configure Shortcuts...

- Open standard &kde; setting dialog that allows you to choose different shortcut keys for different actions.

Settings Configure Toolbars...

- Configure the items you want to put in the toolbar

Settings Configure &khangman;...

- Display the &khangman; settings dialog

#### 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`. Please follow the procedure and then send me the files tarred and gzipped to annemarie.mahfouf@free.fr.

The twenty four available languages so far by code are: bg ca cs da de en es fr fi ga hu it nb nl nn pt pt_BR ru sl sr sr@Ltn sv tg and tr. If your language code is not among those, you can proceed further.

Most of this data should be completed to include hints, please see below. Complete data: bg de fr en it only have hints so the other above languages must be updated as soon as possible.

Be sure you are working with the latest svn trunk sources of &khangman; by issuing a

    svn up khangman

in the kdeedu module. Then

    cd kdeedu/khangman

The words are stored in 4 separate files, one for each level. The files are in `/khangman/data/en`. 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.

English is the default and thus the only language to be shipped with &khangman;. All other languages data are put in the correct kde-l10n.

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. The files now use the kvtml format. The tag `o` is for the word and the tag `t` is 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>

3. Edit all indicated text files in the new folder with a text editor, and replace each word inside the `o` tag with a translated word and each hint inside a `t` with a translated hint. 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 include words with white space or - in them, in that case the white space or the - will be shown instead of the _. Please contact &Anne-Marie.Mahfouf; annemarie.mahfouf@free.fr if there is anything special related to your language so I can adapt the code to it (especially the special and accented characters).

   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.

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

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

       khangman

6. Instead of committing your files, please sent them to &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; tarred and gzipped. As there are now twenty three languages, a wizard (KNewStuff) is now included in &khangman; to easily download and install new languages that are placed on the website. This is done to reduce the size of the kdeedu module and it will also be done in &klettres;, &kstars; and maybe &ktouch;. Please contact Anne-Marie by email if you need further information.

   When you send me the files, please don't forget to mention any special characters used in your language (put them in a text file, one per line and add this file in the tarball) and please mention any other specificity.

   Please never commit files in a BRANCH as it might break the game.

Many thanks for your contribution!

### What is stored by &khangman; and where

When you get a new language via Game Get Words in New Language..., the new language data is stored in `$~/.kde/share/apps/khangman/data` in the language code folder. The available language dir names are also stored in the &khangman; config file in `~/.kde/share/config/khangmanrc`.

The provider name (i.e. the address of the website where to download the new languages) is stored in `$KDEDIR/share/apps/khangman/khangmanrc`.

The English language (default) and the user language from his i18n package(s) (if available) are stored in `$KDEDIR/share/apps/khangman`.

In the configuration file, stored for each user in his `~/.kde/share/config/khangmanrc` are saved all the game settings such as the background, last level played, ... plus the files that were downloaded from the KNewStuff dialog.

### Planned Features for &khangman;

A planned feature is of course to have more language data and also hints in every language. You can help for this in your own language if it is not done yet. Please contact me if you want to help with this, it's just a matter of translating the English words to your language (see How to add words in a new language for the game).

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 from an earlier version to the &kde; 3.5 version

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-2006 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

Contributors:

- Hangman graphics: Renaud Blanchard kisukuma@chez.com

- Sounds: Ludovic Grossard ludovic.grossard@libertysurf.fr

- Blue theme, icons and code: &Primoz.Anzur; &Primoz.Anzur.mail;

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

- Nature theme: Joe Bolin jbolin@users.sourceforge.net

- Softer Hangman Pictures: Matt Howe mdhowe@bigfoot.com

- Spanish data files: eXParTaKus expartakus@expartakus.com

- Spanish data hints: Rafael Beccar rafael.beccar@kdemail.net

- Danish data files: Erik Kjaer Pedersen erik@mpim-bonn.mpg.de

- Finnish data files: Niko Lewman niko.lewman@edu.hel.fi

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

- Catalan data files: Antoni Bella bella5@teleline.es

- Italian data files: Giovanni Venturi jumpyj@tiscali.it

- Dutch data files: Rinse rinse@kde.nl

- Portuguese data files: Pedro Morais morais@kde.org

- Serbian (Cyrillic and Latin) data files: Chusslove Illich chaslav@sezampro.yu

- Slovenian data files: Jure Repinc jlp@holodeck1.com

- Czech data files: Lukáš Tinkl lukas@kde.org

- Tajik data files: Roger Kovacs rkovacs@khujand.org

- Norwegian (Bokmål) data files: Torger Åge Sinnes torg-a-s@online.no

- Hungarian data files: Tamas Szanto tszanto@mol.hu

- Norwegian (Nynorsk) data files: Gaute Hvoslef Kvalnes gaute@verdsveven.com

- Turkish data files: Mehmet Özel mehmet_ozel2003@hotmail.com

- Bulgarian data files: Radostin Radnev radnev@yahoo.com

- Irish (Gaelic) data files: Kevin Patrick Scannell scannell@slu.edu

- Coding help: &Robert.Gogolok; &Robert.Gogolok.mail;

- Coding help: Benjamin Meyer ben@meyerhome.net

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

- Code fixes: Albert Astals Cid tsdgeos@terra.es

- Usability study: Celeste Paul seele@obso1337.org

Documentation copyright 2001-2005 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

&underFDL; &underGPL;

## Installation

### How to obtain &khangman;

&install.intro.documentation;

### Compilation and installation

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