# The &kig; Handbook

## Introduction

&kig; is an application for Interactive Geometry. It's intended to serve two purposes:

- Allow students to interactively explore mathematical figures and concepts using the computer.

- Serve as a WYSIWYG tool for drawing mathematical figures and including them in other documents.

You can report problems in &kig; using the internal bug reporting tool (Help Report Bug), or just contact me at devriese@kde.org.

Since &kig; supports macros and locuses, it allows for some rather advanced macros to be defined. If you have created an interesting macro, that you think might be useful for other people, you can mail it to me at devriese@kde.org, so I can include it in the distribution (if you do this, it will be licensed under the terms of &kig;'s license, the GPL, so that other people can freely use and adapt it).

## Basic usage

### Constructing Objects

#### Constructing points

You can construct points in several ways:

- Select Objects Points Normal Point from the menubar or press the appropriate button in the toolbar. You can then construct a point by clicking on the desired position in the window.

  Actually, this works the same way for constructing other objects as well: click on the desired menubar entry or toolbar button and select the necessary objects to construct the object.

- Since you often need to construct points, simply clicking somewhere on the screen with the middle mouse button will construct a point for you, without going to a menu or button.

- You can construct points while you are building other objects in the background, optionally selecting them for the object you are building. For more on this, see the section below.

A point has been constructed A point has been constructed

#### Constructing Other Objects

Constructing objects other than points is normally done by selecting the appropriate entry in the Objects menu, or by clicking on one of the toolbar buttons.

Constructing a circle Constructing a circle

This will start the construction of the chosen object type. All of these types require arguments. For example, if you selected a circle by center and point, you will need to give it two points: one for the center, and one for the point on the circle.

To select these arguments, simply click on the object you want to use. If you move over an object that can be used to construct the object, a preliminary image will be shown of what the object will look like. For objects that require points as arguments, you can construct a new point at the current cursor position and select it by clicking the left mousebutton.

You can always cancel the construction of the new object by pressing the &Esc; button or by clicking on the Stop button (red octagon with an X) on the toolbar.

Constructing a circle. Constructing a circle

### Selecting Objects

Selecting objects can be done in two ways:

- Simply clicking on an object causes that object to be selected, clearing the current selection. If you don't want that behavior, hold down the &Ctrl; key while clicking on an object.

- By clicking and dragging on an empty spot on the screen, you can select all objects within the rectangle that is created. This action will clear the current selection. As in the previous case, holding down the &Ctrl; key prevents this behavior.

Selecting objects Selecting objects

### Moving Objects

To move objects, you must first select them.

When the objects you want to move are selected, you can start moving them by &LMB; clicking and dragging on any one of them. When you are done, simply release the &LMB;.

For some types of objects (mostly complicated Locuses), moving objects can be slow on older hardware. This is unfortunate, but inevitable, given the calculations involved.

If you &RMB; click one of the selected objects, and choose Move, movement of the mouse will move the object. When the object is moved to the desired position, another &LMB; click will stop the movement.

### Deleting objects

Deleting objects is done by first selecting them, and next doing either of these:

- Press the Delete key.

- Press the delete button on the toolbar.

- &RMB; click on one of the objects, and select Delete in the context menu that appears.

### Showing and hiding objects

In &kig;, objects can be hidden. This is done by selecting the objects, &RMB; clicking one of them, and selecting Hide in the context menu that appears..

For unhiding the objects, use the Edit Unhide all.... This will unhide all currently hidden objects.

### Undo/Redo

In &kig;, you can undo almost any change you do to the document. Just use the undo/redo buttons on the toolbar, or the appropriate shortcuts.

### Full Screen Mode

&kig; also has a Full Screen mode. To use it, click the appropriate button on the toolbar, or select View Full Screen.

To leave Full Screen mode, &RMB; click the screen on a place where there is no object present, and select Exit Full Screen Mode, or press the &Esc; key.

## &kig; Object Types

&kig; supports a rather large number of object types. Please note that not all of the available object types are shown in the toolbars, but that there are also some objects that you can only construct via the Objects menu in the menu bar. Of course, as with all &kde; applications, what appears in the toolbars is configurable. Try out the Settings Configure Toolbars... option if you want to do this.

## Advanced Usage

### Context Menus

&kig; has context menus for its objects. Try &RMB; clicking on an object to see a context menu appear. There are many options: for constructing other objects, setting colors, and even hiding, moving or deleting objects. Some objects have options of their own (⪚ you can redefine certain points to be constrained to a line where they previously weren't, &etc;). These options should be very straightforward to understand.

### Document context menus

&RMB; clicking on the document (&ie; not on an object) will present a popup that you can use to start constructing a new object, change the coordinate system used, show hidden objects, and even zoom in and zoom out of the document.

### Defining Macros

One of the more advanced features in &kig; is its support for macros. This allows you to define a new type of objects by combining other ones.

For example: Suppose you want to make a macro for constructing a circle from three points on it, then you would just construct three points, some perpendiculars and midpoints until you find the center, and construct the circle by the center you constructed and one of the previous points. The following image should make this a bit more clear.

Test running macros Test running macros

Next comes defining the macro. Select New macro from the Type menu, or click on the button on the toolbar. A wizard will appear and ask you to select the given objects. In our example, these are the three points. Select the three points (click on them for selecting, click again for unselecting) and click the next button to continue. Finally, select the last objects (only the circle in our example).

The macro wizard The macro wizard

After the previous steps were completed, click the next button to continue. Enter a name and optionally a description for your new type, and click the Finish button. Your macro type is now finished.

To use the new macro type, click its button on the toolbar or use the Objects menu. Building a macro object is just like constructing any other object.

Using your new type Using your new type

### Working with types

As you saw in the previous chapter, &kig; allows you to create your own objects. &kig; also makes sure that once you have created an object, it is saved on exit and loaded on startup. You do not have to manually save or load macro definitions. However, &kig; does allow you to do more with the macros. If you select Manage Types from the Types menu, you will see a dialog where you can edit your types. It allows you to delete types that are no longer used, export them to a file, or even load them from another file.

Edit Types Dialog The Edit Types Dialog

### Text labels

&kig; allows you to add text labels to a construction. This is very useful for showing names, explanations or other text in constructions. &kig; can also display variable information about objects (also known as properties).

To start constructing a text label, simply press the Text Label button in the &kig; toolbar or select Objects Other Text label in the menubar.

Next, you have to choose a location for the text label. You can either just select a random location on the screen, or choose to attach the label to another object.

Attaching a label to a circle... Attaching a label to a circle...

You now reach the text label dialog. Here, you can type in the text that you want to show in the new label, and click Finish. The label should now be present on your document.

The Text Label Dialog The Text Label Dialog

The previous example was a simple one, and limited to just text. However, there is also support for showing variable information about objects in a label (⪚ you can construct a label showing the text This segment is %1 units long. where %1 would be dynamically replaced with the length of a specific segment).

To do this, enter a text with a number of placeholders ( %1, %2 &etc;) in it. When you are finished, press the Next button to continue. If you want to change the text or variables later, you can go back using the Back button.

The wizard now shows the text you entered with all placeholders replaced by something like argument 1. Selecting what to show as a certain argument is done by first clicking the argument in question. Then click on the object about which you want to show information, and then select an interesting piece of information in the popup menu that appears. For instance, in the example above, you would click argument 1, click on the correct segment in the main &kig; window, and select the property Length. Afterwards, you can fill in the rest of the variable parts, or select another property for one of the variable parts if you wish to change it. When you are ready, click the Finish button to complete the construction of the text label.

Selecting a property for a variable part Selecting a property for a variable part

### Locuses

&kig; has support for geometrical locuses. A locus is a concept from high school math. Briefly put, it is the figure defined by all the points that a point moves over, when another point moves along its constraints. This may sound a little complicated, but in fact, it's not a difficult concept, as the following example demonstrates.

Consider the following geometrical construction: We draw a circle, and a point that can move over its surface (construct this point by positioning the cursor on a circle, and clicking the &MMB;. If you then try to move the resulting point, you'll see that you cannot move it off the circle). Then, we draw a segment from that point to the center of the circle, and the midpoint of that segment.

A simple locus construction A simple locus construction

Now if you move the point that is constrained to the circle, you can see that the second point moves along with it. If you would hold a pen above the second point, and you move the first point around the entire circle, a new circle, half the size of the other would be drawn. We'll see below that this is exactly what a locus does. The path that the second point travels while the first moves around the circle is what the locus will look like.

Actually constructing the locus is very easy. Click the locus button in the toolbar, or select Objects Other Locus from the menubar. Then select the constrained point as the moving point (the text Moving Point will appear as you move the mouse over it ), and the other as the dependent point. The locus will then appear.

## Scripting

&kig; allows the user to create custom types in the Python scripting language. This is a very advanced feature, and I know of only one other Interactive Geometry program that has similar functionality (the GNOME program &drgenius;).

Python Scripting in &kig; basically allows you to create your own way to define an object from certain parent objects. For example, if you are a math teacher, and you have some fancy way of calculating an interesting point of a conic, then instead of messing with complex constructions and macro's, you could just write down in Python code how the point is to be calculated and &kig; will show it for you.

Suppose you were not aware of the &kig; builtin MidPoint type, and you wanted to show the midpoint of two given points. You would then click on the Python Script button in the toolbar, or select Objects Other Script Object from the menubar. You are then presented with a wizard that allows you to proceed.

The Script Object Wizard The Script Object Wizard

The first thing you have to do is select the arguments for the script object. In our example, this means the two points of which we want to show the midpoint. Select them in the &kig; main window, and click Next to proceed.

Now you are presented with a text edit box where you can enter the code for you script object. Template code and some comments are already in place. It is important to make sure that your code is valid Python code. People familiar with Python will note that we are actually defining a Python function called `calc`. It is therefore necessary to adhere to the Python rules for defining functions. For example, every line of the function should start with a Tab. The first line not starting with a tab ends the definition of the function.

The python function that should be defined is called calc, and in our case accepts two arguments. These are the objects you have selected as arguments in the previous screen. There will be as much arguments as you have selected there. They are called `arg1` and `arg2`, but you can change their names to something more meaningful if you want.

In the function, you can do all sorts of calculations that you deem necessary, using the two arguments if needed. You should return the object you want to appear. In our case, this is a Point object. The two arguments are also Point objects, and we can use the `Point.coordinate()` function to get hold of the coordinates of the two given points.

The calculation necessary in our example is very simple, we simply add the two coordinates together, and divide the result by two. We then construct a new point using that coordinate. The python code needed is:

       def calc( a, b ):
            m = ( a.coordinate() + b.coordinate() ) / 2;
    	return Point( m )

Entering the code Entering the code for the midpoint in the Script Object wizard.

If you now click the Finish button, then the new object will appear in the &kig; document. If you move one of the points, then the newly created point will move along with them. A lot more powerful objects can be built in this way, you are encouraged to try it out.

Constructed a Script Object The newly constructed Script Object.

All objects in &kig; can be used in the Python code. As we have seen above, points are of the Point class, and you can use ⪚ the `Point.coordinate()` method. You can also return all kinds of objects, not just Points. Many more classes and methods are available from the &kig; Python code, and a more complete reference on them is provided here.

## &kig; Features

- &kig; is an open source application. This means that you are free to use and modify it any way you like it. Distributing &kig; is subject to some restrictions, basically that everyone should have the same rights to use &kig;, including your modifications, as you and me.

  Free software programs are developed in a very open spirit, and its developers are usually very responsive to user feedback. Therefore, if you have any questions, complaints, or whatever about &kig;, please let the author know at devriese@kde.org.

- &kig; is a KPart application, which means that you can embed it in other &kde; software. If you open a `.kig` file in &konqueror;, it can be opened directly in the &konqueror; screen without the need to start an external application.

- Working with &kig; should be very straightforward. Constructing objects is easy and interactive, with preliminary results being shown, &etc;. Moving, selecting and building all work as one would expect them to. Undo support should also be very intuitive.

- &kig; supports macros to be defined in a straightforward manner. These objects are presented to the user like normal objects. They are saved on exit and loaded on startup, so that they aren't lost on exit. In the Types Manager you can manage these objects. You can export them to files, import them from files, and delete them.

- &kig; saves its data in a clear &XML; format.

- &kig; supports the construction of locuses..

- &kig; allows you to export a &kig; file to some interesting formats, like images, and XFig files. This is rather useful, because not all programs support the &kig; file format yet.

- &kig; has a very flexible transformation system.

- &kig; aims to be compatible with its competitors.. This is why it supports the &kgeo; file format, the &kseg; file format, and support for other formats is planned also.

## Questions and Answers

&reporting.bugs; &updating.documentation;

## Credits and License

&kig;

&kig; copyright 2002 Dominique Devriese devriese@kde.org

Documentation copyright 2002-2003 Dominique Devriese. devriese@kde.org

&underFDL; &underGPL;

## Installation

### How to obtain &kig;

&install.intro.documentation;

### Compilation and Installation

&install.compile.documentation;

## Contribute

### Free Software

&kig; is Free Software. This means that its source code is freely available on the Internet, and everyone can use it, read it, modify it, and distribute it. I work on it as a hobby project, and I have already learned a lot about programming, C++, &kde;/&Qt;, math, software collaboration and open source projects in the process.

### Contribute

The point of this chapter is to point you (the user) to the rights that &kig;'s license gives you. As with all free software, you are allowed (and encouraged) to fix problems you encounter while using it, to add features you miss, to distribute your modified program, and to send these modifications to me at devriese@kde.org, so that I can include them in the next version for others to enjoy. I personally have no financial interest in this project whatsoever, so this isn't just marketing-speak here.

If you are uncertain of your rights to use this software, or other peoples right to use any modifications you make to this program &etc;, please read the license. You can find it in the `COPYING` file in the &kig; source tree or the license tab in the About Kig dialog.

### How to contribute ?

Any contributions are welcome. If you think the icons suck, or that the manual needs updating, or you have this really cool macro that you want to share with the world, do not hesitate to send it to me. Please note that your contributions will be distributed under the terms of the GNU GPL; you can find the terms of this license in the `COPYING` file in the &kig; source tree, and in the Credits and Licenses chapter in this manual.

&documentation.index;