<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [

  <!ENTITY kappname "&rocs;">
  <!ENTITY package "kdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % Estonian  "INCLUDE">
]>
<book lang="&language;">

<bookinfo>
<title
>&rocs;i käsiraamat</title>
<authorgroup>
<author
><personname
> <firstname
>Tomaz</firstname
> <surname
>Canabrava</surname
> </personname
> <email
>tomaz.canabrava@gmail.com</email
> </author>
<author
><personname
> <firstname
>Andreas</firstname
> <surname
>Cord-Landwehr</surname
> </personname
> <email
>cordlandwehr@googlemail.com</email
> </author>

<othercredit role="translator"
><firstname
>Marek</firstname
><surname
>Laane</surname
><affiliation
><address
><email
>bald@smail.ee</email
></address
></affiliation
><contrib
>Tõlge eesti keelde</contrib
></othercredit
> 
</authorgroup>

<copyright
><year
>2009</year
><holder
>Tomaz Canabrava</holder
></copyright>
<copyright
><year
>2011</year
><holder
>Andreas Cord-Landwehr</holder
></copyright>

<date
>2011-12-04</date>
<releaseinfo
>1.1 &kde; 4.8</releaseinfo>

<legalnotice
>&FDLNotice;</legalnotice>

<abstract>
<para
>&rocs; on KDE graafiteooria tööriist. </para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kdeedu</keyword>
<keyword
>matemaatika</keyword>
<keyword
>matemaatika</keyword>
<keyword
>graafid</keyword>
<keyword
>tipp</keyword>
<keyword
>seos</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title
>Sissejuhatus</title>
<para
>&rocs; on graafiteooria arenduskeskkond kõigile, keda huvitab graafialgoritmide loomine ja analüüs. See hõlmab muu hulgas</para>
<itemizedlist>
	<listitem
><para
>õppejõude, kes soovivad demonstreerida algoritme oma õpilastele,</para
></listitem>
	<listitem
><para
>õppureid, kes soovivad mõista ja näha algoritmide tööd,</para
></listitem>
	<listitem
><para
>kõiki, kes peavad mis tahes põhjusel looma graafialgoritme ja vajavad tööriista prototüüpide testimiseks.</para
></listitem>
</itemizedlist>
<para
>Kõigile neile pakub &rocs; hõlpsasti pruugitava graafiredaktori, millega graafe luua, võimsa QTScripti mootori algoritmide täitmiseks ja mitu abitööriista graafide ja andmestruktuuride loomiseks enda katsete tarbeks. Tavaliselt käib asi nii, et kõigepealt kirjutatakse algoritm, siis luuakse graaf ja siis uuritakse reaalajas, kuidas algoritm graafi peal toimib.</para>

<screenshot>
<screeninfo
>&rocs;i pilt.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>&rocs;i pilt.</phrase>
</textobject>
</mediaobject>
</screenshot>
</chapter>

<chapter id="user-interface">
<title
>&rocs;i kasutajaliides</title>

<sect1 id="user-interface-all">
<title
>Kasutajaliidese põhielemendid</title>
<para
>Kasutajaliides jaguneb mitmeks loogiliseks osaks, nagu on näha ka juuresoleval pildil. </para>
<screenshot>
	<screeninfo
>&rocs;i liidese graafilised elemendid.</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="rocs-interfaces.png" format="PNG"/>
	</imageobject>
	<textobject>
	<phrase
>&rocs;i liidese graafilised elemendid.</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
	<term
>Visuaalse graafiredaktori riba</term>
	<listitem
><para
>Graafi loomiseks või muutmiseks visuaalses graafiredaktoris tuleb siin kõigepealt valida tööriist</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Visuaalne graafiredaktor</term>
	<listitem
><para
>Siin saab graafid joonistada. Paremklõps tühjal alal, graafi elementidel või valitud graafi elementidel avab kontekstimenüü, mis mõnevõrra erineb sõltuvalt sellest, kus klõpsati.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Graafi omadused</term>
	<listitem
><para
>Siin näeb kõigi parajasti visuaalse graafiredaktori lõuendil olevate graafide loendit. Siin saab teha ka muudatusi näiteks graafi nimes, nähtavates omadustes, näiteks tippude nimedes või väärtustes, samuti määrata graafi elementide vaikimisi värve.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Skriptiredaktor</term>
	<listitem
><para
>Selles tekstiredaktoris saab kirjutada algoritme QtScriptis (antud juhul on see põhimõtteliselt samane JavaScriptiga). Korraga võib tegutseda ka mitme algoritmi kallal, avades või luues menüü abil uusi skriptikaarte. Kui skripti tehtud muudatused on salvestamata, näeb kaardi sakil väikest ketast.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Silumis- ja skriptiväljund</term>
	<listitem
