summaryrefslogtreecommitdiffstats
path: root/doc/kig/index.docbook
blob: 6966b588b3e66ac914f67d3f3d916db11dd3bb22 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
<!ENTITY kseg "<application>KSeg</application>">
<!ENTITY cabri "<application>Cabri</application>">
<!ENTITY drgeo "<application>Dr.Geo</application>">
<!ENTITY package "tdeedu">
<!ENTITY kappname "&kig;">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
<!-- change language only here -->
]
>

<book lang="&language;">

<bookinfo>
<title>The &kig; Handbook</title>

<authorgroup>
<author>
<firstname>Dominique</firstname> <surname>Devriese</surname>
<affiliation>
<address><email>devriese@kde.org</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>


<copyright>
<year>2002</year><year>2003</year><year>2004</year> <holder>Dominique
Devriese</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2005-08-20</date> <releaseinfo>0.10.5</releaseinfo>

<abstract>
<para>
&kig; is a &kde; application for Interactive Geometry.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KDE-Edu</keyword>
<keyword>Kig</keyword>
<keyword>Interactive Geometry</keyword>
<keyword>KGeo</keyword>
<keyword>Cabri</keyword>
<keyword>Dr.Geo</keyword>
<keyword>KSeg</keyword>
</keywordset>
</bookinfo>


<chapter id="introduction">
<title>Introduction</title>

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

<itemizedlist>
<listitem><para> Allow students to interactively explore
mathematical figures and concepts using the computer.
</para></listitem>

<listitem><para> Serve as a <acronym>WYSIWYG</acronym> tool for
drawing mathematical figures and including them in other
documents.</para></listitem>
</itemizedlist>

<para>
You can report problems in &kig; using the internal bug
reporting tool
(<menuchoice><guimenu>Help</guimenu><guimenuitem>Report
Bug...</guimenuitem></menuchoice>), or just contact me at
<email>toscano.pino@tiscali.it</email>.
</para>
<para>
Since &kig; supports macros and the construction of locuses, it allows for
some
rather advanced macros to be defined. If you have created an
interesting macro, which you think might be useful for other
people, please mail it to me at
<email>toscano.pino@tiscali.it</email>, so I can include it in the
distribution (if you do this, it will be licensed under the
terms of &kig;'s license, the <ulink
url="http://www.gnu.org/licenses/licenses.html#GPL">GPL</ulink>,
so that other people can freely use and adapt it).
</para>
</chapter>


<chapter id="using-kig-basic">
<title>Basic usage</title>
<section id="constructing-objects">
<title>Constructing Objects</title>
<section id="constructing-points">
<title>Constructing points</title>
<para>
You can construct points in several ways:</para>
<itemizedlist>
<listitem>
<para>
Select <menuchoice><guimenu>Objects</guimenu>
<guisubmenu>Points</guisubmenu>
<guimenuitem>Point</guimenuitem></menuchoice> from the
menubar or
press the appropriate button in the toolbar. You can
then construct a point by clicking at the desired
position in the window.</para> <note><para>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 items to construct
the object.</para></note>
</listitem>
<listitem>
<para>
Since you often need to construct points, simply
clicking somewhere in the screen with the &MMB; will
construct a point for you, without going to a menu or
button.
</para>
</listitem>
<listitem>
<para>
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 <xref linkend="constructing-other-objects" />.
</para>
</listitem>
</itemizedlist>

<screenshot>
<screeninfo>A point has been constructed</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="constructed_a_point.png"
format="PNG"/>
</imageobject>
<textobject>
<phrase>A point has been constructed</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>

<section id="constructing-other-objects">
<title>Constructing Other Objects</title>
<para>
Constructing objects other than points is usually done by
selecting the appropriate entry in the
<guimenu>Objects</guimenu> menu, or by clicking on one of
the toolbar buttons.
</para>
<screenshot>
<screeninfo>Constructing a circle</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="constructing_a_circle.png"
format="PNG"/>
</imageobject>
<textobject>
<phrase>Constructing a circle</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
This will start the construction of the chosen object type.
All of these types require arguments. For example, if you
selected to construct a circle by center and point, you will need to
give two points: one for the center, and one for the point on
the circle.
</para>
<para>
These arguments are objects too, which can also be selected, simply by
clicking on them. When you move the cursor over an argument you want to use to
construct an object, a preliminary image will be shown of the object, so you will
know what it will look like. For objects that require points as arguments, you
can place a new point at the
current cursor position and select it by clicking the &LMB;.
</para>
<para>
You can always cancel the construction of the new object by
pressing the &Esc; button or by clicking
on the <guiicon>Stop</guiicon> button (red octagon with an
<quote>X</quote>) on the toolbar.
</para>
<screenshot>
<screeninfo>Constructing a circle.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="constructing_a_circle_2.png"
format="PNG"/>
</imageobject>
<textobject>
<phrase>Constructing a circle</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>
</section>

