The KGeography Handbook

Anne-Marie MahfoufKushal Das

The KGeography Handbook

2

Contents

1 Introduction 5

2 Quick Start to KGeography 6

3 Using KGeography 13

3.1 More KGeography features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 How to make maps 15

4.1 Helper tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Description file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.3 Map file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.4 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.5 How to test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.6 Non political maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5 Command Reference 185.1 The main KGeography window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5.1.1 The File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.1.2 The View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.1.3 The Settings Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5.1.4 The Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Configuration 20

7 Credits and License 21

Abstract

KGeography is a geography learning tool by KDE. Right now it has seven usage modes:

• Browse the maps clicking in a map division to see its name, capital and flag

• The game tells you a map division name and you have to click on it

• The game tells you a capital and you have to guess the division it belongs to

• The game tells you a division and you have to guess its capital

• The game shows you a map division flag and you have to guess its name

• The game tells you a map division name and you have to guess its flag

• The game shows an empty map and you have to place divisions on it one by one

The KGeography Handbook

Chapter 1

Introduction

KGeography is a geography learning tool by KDE. It allows you to learn about the political di-visions of some countries (divisions, capitals of those divisions and their associated flags if thereare some).

5

The KGeography Handbook

Chapter 2

Quick Start to KGeography

When you run KGeography for the first time, it first asks you to choose a map to start with.

TIPYou can filter the map list using Filter Maps text field. Just enter a few first letters of the map name tonarrow down the list to a few matches.

Here we choose Canada

6

The KGeography Handbook

And KGeography main window appears with the map of Canada:

You can then choose what type of learning or testing you want to do by looking at the menu onthe left:

7

The KGeography Handbook

Explore Map: a left mouse button click on an area of the map will display information about thatarea, if you click on the small info icon on the popmap, it will open the wikipedia page for thatdivision in the system’s default browser:

Location of Provinces or Territories: you are first asked how many questions you want

8

The KGeography Handbook

Then you are asked to click on a specific province:

When you finish all the questions, a result dialog is shown with your correct and uncorrect an-swers:

Place Provinces or Territories in the Map: the cursor takes the shape of a province and you haveto place it in the map:

9

The KGeography Handbook

Provinces or Territories by Capital: you are asked to find the name of a province among a choiceof 4 given its capital:

And the results are displayed when the test is finished:

10

The KGeography Handbook

Capitals of Provinces and Territories: you have a capital and four province names and you mustchoose the correct one. As before, at the end a result dialog is shown.

Provinces or Territories by Flag: a flag is shown and you must find the province it belongs to.

Flags of Provinces and Territories: a province name is given and you must find the correct flagamong four.

11

The KGeography Handbook

12

The KGeography Handbook

Chapter 3

Using KGeography

KGeography displays information about some countries and tests you about those information.

3.1 More KGeography features

Another feature of KGeography is the possibility of zoom on a map.

13

The KGeography Handbook

You can click the Zoom button and then draw a rectangle to zoom in a part of the map. While inzoom mode, you can press right mouse button to go back to the original map size (the OriginalSize action has the same effect). Use the scroll bars, the arrow keys or the mouse wheel to movearound the zoomed map or use the Move action that will allow you to drag the map using leftmouse button. The Automatic Zoom feature will make the map as big as possible.

14

The KGeography Handbook

Chapter 4

How to make maps

A map in KGeography is made by two files, one is the image of the map and the other one is itsdescription.

4.1 Helper tool

You can find here a tool (made by Yann Verley) which helped him with the map of France. Tofind out its usage, simply execute it and read the help message. It basically creates the .kgm filefrom a plain text file and creates a file with the colors it has assigned to each division, so you canfill the map according to them.

There is another tool colorchecker.py written by Albert Astals Cid. You need PyQt4 to run this.Just run this with the .kgm filename as argument (you also need the .png file of the map in thesame folder). This will tell you if any pixel on the map has a different color which is not definedin the .kgm (description) file.

TIPPlease read also the tutorial How to add maps on the KGeography website.

4.2 Description file

The description file is needed and its file extension is .kgm. It should begin with <!DOCTYPEkgeographyMap>, followed by <map> and end with </map>.

Inside of those tags there should be:

• <mapFile> and </mapFile>: the name of the file (without any path) containing the mapimage, e.g. ‘europe.png’.

• <name> and </name>: the name of map, e.g. ‘Europe’.

• <divisionsName> and </divisionsName>: the general name of divisions in this map, that is,Provinces, States, Countries, etc.

• A <division> and </division> for each division in the map.

Each division has these tags:

15

The KGeography Handbook

• <name> and </name>: the name of the division, e.g. ‘Albania’.

• <capital> and </capital>: the name of the capital of the division, e.g. ‘Tirana’.