><para
>Selles tekstialas näeb kas sinu skripti silumisteavet või väljundit sõltuvalt väljundi valikust. Kui skript tekitab vigu, valitakse automaatselt silumisväljund. Silumisväljund näitab samuti kõiki programmi väljundteateid.</para
></listitem>
</varlistentry>
<varlistentry>
	<term
>Skripti töölepanek</term>
	<listitem
><para
>See ala tegeleb skriptide töölepanekuga. Parajasti avatud skripti saab rakendada visuaalse graafiredaktori lõuendil olevale graafile, kui klõpsata nupule <guiicon
>Käivita</guiicon
>. Skripti käivitamise järel saab selle täitmist ka peatada, kui klõpsata nupule <guiicon
>Peata</guiicon
>.</para
></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title
>Tööriistaribad</title>
<para
>Siin on mitmesugused visuaalse graafiredaktori tööriistaribad, mis võimaldavad vajalikke võimalusi kasutada üheainsa klõpsuga. Vaikimisi näeb järgmisi tööriistaribasid:</para>
<itemizedlist>
	<listitem
><para
>Peamine tööriistariba</para
></listitem>
	<listitem
><para
>Joondusriba</para
></listitem>
</itemizedlist>

<sect2 id="user-interface-toolbars-main">
<title
>Peamine tööriistariba</title>
<para
><emphasis
>Peamine tööriistariba</emphasis
> koosneb järgmistest toimingutest. Toimingule klõpsamine tähendab seda, et saad hiirega rakendada antud toimingu visuaalse graafiredaktori lõuendis:</para>
<itemizedlist>
<listitem
><para
><guilabel
>Liiguta</guilabel
>: elementide valimiseks klõpsa lõuendi tühjal alal, hoia hiirenupp all ja joonista ristkülik, mis sisaldab mõningaid tippe ja/või seoseid, mis sel juhul valitakse, või klõpsa vahetult valimata elemendi peal selle valimiseks. Kui klõpsad valitud elemendil või elementidel, saab hiirenuppu all hoides ja hiirt liigutades elemente liigutada. Valitud elemente saab liigutada ka nooleklahvidega.</para
></listitem>
<listitem
><para
><guilabel
>Lisa tipp</guilabel
>: klõpsa visuaalse graafiredaktori lõuendil vajalikus kohas ja loo uus tipp, mis kuulub parajasti valitud graafile.</para
></listitem>
<listitem
><para
><guilabel
>Lisa seos</guilabel
>: klõpsa mõnel tipul, hoia hiir all ja tõmba joon teise tipuni, milleni seos peab ulatuma. Seda toimingut saadab edu ainult siis, kui aktiivne graaf võimaldab sellist seost lisada (nt. orienteerimata graafil ei ole lubatud lisada kahe tipu vahele mitut seost).</para
></listitem>
<listitem
><para
><guilabel
>Kustuta</guilabel
>: klõpsa elemendil selle kustutamiseks. Kui kustutad tipu, kustutatakse ka kõik sellega seotud seosed.</para
></listitem>
<listitem
><para
><guilabel
>Suurendus</guilabel
>: klõpsa lõuendil, hoia &HVN; all ja joonista sellega ristkülik. Lõuendit suurendatakse, nii et näed ainult valitud osa. Samuti võib suurendada või vähendada hiirerattaga. Topeltklõps &HVNga; taasta esialgse suurenduse.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Peamine tööriistariba</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-main.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Peamine tööriistariba</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="user-interface-toolbars-alignment">
<title
>Joondusriba</title>
<para
>Lisada võib ka <emphasis
>joondusriba</emphasis
>. Mõnele selle riba toimingule klõpsates saab vahetult mõjutada parajasti valitud tippe:</para>
<itemizedlist>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Üles</guilabel
>: tipud joondatakse kõige ülemise tipu vertikaalse positsiooni järgi. See puudutab ainult vertikaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Keskele</guilabel
>: tippude joondamine kõigi valitud tippude vertikaalsete positsioonide keskme järgi. See puudutab ainult vertikaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Alla</guilabel
>: tipud joondatakse kõige alumise tipu vertikaalse positsiooni järgi. See puudutab ainult vertikaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Vasakule</guilabel
>: tipud joondatakse kõige vasakpoolsema tipu horisontaalse positsiooni järgi. See puudutab ainult horisontaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Keskele</guilabel
>: tipud joondatakse kõige ülemise tipu horisontaalse positsiooni järgi. See puudutab ainult horisontaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Paremale</guilabel
>: tipud joondatakse kõige parempoolsema tipu horisontaalse positsiooni järgi. See puudutab ainult horisontaalset positsiooni.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Ring</guilabel
>: tipud joondatakse ringi, mille diameeter võrdub tippude maksimaalse vahemaaga. Tipud paigutatakse samas järjekorras nagu vaates alates tippude raskuskeskmest.</para
></listitem>
<listitem
><para>
<inlinemediaobject
><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject
> <guilabel
>Kattuvate seoste minimeerimine</guilabel
>: rakendatakse Rruchterman-Reingoldi algoritmile kattuvate seoste arvu (ligilähedaseks) minimeerimiseks.</para
></listitem>
</itemizedlist>
<screenshot>
<screeninfo
>Joondusriba</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-alignment.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Joondusriba</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="user-interface-graph-properties">
	<title