<section id="selecting-objects">
<title>Selecting Objects</title>
<para>
Selecting objects can be done in two ways:
</para>
<itemizedlist>
<listitem>
<para>
Simply clicking on an object causes that object to be selected, clearing the
current selection. If you
want to select multiple objects simultaneously, hold down the &Ctrl; key while
clicking on an object.
</para>
</listitem>
<listitem>
<para>
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 allows you
to keep the current selection.
</para>
</listitem>
</itemizedlist>
<para>
When you have more than one object under the mouse, you can easily
choose which object select or add to the current selection. Click
with the &LMB;, while holding the &Shift; key, to have a popup with
all the objects under the mouse. Then, you can select the object
you need. As said before, the behaviour of the &Ctrl; key will
affect the selection.
</para>

<screenshot>
<screeninfo>Selecting objects</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="selecting_objects.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Selecting objects</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>

<section id="moving-objects">
<title>Moving Objects</title>
<para>
To move objects, you must first <link
linkend="selecting-objects">select</link> them.
</para>
<para>
When the objects you want to move are selected, you can start
moving them by &LMB; clicking and dragging any one of them. When you are done,
simply release the &LMB;.
</para>
<note><para>For some types of objects (especially when defined by
complicated locuses), moving them can be slow on old hardware. This
is unfortunate, but inevitable, given the calculations involved.
</para></note> <note><para>If you &RMB; click one of the selected objects, and
choose
<guimenuitem>Move</guimenuitem>, moving the mouse will move the object. When the
object is moved to the desired position, another &LMB; click will stop the
moving of the object.</para></note>
</section>
<section id="deleting-objects">
<title>Deleting objects</title>
<para>
Deleting objects is done by first <link
linkend="selecting-objects">selecting</link> them, and next doing either of
these:
<itemizedlist>
<listitem>
<para>
Press the <keycap>Delete</keycap> key.
</para>
</listitem>
<listitem>
<para>
Press the <guiicon>delete</guiicon> button on the toolbar.
</para>
</listitem>
<listitem>
<para>
<mousebutton>Right</mousebutton>-click on one of the
objects, and select
<guimenuitem>Delete</guimenuitem>
in the <link linkend="objects-context-menus">context
menu</link> that appears.
</para>
</listitem>
</itemizedlist>
</para>
</section>

<section id="showing-hiding-objects">
<title>Showing and hiding objects</title>
<para>
In &kig;, objects can be hidden. This is done by selecting
the objects, &RMB; clicking one of
them, and selecting
<guimenuitem>Hide</guimenuitem> in
the <link linkend="objects-context-menus">context menu</link>
that appears.
</para>
<para>
To unhide the objects, use the
<menuchoice><guimenu>Edit</guimenu><guimenuitem>Unhide
all</guimenuitem></menuchoice>. This will unhide all
currently hidden objects.
</para>

<section id="night-vision">
<title>Night Vision</title>
<para>
Night Vision is a particular way of working with hidden
objects. When you have to move or change something in one or
more object but without unhiding all the hidden objects you
have, then the night vision mode will be of benefit to you.
</para>
<para>
Basically, it allows you to see the hidden objects as if they
were visible, so that you can manipulate them as you would normally.
In Night Vision mode, the hidden objects will be visible with
a grey colour.
</para>
<para>
To toggle the night vision mode, use
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Wear
Infrared Glasses</guimenuitem></menuchoice>.
</para>
</section>
</section>

<section id="undo-redo">
<title>Undo/Redo</title>
<para>
In &kig;, you can undo almost any change you make in the
document. Just use the
<guiicon>undo</guiicon>/<guiicon>redo</guiicon> buttons on the
toolbar, or the appropriate shortcuts.
</para>
</section>

<section id="full-screen-mode">
<title>Full Screen Mode</title>
<para>
&kig; also has a Full Screen mode. To use it, click the
appropriate button on the toolbar, or select
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Full
Screen Mode</guimenuitem></menuchoice>.
</para>
<para>
To leave Full Screen mode,
&RMB; click the screen at a place
where there is no object present, and select
<guimenuitem>Exit Full Screen Mode</guimenuitem>, or press the
&Esc; key.
</para>
</section>
</chapter>