• <ignore> and </ignore>: can be set to yes, allowClickMode, allowClickFlagModeand no. If this tag is set to yes then the division will be ignored when asking for divisions inthat map. It is then as if this division does not exist in KGeography quiz modes. If this tag isset to allowClickMode then KGeography will ask for the division in the Location of ... modebut not in other quiz modes. If this tag is set to allowClickFlagMode then KGeography willask for the division in the Location of ... mode and in the flag related quizes but not in otherquiz modes. Setting this tag to no means the division will appear in all modes (browse andquizzes). This tag is optional and when there is no <ignore> tag that means as it is set to no.For example ‘Algeria’ has this tag set to yes in the ‘Europe’ map which means that ‘Algeria’will not be part of any quiz in the ‘Europe’ map.

• <flag> and </flag>: the file (without any path) containing the flag of the division, e.g.‘albania.png’. This tag is optional. Not needed for the divisions whose <ignore> tag is set toyes.

• <color> and </color>: the color the division has in the map.

• <falseCapital> and </falseCapital>: There can be any number of falseCapital pairs, theyare used to provide a list of false answers to the capital question instead of choosing the falseanswers amongst the other divisions capitals.

The color is defined using three tags:

• <red> and </red>: red component of the color. Valid values are between 0 and 255.

• <green> and </green>: green component of the color. Valid values are between 0 and 255.

• <blue> and </blue>: blue component of the color. Valid values are between 0 and 255.

TIPIt is convenient to create 2 or 3 false divisions like ‘Water’, ‘Frontier’ and ‘Coast’ and set them with the<ignore> tag set to yes. Don’t forget not to set color for any ‘Frontier’ 0,0,0 in RGB. Pleasemake it something like 1,1,1 so that a border outline comes while placing any division on the map.

IMPORTANTAll names (capitals and divisions) must be in English.

4.3 Map file

The map file is quite simple but laborious to create. It has to be in PNG format. You can findsome maps to transform at Cia Reference Maps. If no map fits your needs you can download thepolitical world map, take a screenshot of it and work from it. Each division in the map shouldhave one and only one color. To achieve this you can use image processing programs like TheGimp and Kolourpaint.

4.4 Flags

If you have used the <flag> tag you should provide the flag files. They have to be in PNGformat and better if they are 300x200 pixels and you provide a SVG file for it. To obtain SVG flagsof almost all countries in the world and some other divisions, you can consult the Sodipodi flagscollection.

16

The KGeography Handbook

4.5 How to test

Before sending your map to Albert aacid@kde.org, you should test it to see it has no errors. Toachieve that, you have to do the following:

• Put the map description and map image file in $XDG_DATA_HOME /share/apps/kgeography/

• Put the flag PNG files (if any) in $XDG_DATA_HOME /share/apps/kgeography/flags/

Once that has been done you should be able of opening your map from inside KGeography.

If you don’t know which is your $XDG_DATA_HOME, type qtpaths --paths HomeLocation ina shell.

TIPUse the colorchecker.py tool from the helper tools to check if any extra color left on the map which isnot defined on the .kgm file.

4.6 Non political maps

Is it possible to do non-political maps? Yes, it is!

Of course, the division concept can be extended to a river or a mountain. During the creation ofthe map, you should keep in mind that most times the river or mountain will be too small thatyou should provide an additional clicking area. In this example the river would have the maroonarea and color <20,76,34> as its identifier.

17

The KGeography Handbook

Chapter 5

Command Reference

5.1 The main KGeography window

5.1.1 The File Menu

File → Open Map... (Ctrl+O)

Open the choose map dialog. If you type quickly enough the first letters of the map youlook for will select the first map that matches.

File → Quit (Ctrl+Q)Quits KGeography

5.1.2 The View Menu

View → ZoomGoes in zoom mode, then draw a rectangle to zoom in a part of the map

View → Original Size

Sets the map back to its original size as defined in the map file. A right mouse button clickin zoomed mode performs the same action

View → Automatic ZoomSets the map to automatic zoom using as much space as possible when resizing the KGeog-raphy window

View → MoveMoves the current map. This item is only enabled, if you have zoomed into the map.

5.1.3 The Settings Menu

KGeography has the common KDE Settings menu items, for more information read the sectionabout the Settings Menu of the KDE Fundamentals.

18

The KGeography Handbook

5.1.4 The Help Menu

KGeography has a default KDE Help menu as described in the KDE Fundamentals with twoadditional entries:

Help → Disclaimer

Displays a disclaimer about the accuracy of maps, flags and translations used by KGeogra-phy.

Help → Map author

Displays the name of author who created the current map.

19

The KGeography Handbook

Chapter 6

Configuration

Question Alignment

Determines the position of the questions in the window, default is Top-left.

Wait for ValidationIf enabled the user will have to press Accept after choosing an answer.

Focus follows MouseIf enabled pressing Space will trigger the button under the mouse pointer.

Map divisions colors

You can choose if you always want to keep the same colors (default) or if you want to userandom colors: with this option random colors are assigned to the divisions in the map.This helps the user to focus and learn the division shapes and not the division colors.

20

The KGeography Handbook

Chapter 7

Credits and License

KGeography

Program copyright 2004-2008 Albert Astals Cid aacid@kde.org

Documentation Copyright (c) 2005 Anne-Marie Mahfouf annma@kde.org 2008 Kushal Daskushaldas@gmail.com

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.

21