>Graafi omadused</title>
	<para
>Vasakul külgribal leiab valikud kõigi avatud graafide jaoks. Kõik need on globaalsed iga graafi jaoks ning neid võib muuda tipu või seose jaoks vastavalt tipu või seose omaduste dialoogis.</para>

	<itemizedlist>
	<listitem
><para
><guilabel
>nimi</guilabel
>: nimi, mida algoritm peab kasutama graafi mõjutamiseks. </para
></listitem>
	<listitem
><para
><guilabel
>Andmete värv</guilabel
> uute tippude jaoks: klõpsuga nupule <guilabel
>Kõik</guilabel
> saab muuta kõigi aktiivsete tippude värvi </para
></listitem>
	<listitem
><para>
	  <guilabel
>Osuti värv</guilabel
> <!--FIXME color of edges?-->
	</para
></listitem>
	</itemizedlist>
	<para
>Valikute viimane rida sisaldab klõpsatavaid nuppe:</para>
	<itemizedlist>
	<listitem
><para
><guilabel
>Nimede näitamise koht</guilabel
> <guilabel
>Andmed</guilabel
> või <guilabel
>Osutid</guilabel
> </para
></listitem>
	<listitem
><para
><guilabel
>Väärtuste näitamise koht</guilabel
> <guilabel
>Tipud</guilabel
> või <guilabel
>Seosed</guilabel
> </para
></listitem>
	<!-- FIXME missing Graph Type Undirected Graph, Directed Graph, Multigraph -->
	</itemizedlist>
</sect1>
</chapter>

<chapter id="using-rocs">
<title
>&rocs;i kasutamine</title>
<para
>Tavaliselt on esimene samm graafi loomine visuaalse graafiredaktoriga. Seda võib teha käsitsi, see tähendab tippe luues ja neid ühendades, või siis kasutades mõningaid abialgoritme, mida pakub menüükäsk <menuchoice
><guimenu
>Tööriistad</guimenu
> <guimenuitem
>Graafi genereerimine</guimenuitem
></menuchoice
>. Samuti võib lõpuks kasutada tööriista <menuchoice
><guimenu
>Tööriistad</guimenu
> <guimenuitem
>Väärtuste omistamine</guimenuitem
></menuchoice
>, millega saab anda graafi tippudele ja seostele esialgsed väärtused. Kõige lõpuks tuleb graafile anda nimi. Seda kasutatakse edaspidi identifikaatorina, mida läheb vaja skriptimootoril.</para>

<sect1 id="using-rocs-scripting">
<title
>Skriptimine</title>
<para
>&rocs; kasutab JavaScriptile sarnanevat skriptikeelt. See tähendab, et muutujate ja funktsioonide defineerimine ning nende kasutamine käib täpselt samamoodi nagu JavaScriptis. Lisaks pakub &rocs; mitmeid funktsioone, mis võimaldavad kasutada graafe visuaalse graafiredaktori lõuendil ja nende elemente. </para>

<sect2
><title
>Graafi kasutamine</title>
<para
>Skriptiliideses saab ligipääsu graafile tagada lihtsalt selle nime kirjutades ja kasutades seda objektina koos mõnega järgnevatest funktsioonidest. ligipääsu tipule või seosele annab graafiobjekti identifikaator.</para>
<variablelist>
<varlistentry>
<term
>Graafiobjektid</term>
<listitem>
<programlisting
>// functions
     array list_nodes();
     array list_edges();
     node add_node(name);
     edge add_edge(from, to);
     node node_byname(QString&amp; name);
     node begin_node();
     array end_nodes();

// variables
     bool directed
     bool automate
     string name
     string nodeDefaultColor // in HEXA
     string edgeDefaultColor  // in HEXA
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Tipuobjektid</term>
<listitem>
<programlisting
>// functions
     array adj_nodes();
     array adj_edges();
     array input_edges();
     array output_edges();
     array loop_edges();
     array connected_edges(Node *n);
     void self_remove();