<chapter id="kig-object-types">
<title>&kig; Object Types</title>
<para>
&kig; supports a rather large number of object types. Please
note that not all of the available object types are shown in the
toolbars: there are some objects that you can only
construct via the <guimenu>Objects</guimenu> menu in the menu
bar. Of course, as with all &kde; applications, the contents of the toolbars are
configurable. Try out the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
Toolbars...</guimenuitem></menuchoice> option if you want to do this.
</para>
</chapter>


<chapter id="using-advanced">
<title>Advanced Usage</title>
<section id="objects-context-menus">
<title>Context Menus</title>
<para>
&kig; has context menus for its objects. Try
&RMB; clicking on an object in order to see
a context menu appear. There are many options: for
constructing other objects, setting colours, and even hiding,
moving or deleting objects. Some objects have options of
their own (&eg; you can redefine certain points to be
constrained to a line if they previously weren't, &etc;).
These options should be very straightforward to understand.
</para>
</section>

<section id="document-context-menus">
<title>Document context menus</title>
<para>
<mousebutton>Right</mousebutton>-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.
</para>
</section>

<section id="defining-macros">
<title>Defining Macros</title>
<para>
One of the more advanced features in &kig; is its support for
macros. This allows you to define new types of objects from
other ones which are defined already.
</para>
<para>
For example: Suppose you want to make a macro for constructing
a circle from three points on it. You would input three points,
then construct some perpendiculars and midpoints
until you find the center. Now you can use the existing
<quote>Construct a circle by center and point</quote> command
(using one of the three points as the point for this command). The
following image should make this a bit more clear:
</para>
<screenshot>
<screeninfo>Test running macros</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="test_run_macro.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Test running macros</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Next comes defining the macro. Select <guimenuitem>New
macro</guimenuitem> from the <guimenu>Type</guimenu> 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
to select, click again to unselect) and click the
<guibutton>Next</guibutton> button to continue. Finally,
select the last objects (only the circle in our example).
</para>

<screenshot>
<screeninfo>The macro wizard</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="macro_wizard.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The macro wizard</phrase>
</textobject>
</mediaobject>
</screenshot>

<para> After the previous steps are completed, click the
<guibutton>Next</guibutton> button to continue. Enter a name
and optionally a description for your new type, and click the
<guibutton>Finish</guibutton> button. Your macro type is now
finished.
</para>

<para>
To use the new macro type, click its button on the toolbar or
use the <guimenu>Objects</guimenu> menu. Constructing a macro
object is just like constructing any other object.
</para>
<screenshot>
<screeninfo>Using your new type</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="macros_at_work.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Using your new type</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>

<section id="working-with-types">
<title>Working with types</title>
<para>
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 <menuchoice><guimenu>Types</guimenu><guimenuitem>Manage
Types...</guimenuitem></menuchoice> from the menu, you will see
a dialog where you can edit your types. It allows you to modify
the existant types, delete types that are no longer used, export
them to a file, or even load them from another file.
</para>
<screenshot>
<screeninfo>Edit Types Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="edit_types_dialog.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The Edit Types Dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>

<section id="text-labels">
<title>Text labels</title>
<para>
&kig; allows you to add text labels to a construction. This
is very useful for adding names, explanations or other text
to constructions. &kig; can also display variable information
about objects (also known as <quote>properties</quote>).
</para>
<para>
To start constructing a text label, simply press the
<guibutton>Text Label</guibutton> button in the &kig; toolbar or
select <menuchoice><guimenu>Objects</guimenu><guisubmenu>Other
</guisubmenu><guimenuitem>Text label</guimenuitem>
</menuchoice> in the menubar.
</para>
<para>
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 <quote>attach</quote> the label to an object.
</para>
<screenshot>
<screeninfo>Attaching a label to a circle...</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="text_label_attaching.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Attaching a label to a circle...</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
After you have selected where to put the label, the text label dialog appears. 
Here, you can type in
the text that you want in the new label, and click
<guibutton>Finish</guibutton>. You should now see the label in your document.
</para>
<screenshot>
<screeninfo>The Text Label Dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="text_label_wizard.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The Text Label Dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
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 (&eg; you can construct a
label with the text <quote>This segment is %1 units
long.</quote> where <token>%1</token> would be dynamically
replaced with the length of a specific segment).
</para>
<para>
To do this, enter a text with a number of placeholders (
<token>%1</token>, <token>%2</token> &etc;) in it.
Then, press the <guibutton>Next</guibutton> button to
continue. If you want to change the text or variables later,
you can go back using the <guibutton>Back</guibutton> button.
</para>
<para>
The wizard now shows the text you entered with all
placeholders replaced by something like <guilabel>argument
1</guilabel>. Selecting the property connected to a certain argument is
done by first clicking on the argument in question. Then click
on the object that you need and that has this property, and
then select the property itself in the popup
menu that appears. For instance, in the example above, you
would click <guilabel>argument 1</guilabel>, click on the
correct segment in the main &kig; window, and select the
property <guilabel>Length</guilabel>. 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
<guibutton>Finish</guibutton> button to complete the
construction of the text label.
</para>
<screenshot>
<screeninfo>Selecting a property for a variable
part</screeninfo>
<mediaobject>
<imageobject>
<imagedata
fileref="text_label_wizard__select_property.png"
format="PNG"/>
</imageobject>
<textobject>
<phrase>Selecting a property for a variable part</phrase>
</textobject>
</mediaobject>
</screenshot>
</section>

<section id="locuses">
<title>Locuses</title>
<para>
&kig; supports the use of locuses. A locus is mathematically defined as
the set of all points or lines that satisfy or are determined by specific
conditions; as in <quote>the locus of points
equidistant from a given point is a circle</quote>.
Let's look at an example of how to use locuses in &kig;:
</para>
<para>
Consider the following geometrical construction: We draw a
circle, and a point that can move only along its circumference
(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.
</para>
<screenshot>
<screeninfo>A simple construction using a locus</screeninfo>
<mediaobject>
<imageobject>
<imagedata
fileref="simple_locus_construction.png"
format="PNG"/>
</imageobject>
<textobject>
<phrase>A simple construction using a locus</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
Now if you move the point that is constrained to the circle,
you'll see that the second point moves along with it. If you
were to hold a pen at the second point, and move the
first point around the entire circle, a new circle, half the
size of the other would be drawn. The path that the second point
travels while the first one moves around the circle is its locus.
</para>
<para>
Actually constructing the locus of a point is very easy. Click
the <guiicon>locus</guiicon> button in the toolbar, or select
<menuchoice><guimenu>Objects</guimenu>
<guisubmenu>Other</guisubmenu>
<guimenuitem>Locus</guimenuitem>
</menuchoice>
from the menubar. Then select the constrained point as the
moving point (the text <guilabel>Moving Point</guilabel> will
appear as you move the mouse over it), and the other as the
dependent point. The locus of the dependent point will then be drawn.
</para>
</section>
</chapter>

<chapter id="scripting">
<title>Scripting</title>
<para>
&kig; allows you 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 a similar
functionality (the <acronym>GNOME</acronym> program &drgeo;). 
</para>
<para>
Python Scripting in &kig; basically allows you to create your
own objects from certain parent objects. For example, if you are a math
teacher, and you have some fancy way
of calculating an interesting point on a conic, then instead of
messing with complex constructions and macros, you could just
write down in Python code how the point is to be calculated and
then &kig; will show it for you.
</para>
<para>
Suppose you were not aware of the &kig; built-in type <quote>Mid Point</quote>,
and you wanted to show the midpoint of two given points. You
would then click on the <guibutton>Python Script</guibutton>
button in the toolbar, or select
<menuchoice><guimenu>Objects</guimenu><guisubmenu>Other</guisubmenu>
<guimenuitem>Python Script</guimenuitem></menuchoice> from the
menubar. You are then presented with a wizard that allows you
to proceed.
</para>
<screenshot>
<screeninfo>The Script Object Wizard</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="script_wizard.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The Script Object Wizard</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
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 <guibutton>Next</guibutton> to proceed.
</para>
<para>
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
notice that we are actually defining a Python function called
<function>calc</function>. It is therefore necessary to adhere
to the Python rules for defining functions. For example, every
line of the function should start with a <keysym>Tab</keysym>.
The first line not starting with a <keysym>tab</keysym> ends the
definition of the function.
</para>
<para>
The Python function that we want to define is called
<function>calc</function>, and in our case it accepts two arguments.
These are the objects you have selected as arguments in the
previous screen. You need as many arguments as you have
selected there. They are called <parameter>arg1</parameter> and
<parameter>arg2</parameter>, but you can change their names to
something more meaningful if you want.
</para>
<para>
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 define. In our case, this is a
<classname>Point</classname> object. The two arguments are also
<classname>Point</classname> objects, and we
can use the <function>Point.coordinate()</function> function to
define the coordinates of the two given points.
</para>
<para>
The calculation necessary in our example is very simple, we
simply add the two sets of coordinates, and divide the new set
by two. We then construct a new point using the result.
The Python code needed is:</para>

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

<screenshot>
<screeninfo>Entering the code</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="script_wizard_entering_code.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Entering the code for the midpoint in the Script Object
wizard.</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
If you now click the <guibutton>Finish</guibutton> button,
the new object will appear in the &kig; document. If you move
one of the points, the newly created point will move along
with it. Much more powerful objects can be built in this way:
you are encouraged to try it out.
</para>
<screenshot>
<screeninfo>Constructed a Script Object</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="constructed_script_object.png" format="PNG" />
</imageobject>
<textobject>
<phrase>
The newly constructed Script Object.
</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
All objects in &kig; can be used in the Python code. As we have
seen above, points are of the <classname>Point</classname> class, and you
can use &eg; the <function>Point.coordinate()</function> method. You can
also return all kinds of objects, not just a <classname>Point</classname>.
Many more classes and methods are available in the &kig; Python code,
and a more complete reference is provided <ulink
url="http://edu.kde.org/kig/manual/scripting-api/index.html">on
the &kig; website</ulink>.
</para>
</chapter>

<chapter id="kig-features">
<title>&kig; Features</title>

<itemizedlist>
<listitem>
<para>
&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.
</para>
<para>
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 <email>toscano.pino@tiscali.it</email>.
</para>
</listitem>
<listitem>
<para>
&kig; is a KPart application, which means that you can
embed it into other &kde; software. If you open a <literal
role="extension">.kig</literal> file in &konqueror;, it
can be opened directly in the &konqueror; screen without
the need to start an external application.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
&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. You can
manage these objects in the <guilabel>Manage Types</guilabel>
dialog (see <xref linkend="working-with-types" />). You can export
them
to files, import them from files, edit and delete them.
</para>
</listitem>
<listitem>
<para>
&kig; saves its data in a clear &XML; format.
</para>
</listitem>
<listitem>
<para>
&kig; supports the construction of locuses.
</para>
</listitem>
<listitem>
<para>
&kig; allows you to export a &kig; file to some interesting
formats, like images, <application>XFig</application> and
<application>LaTeX</application> files, and <acronym>SVG</acronym>
vectorial images. This is rather useful, because not all programs
support the &kig; file format yet.
</para>
</listitem>
<listitem>
<para>
&kig; has a very flexible transformation system.
</para>
</listitem>
<listitem>
<para>
&kig; aims to be compatible with its competitors. This is
why it supports the &kgeo; file format, the &kseg; file
format and partially the &drgeo; and &cabri; formats; morover,
support for other formats is planned.
</para>
</listitem>
</itemizedlist>
</chapter>


<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs; &updating.documentation;
</chapter>


<chapter id="credits">
<title>Credits and License</title>

<para>
&kig;
</para>
<para>
&kig; copyright 2002-2004 Dominique Devriese
<email>devriese@kde.org</email>
</para>

<para>
Documentation copyright 2002-2004 Dominique
Devriese <email>devriese@kde.org</email>.
</para>

<para>
Documentation copyright 2004-2005 Pino Toscano
<email>toscano.pino@tiscali.it</email>.
</para>

<para>
Reviewed by &Philip.Rodrigues; &Philip.Rodrigues.mail;.
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL; &underGPL;
</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kig">
<title>How to obtain &kig;</title>

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
</sect1>

</appendix>

<appendix id="contributing">
<title>Contribute</title>
<section id="kig-is-free">
<title>Free Software</title>
<para>
&kig; is <ulink
url="http://www.gnu.org/philosophy/philosophy.html#AboutFreeSoftware">
Free Software</ulink>. 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.
</para>
</section>

<section id="contribute-to-kig">
<title>Contribute</title>
<para>
In this chapter I want to point out to you (the user) 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 <email>toscano.pino@tiscali.it</email>, so
that I can include them in the next version for others to
enjoy. Please note I personally have no financial interest in this
project whatsoever.
</para>
<para>
If you are uncertain of your rights to use this software, or
other people's right to use any modifications you make to this
program &etc;, please read the license. You can find it in the
<filename>COPYING</filename> file in the &kig; source tree or
the <guilabel>license</guilabel> tab in the <guilabel>About
Kig</guilabel> dialog.
</para>
</section>

<section id="howto-contribute">
<title>How to contribute ?</title>
<para>
Any contributions are welcome. If you don't like the icons,
or think that the manual needs updating, or if 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;
<acronym>GPL</acronym>; you can find the terms of this license in the
<filename>COPYING</filename> file in the &kig; source tree,
and in the <link linkend="credits">Credits and
Licenses</link> chapter in this manual.
</para>
</section>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: xml
End:
-->