// variables
    double x
    double y
    double width
    string value
    string name
    string color  // in HEXA
    bool begin
    bool end
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Seoseobjektid</term>
<listitem>
<programlisting
>string color ( em hexa )
    string value
    string name
    double width
    string style ( dot, dash, dash dot, solid )

    node start();
    node  end();

    void self_remove();
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="script-graph-algorithms">
<title
>Graafi algoritmid</title>
<para
>Mõnikord tuleb kasuks, kui tarvitad standardsete ülesannete funktsioone, näiteks lühima vahemaa arvutamiseks kahe tipu vahel. Praegu toetame järgmisi algoritme, mida saab skriptimootoriga välja kutsuda sama graafi tippudel.</para>
<variablelist>
<varlistentry>
<term
>Lühima teekonna arvutamine</term>
<listitem>
	<para
>Arvutab lühima tee tippude <emphasis
>algus</emphasis
> ja <emphasis
>lõpp</emphasis
> vahel. Mõlemad tipud peavad asuma ühel graafil. Arvutamine arvestab ka seda, kas graaf on orienteeritud või orienteerimata.</para>
	<funcsynopsis>
	<funcprototype
><funcdef
>array <function
>dijkstra_shortest_path</function
></funcdef
> <paramdef
>Node* <parameter
><replaceable
>algus</replaceable
></parameter
></paramdef
> <paramdef
>Node* <parameter
><replaceable
>lõpp</replaceable
></parameter
></paramdef
> </funcprototype>
	</funcsynopsis>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="script-example">
<title
>Näide</title>
<para
>Selle on lihtne näidisskript, mis määrab kindlaks esimese graafi nelja esimese tipu värvi:</para>
<programlisting
>/* A simple example that sets the color of the 4 first nodes in the first
graph: */

var colors = new Array("red", "green", "blue", "yellow");

/* graphs is an array of graphs, you can access a graph by its index in the
array or by its name, so if the first graph's name is Untitled0, the following
sentence are right  */
var list1= graphs[0].list_nodes(); //  1st form.
var list2=Untitled0.list_nodes();              // 2nd form

 for ( var i = 0; i &lt; colors.length; i++){
        if (i 
> list2.length) break;
        list2[i].color = colors[i]
 }
</programlisting>
</sect1>
<sect1>
	<title
>Import ja eksport</title>
	<para
>&rocs; toetab praegu importimisel ja eksportimisel järgmisi failivorminguid:</para>
	<itemizedlist>
		<listitem
><para
>DOT-failid, tuntud ka kui Graphviz-failid</para
></listitem>
		<listitem
><para
>GML-failid</para
></listitem>
		<listitem
><para
>Klaartekstfailid</para
></listitem>
	</itemizedlist>
	<para
>Praegu imporditakse enamiku failitüüpide korral ainult üksikud väärtused. Imporditavate väärtuste hulka kuuluvad tipud ja nendega seotud seosed, kõigi elementide nimed, väärtused ja olemasolu korral ka koordinaadid.</para>
</sect1>
</chapter>

<chapter id="credits">
<title
>Autorid ja litsents</title>

<para
>&rocs; </para>
<para
>Rakenduse autoriõigus:</para>
<itemizedlist>
	<listitem
><para
>Autoriõigus 2008: Ugo Sangiori (ugorox AT gmail.com)</para
></listitem>
	<listitem
><para
>Autoriõigus 2008-2011: Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Autoriõigus 2008-2011: Wagner Reck (wagner.reck AT gmail.com)</para
></listitem>
	<listitem
><para
>Autoriõigus 2011: Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Dokumentatsiooni autoriõigus:</para>
<itemizedlist>
	<listitem
><para
>Dokumentatsiooni autoriõigus 2009: &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</para
></listitem>
	<listitem
><para
>Dokumentatsiooni autoriõigus 2009: Tomaz Canabrava (tcanabrava AT kde.org)</para
></listitem>
	<listitem
><para
>Dokumentatsiooni autoriõigus 2011: Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para
></listitem>
</itemizedlist>

<para
>Tõlge eesti keelde: Marek Laane <email
>bald@smail.ee</email
></para
> 
&underFDL; &underGPL; </chapter>

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

<sect1 id="getting-rocs">
<title
>&rocs;i hankimine</title>
&install.intro.documentation; </sect1>

<sect1 id="compilation">
<title
>Kompileerimine ja paigaldamine</title>
&install.compile.documentation; </sect1>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
