Git commit 484b879c06b3e7f675c2c7ed56ff7b9d60d427bf by Andreas Cord-Landwehr. Committed on 03/07/2013 at 20:11. Pushed by cordlandwehr into branch 'master'.
Major 1.9 handbook updated. The scripting API is updated in a semi-automated way (next time it will be hopefully fully automated). Else, only copyright information are updated. R +0 -4 doc/apiConsole.docbook [from: doc/scripting-api.docbook - 095% similarity] A +162 -0 doc/apiDatastructure.docbook A +391 -0 doc/apiGraphstructure.docbook A +141 -0 doc/apiLinkedListstructure.docbook A +62 -0 doc/apiRootedTreestructure.docbook A +82 -0 doc/chapterImportExport.docbook M +31 -378 doc/index.docbook http://commits.kde.org/rocs/484b879c06b3e7f675c2c7ed56ff7b9d60d427bf diff --git a/doc/scripting-api.docbook b/doc/apiConsole.docbook similarity index 95% rename from doc/scripting-api.docbook rename to doc/apiConsole.docbook index fe79921..aea7e5b 100644 --- a/doc/scripting-api.docbook +++ b/doc/apiConsole.docbook @@ -1,6 +1,3 @@ -<chapter id="scripting-api"> -<title>The Scripting API</title> - <sect1 id="include-scripting-interface"> <title>Scripting Interfaces</title> <sect2> @@ -59,4 +56,3 @@ Console.debug("A debug message."); // print a debug message </sect3> </sect2> </sect1> -</chapter> diff --git a/doc/apiDatastructure.docbook b/doc/apiDatastructure.docbook new file mode 100644 index 0000000..1967365 --- /dev/null +++ b/doc/apiDatastructure.docbook @@ -0,0 +1,162 @@ +<sect1 id="scripting-data-structure"> +<title>Scripting API for every Data Structure</title> +<sect2> +<title>Abstract Data Structure Object</title> +<para> +The abstract data structure defines a set of data elements and possible connections between them, this is the prototype for every other data structure. +Data structures are identified by their names. +Assuming you created a data structure with name <literal>testgraph</literal>, then you can access the data structure simply by writing this identifier. +For example, to get an array with all data elements in the given data structure, you can write <literal>testgraph.list_nodes();</literal> in the script. +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + <listitem> + <para> + <emphasis>name</emphasis> : + </para> + <para>The unique name of this data structure.</para> + </listitem> +</itemizedlist> +</sect3> +</sect2> + +<sect2> +<title>Abstract Data</title> +<para> +An abstract data element is a unit of information that belongs to an abstract data structure and possibly is connected to other data elements by pointers. +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + <listitem> + <para> + <emphasis>width</emphasis> : + </para> + <para>The size of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>x</emphasis> : + </para> + <para>The x-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>y</emphasis> : + </para> + <para>The y-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>id</emphasis> : + </para> + <para>The unique identifier of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>color</emphasis> : + </para> + <para>The color of this data element stated as hexadecimal value.</para> + </listitem> +</itemizedlist> +</sect3> +</sect2> + + +<sect2> +<title>Abstract Pointer</title> +<para> +A pointer connects two data elements and can itself hold information by its properties. +</para> +<sect3> +<title>Properties</title> +<itemizedlist> + <listitem> + <para> + <emphasis>width</emphasis> : + </para> + <para>The width of the connection.</para> + </listitem> + + <listitem> + <para> + <emphasis>directed</emphasis> : + </para> + <para>If true, the connection is directed. Otherwise is connection is undirected.</para> + </listitem> + + <listitem> + <para> + <emphasis>from</emphasis> : + </para> + <para>Start of the connection.</para> + </listitem> + + <listitem> + <para> + <emphasis>to</emphasis> : + </para> + <para>End of the connection</para> + </listitem> + + <listitem> + <para> + <emphasis>color</emphasis> : + </para> + <para>ID of the connection type.</para> + </listitem> +</itemizedlist> +</sect3> + + +<sect3> +<title>Methods</title> +<variablelist> + + <varlistentry> + <term>remove()</term> + <listitem> + <para>Remove this connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>remove()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>add_property(name, value)</term> + <listitem> + <para>Add a new property to the connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>add_property(name, value)</function></funcdef> + <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef> + <paramdef>string <parameter><replaceable>value</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>remove_property(name)</term> + <listitem> + <para>Remove an existing property from the connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>remove_property(name)</function></funcdef> + <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> +</variablelist> +</sect3> + +</sect2> +</sect1> diff --git a/doc/apiGraphstructure.docbook b/doc/apiGraphstructure.docbook new file mode 100644 index 0000000..cfc93b4 --- /dev/null +++ b/doc/apiGraphstructure.docbook @@ -0,0 +1,391 @@ +<sect1> +<title>Scripting API for Graph Backend</title> + +<para> + The data structure properties dialog allows access to configure settings specific to the Graph backend. + There, with <guilabel>Graph Type</guilabel> you can select the type of the graph. The meaning of these types is as follows: +</para> +<itemizedlist> + <listitem><para> + <guilabel>Graph</guilabel>: Graph at which same edges (with respect to start and end points) may not exist multiple times. + </para></listitem> + <listitem><para> + <guilabel>Multigraph</guilabel>: Graph at which same edges (with respect to start and end points) may exist multiple times. + </para></listitem> +</itemizedlist> + +<sect2> +<title>Graph Data Structure</title> +<para> +A graph objects holds the information of a data structure of type "Graph". +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + + <listitem> + <para> + <emphasis>name</emphasis> : + </para> + <para>The unique name of this data structure.</para> + </listitem> + +</itemizedlist> +</sect3> + +<sect3> +<title>Methods</title> +<variablelist> + + <varlistentry> + <term>nodes()</term> + <listitem> + <para>Return list all nodes in the graph.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>nodes()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>nodes(type)</term> + <listitem> + <para>Return list all nodes in the graph of specified type.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>nodes(type)</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>edges()</term> + <listitem> + <para>Return list all edges in the graph.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>edges()</function></funcdef> + + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>edges(type)</term> + <listitem> + <para>Return list all edges in the graph of specified type.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>edges(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createNode(type)</term> + <listitem> + <para>Create a new node of the specified type and return the created node. If the type is not registered, no node is created.</para> + <funcsynopsis><funcprototype> + <funcdef>GraphNode <function>createNode(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createNode()</term> + <listitem> + <para>Create a new node of default type and return the created node.</para> + <funcsynopsis><funcprototype> + <funcdef>GraphNode <function>createNode()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createEdge(from, to, type)</term> + <listitem> + <para>Create an edge from node "from" to node "to" of the specified type and return the created edge. If the type is not registered, no edge is created.</para> + <funcsynopsis><funcprototype> + <funcdef>GraphEdge <function>createEdge(from, to, type)</function></funcdef> + <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef> + <paramdef>GraphNode <parameter><replaceable>to</replaceable></parameter></paramdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createEdge(from, to)</term> + <listitem> + <para>Create an edge from node "from" to node "to" of default type and return the created edge.</para> + <funcsynopsis><funcprototype> + <funcdef>GraphEdge <function>createEdge(from, to)</function></funcdef> + <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef> + <paramdef>GraphNode <parameter><replaceable>to</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>distances(from)</term> + <listitem> + <para>Returns an array of shortest path lengths from this node to every other node in the graph.</para> + <funcsynopsis><funcprototype> + <funcdef>Array <function>distances(from)</function></funcdef> + <paramdef>GraphNode <parameter><replaceable>from</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + +</variablelist> +</sect3> +</sect2> + +<sect2> +<title>Graph Node</title> +<para> +A node is the data element of a graph. +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + + <listitem> + <para> + <emphasis>width</emphasis> : + </para> + <para>The size of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>x</emphasis> : + </para> + <para>The x-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>y</emphasis> : + </para> + <para>The y-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>id</emphasis> : + </para> + <para>The unique identifier of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>color</emphasis> : + </para> + <para>The color of this data element stated as hexadecimal value.</para> + </listitem> +</itemizedlist> +</sect3> + +<sect3> +<title>Methods</title> +<variablelist> + + <varlistentry> + <term>neighbors()</term> + <listitem> + <para>Return list all nodes connected to this node. This method respects if edges are directed.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>neighbors()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>edges()</term> + <listitem> + <para>Return a list of all edges (incoming and outgoing) of this node.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>edges()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>edges(type)</term> + <listitem> + <para>Return a list of all edges (incoming and outgoing) of this node of a specified type.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>edges(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>inEdges()</term> + <listitem> + <para>Return a list of incoming edges of this node.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>inEdges()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>inEdges(type)</term> + <listitem> + <para>Return a list of all incoming edges of this node of a specified type.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>inEdges(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>outEdges()</term> + <listitem> + <para>Return a list of all outgoing edges of this node.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>outEdges()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>outEdges(type)</term> + <listitem> + <para>Return a list of all outgoing edges of this node of a specified type.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>outEdges(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>edgesTo(target)</term> + <listitem> + <para>Return a list of all edges of this node to the specified node.</para> + <funcsynopsis><funcprototype> + <funcdef>array <function>edgesTo(target)</function></funcdef> + <paramdef>GraphNode <parameter><replaceable>target</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> +</variablelist> +</sect3> +</sect2> + + +<sect2> +<title>Graph Edge</title> +<para> +An Edge is the connection of two GraphNodes. Edges can be directed or undirected, depending on their type. +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + <listitem> + <para> + <emphasis>width</emphasis> : + </para> + <para>The width of the connection.</para> + </listitem> + + <listitem> + <para> + <emphasis>directed</emphasis> : + </para> + <para>If true, the connection is directed. Otherwise is connection is undirected.</para> + </listitem> + + <listitem> + <para> + <emphasis>from</emphasis> : + </para> + <para>Start of the connection.</para> + </listitem> + + <listitem> + <para> + <emphasis>to</emphasis> : + </para> + <para>End of the connection</para> + </listitem> + + <listitem> + <para> + <emphasis>color</emphasis> : + </para> + <para>ID of the connection type.</para> + </listitem> +</itemizedlist> +</sect3> + + +<sect3> +<title>Methods</title> +<variablelist> + + <varlistentry> + <term>remove()</term> + <listitem> + <para>Remove this connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>remove()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>add_property(name, value)</term> + <listitem> + <para>Add a new property to the connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>add_property(name, value)</function></funcdef> + <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef> + <paramdef>string <parameter><replaceable>value</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>remove_property(name)</term> + <listitem> + <para>Remove an existing property from the connection.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>remove_property(name)</function></funcdef> + <paramdef>string <parameter><replaceable>name</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + +</variablelist> +</sect3> +</sect2> + +</sect1> diff --git a/doc/apiLinkedListstructure.docbook b/doc/apiLinkedListstructure.docbook new file mode 100644 index 0000000..4320295 --- /dev/null +++ b/doc/apiLinkedListstructure.docbook @@ -0,0 +1,141 @@ +<sect1> +<title>Scripting API for Linked List Backend</title> +<sect2> +<title>Linked List Data Structure</title> +<para> +A list objects holds the information of a data structure of type "Linked List". +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + <listitem> + <para> + <emphasis>name</emphasis> : + </para> + <para>The unique name of this data structure.</para> + </listitem> +</itemizedlist> +</sect3> + + +<sect3> +<title>Methods</title> +<variablelist> + + <varlistentry> + <term>head()</term> + <listitem> + <para>Return head node of the list.</para> + <funcsynopsis><funcprototype> + <funcdef>ListNode <function>head()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>setHead(node)</term> + <listitem> + <para>Set the head of the list.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>setHead(node)</function></funcdef> + <paramdef>ListNode <parameter><replaceable>node</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createNode(type)</term> + <listitem> + <para>Create a new node of the specified type and return the created node. If the type is not registered, no node is created.</para> + <funcsynopsis><funcprototype> + <funcdef>ListNode <function>createNode(type)</function></funcdef> + <paramdef>int <parameter><replaceable>type</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> + + <varlistentry> + <term>createNode()</term> + <listitem> + <para>Create a new node of default type and return the created node.</para> + <funcsynopsis><funcprototype> + <funcdef>ListNode <function>createNode()</function></funcdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> +</variablelist> +</sect3> +</sect2> + + +<sect2> +<title>List Node</title> +<para> +A node is the data element of a linked list. +</para> + +<sect3> +<title>Properties</title> +<itemizedlist> + + <listitem> + <para> + <emphasis>width</emphasis> : + </para> + <para>The size of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>x</emphasis> : + </para> + <para>The x-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>y</emphasis> : + </para> + <para>The y-coordinate of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>id</emphasis> : + </para> + <para>The unique identifier of this data element.</para> + </listitem> + + <listitem> + <para> + <emphasis>color</emphasis> : + </para> + <para>The color of this data element stated as hexadecimal value.</para> + </listitem> +</itemizedlist> +</sect3> + + +<sect3> +<title>Methods</title> +<variablelist> + <varlistentry> + <term>pointTo(target)</term> + <listitem> + <para>Set pointer of this list node to the target node.</para> + <funcsynopsis><funcprototype> + <funcdef>void <function>pointTo(target)</function></funcdef> + <paramdef>ListNode <parameter><replaceable>target</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </listitem> + </varlistentry> +</variablelist> +</sect3> +</sect2> +</sect1> diff --git a/doc/apiRootedTreestructure.docbook b/doc/apiRootedTreestructure.docbook new file mode 100644 index 0000000..957b5d6 --- /dev/null +++ b/doc/apiRootedTreestructure.docbook @@ -0,0 +1,62 @@ +<sect1 id="scripting-backend-rootedtree"> +<title>Scripting API for Rooted Tree Backend</title> +<sect2> +<title>Rooted Tree Data Structure</title> +<para> + The data structure properties dialog allows access to configure settings specific to the Graph backend. + There, by checking the <guilabel>Show all pointers</guilabel> property, all pointers between the tree nodes are shown. + If unchecked, multiple pointers between same nodes are collapsed to one. +</para> +</sect2> + +<sect2> +<title>The Rooted Tree Structure</title> +<para> +Given a data structure object of type "Rooted Tree", the following properties can be read or written: +</para> +<programlisting> + ShowAllPointers // set to true if show all edges, set to false if multiple edges shall be compressed +</programlisting> +<para> +Given a data structure object of type "Rooted Tree", you can call the following member functions: +</para> +<programlisting> + node add_data(string name); // add a node to tree with given name + void set_root_node(node root); // set root as root node of the tree + node root_node(); // return root node of the tree +</programlisting> +</sect2> + +<sect2> +<title>Rooted Tree Nodes</title> +<para> +Given a node object of type "Rooted Tree", the following properties can be read or written: +</para> +<programlisting> + int numberOfChilds // set the number of (allowed) children for this node + node left_child // read only: node that is the left child + node right_child // read only: node that is the right child + node node_parent // read only: node that is the parent +</programlisting> +<para> +Given a node object of type "Rooted Tree", you can call the following member functions: +</para> +<programlisting> + node add_left_child(node child); // add left child + node add_right_child(node child); // add right child + node add_child(node child, int i); // add a child as the i-th child of the node + node add_node_parent(node child); // add parent (only successful if no parent set, yet) + node left_child(); // return right child + node right_child(); // return left child + node child_at(int i); // return the i-th child of the node + node node_parent(); // return the node's parent +</programlisting> +</sect2> + +<sect2> +<title>Rooted Tree Edges</title> +<para> +Given edges of a data structure of type "Rooted Tree", only the properties of the base data structure are available. +</para> +</sect2> +</sect1> diff --git a/doc/chapterImportExport.docbook b/doc/chapterImportExport.docbook new file mode 100644 index 0000000..bb940c5 --- /dev/null +++ b/doc/chapterImportExport.docbook @@ -0,0 +1,82 @@ +<title>Import and Export</title> +<sect1 id="import-export-projects"> + <title>Exchange &rocs; Projects</title> + <para> + &rocs; projects can be imported and exported as archived <literal>.tar.gz</literal> files. + These archives can be used to exchange projects. + Import and Export can be done with <menuchoice><guimenu>File</guimenu> <guimenuitem>Import Project</guimenuitem></menuchoice> and <menuchoice><guimenu>File</guimenu> <guimenuitem>Export Project</guimenuitem></menuchoice>, respectively. + </para> +</sect1> + +<sect1 id="import-export-graphs"> + <title>Import and Export of Graph Documents</title> + <para>&rocs; currently supports import and export of the following file formats:</para> + <itemizedlist> + <listitem><para>DOT files, also known as Graphviz files</para></listitem> + <listitem><para>GML files</para></listitem> + <listitem><para>Trivial Graph Format files</para></listitem> + </itemizedlist> + +<sect2 id="format-specification-tgf"> +<title>Trivial Graph File Format</title> +<para> + The <emphasis>Trivial Graph Format</emphasis> (TGF) is a simple text-based file format for describing graphs. + A TGF file consists of a list of node definitions, that map the node IDs to labels, followed by a list of the edges. + In this format it is only possible to have one label per node and one value per edge. + &rocs; interprets imported graphs as undirected graphs. + Exported graphs will contain two edges per connection if connections are bidirectional. +</para> + +<sect3> +<title>Format Specification</title> + <itemizedlist> + <listitem><para>The file starts with a list of nodes (one node per line), followed by a line with the only character "#", followed by a list of edges (one edge per line).</para></listitem> + <listitem><para>A node consists of an integer (identifier), followed by a space, followed by an arbitrary string.</para></listitem> + <listitem><para>An edge consists of two integers (identifiers) separated by a space, followed by a space, followed by an arbitrary string. It is assumed that the directed edge points from the first identifier to the second identifier.</para></listitem> + </itemizedlist> +</sect3> +<sect3> +<title>Example</title> +<programlisting> +1 starting node +2 transmitter +3 sink +# +1 2 blue +2 1 red +2 3 green +</programlisting> +</sect3> +</sect2> + +<sect2 id="format-specification-dot"> +<title>DOT Language / Graphviz Graph File Format</title> +<para> + The DOT language is a plain text graph description language that allows both,a good human readable representation of graphs as well as an efficient processing by graph layout programs. + DOT is the default file format for the Graphviz graph visualization suite, but is also widely used by other graph tools. + The usual file endings for DOT are <emphasis>.gv</emphasis> and <emphasis>.dot</emphasis>. +</para> + +<sect3> +<title>Unsupported Features</title> +<para> + &rocs; can parse every graph file that contains a graph specified according to the DOT language specification<footnote><para>http://www.graphviz.org/content/dot-language</para></footnote>. + The support of language features is complete, despite of the following exceptions: +</para> + <itemizedlist> + <listitem><para>subgraph: Due to the lack of a subgraph concept in &rocs;, subgraphs are only imported as a set of date elements and connections. Especially, connections to or from subgraphs are not imported.</para></listitem> + <listitem><para>&HTML; and &XML; attributes: Attributes (like labels) that contain &HTML; or &XML; syntax are read unchanged. Especially, not adjustment of fonts and styles are read from those attributes.</para></listitem> + </itemizedlist> +</sect3> +<sect3> +<title>Example</title> +<programlisting> +digraph myGraph { + a -> b -> c; + b -> d; +} +</programlisting> +</sect3> +</sect2> + +</sect1> diff --git a/doc/index.docbook b/doc/index.docbook index 706f571..e6e1b67 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -5,7 +5,14 @@ <!ENTITY package "kdeedu"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> - <!ENTITY scriptingapi SYSTEM "scripting-api.docbook"> + + <!ENTITY apiConsole SYSTEM "apiConsole.docbook"> + <!ENTITY apiDatastructure SYSTEM "apiDatastructure.docbook"> + <!ENTITY apiGraphstructure SYSTEM "apiGraphstructure.docbook"> + <!ENTITY apiLinkedListstructure SYSTEM "apiLinkedListstructure.docbook"> + <!ENTITY apiRootedTreestructure SYSTEM "apiRootedTreestructure.docbook"> + + <!ENTITY chapterImportExport SYSTEM "chapterImportExport.docbook"> ]> <book id="rocs" lang="&language;"> @@ -245,7 +252,7 @@ while (E.length > 0) { } } } -output("Vertex Cover contains " + C.length + " nodes."); +Console.log("Vertex Cover contains " + C.length + " nodes."); </programlisting> </sect2> @@ -496,6 +503,7 @@ The created data structure is added to the currently selected graph document. </sect1> </chapter> + <chapter id="scripting"> <title>Writing and Executing Algorithms in &rocs;</title> @@ -511,299 +519,6 @@ It is important to know that changes done by the scripting engine are directly r Hence, the scripts actually modify the data structures. </para> -<sect1 id="scripting-data-structure"> -<title>The Base Data Structure Elements</title> -<para> -Every backend provides a special set of functions and properties for its data structures and their elements. -But also every backend provides the properties and functions that are defined for the base data structure. -Hence, everything explained in this sections is available for every data structure backend. -</para> -<sect2><title>Base Data Structures Properties</title> -<para> -Data structures are identified by their names. -Assuming you created a data structure with name <literal>testgraph</literal>, then you can access the data structure simply by writing this identifier. -For example, to get an array with all data elements in the given data structure, you can write <literal>testgraph.list_nodes();</literal> in the script. -</para> - -<sect3> -<title>Base Data Structure Properties and Functions</title> -<para> -Each data structure <literal>testgraph</literal> has the following properties that can be read or written by <literal>testgraph.property</literal>: -</para> -<programlisting> - string name // identification of the data structure -</programlisting> -</sect3> -</sect2> - -<sect2> -<title>Base Data Element Properties and Functions</title> -<para> -Each data element has the following properties that can be read or written: -</para> -<programlisting> - double x // x coordinate of current position - double y // y coordinate of current position - double width // size - string value // value - int id // unique identifier for data element - string name // name - string color // color in HEXA -</programlisting> -<para> -Further, every dynamic property of a data element can be accessed by its name. -</para> - -<para> -Each data element object provides the following methods: -</para> -<programlisting> - int type(); // data type of data element - int set_type(int); // set data type of the data element - void add_property(string name, // add dynamic property to data element with specified name and value - string value); - array adj_data(); // list of adjacent data - array adj_pointers(); // list of adjacent pointers - array input_pointers(); // list of input pointers - array output_pointers(); // list of output pointers - array loop_pointers(); // list of pointers forming a self-loop - array connected_pointers(target); // list of pointers pointing to 'target' - void remove(); // remove this data element -</programlisting> -</sect2> - -<sect2> -<title>Base Pointer Properties and Functions</title> -<para> -Each pointer has the following properties that can be read or written: -</para> -<programlisting> - string color // color in HEXA - string value // value - string name // name - double width // width - string style // value out of: dot, dash, dash dot, solid -</programlisting> -<para> -Further, every dynamic property of a pointer can be accessed by its name. -</para> - -<para> -Each pointer object provides the following methods: -</para> -<programlisting> - int type(); // pointer type of pointer - int set_type(int); // set pointer type of the pointer - void add_property(string name, // add dynamic property to data element with specified name and value - string value); - node start(); // start node of the pointer - node end(); // target node of the pointer - void remove(); // remove this pointer -</programlisting> -</sect2> -</sect1> - -<sect1 id="scripting-backend-graph"> -<title>The Graph Backend</title> -<sect2> -<title>Graph Properties and Functions</title> - - - -<sect3> -<title>Graph Backend Specific Properties</title> -<para> - The data structure properties dialog allows access to configure settings specific to the Graph backend. - There, with <guilabel>Graph Type</guilabel> you can select the type of the graph. The meaning of these types is as follows: -</para> -<itemizedlist> - <listitem><para> - <guilabel>Graph</guilabel>: Graph at which same edges (with respect to start and end points) may not exist multiple times. - </para></listitem> - <listitem><para> - <guilabel>Multigraph</guilabel>: Graph at which same edges (with respect to start and end points) may exist multiple times. - </para></listitem> -</itemizedlist> -</sect3> - -<sect3> -<title>The Graph Structure</title> -<para> -Given a data structure object of type "Graph", you can call the following member functions: -</para> -<programlisting> - array list_nodes(); // list of all nodes of the graph - array list_nodes(int type); // list of all nodes of given type - array list_edges(); // list of all edges of the graph - array list_edges(int type); // list of all edges of given type - node add_node(name); // add new node and returns it - edge add_edge(node from, node to); // add new edge from 'from' to 'to' and returns it - array overlay_edges(int overlayID); // list of all edges in given overlay - edge add_overlay_edge(node from, - node to, - int overlayID); // add edge of given pointer type/in specified overlay -</programlisting> -</sect3> - -<sect3> -<title>Graph Nodes</title> -<para> -Given a data structure object of type "Graph", you can call the following member functions on the graph nodes additionally to the properties provided by the Data elements: -</para> -<programlisting> - array adj_nodes(); // list of all adjacent nodes - array adj_edges(); // list of connected edges - array input_edges(); // list of input edges - array output_edges(); // list of all output edges - array loop_edges(); // list of all edges looping to the node - array connected_edges(node target); // all edges that connect this node with node 'target' -</programlisting> -</sect3> - -<sect3> -<title>Graph Edges</title> -<para> -Given edges of a data structure of type "Graph", only the properties of the base data structure are available. -</para> -</sect3> -</sect2> - -<sect2> -<title>Graph Structure Algorithms</title> -<para> -The graph backend provides some special functions that can be used from the scripting engine.</para> -<variablelist> -<varlistentry> -<term>Shortest Path Computation</term> -<listitem> - <para>Compute the shortest path between the nodes <emphasis>start</emphasis> and <emphasis>end</emphasis>. Both nodes must be of the same graph. This computation respects if the graph is directed or undirected.</para> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>dijkstra_shortest_path</function></funcdef> - <paramdef>node <parameter><replaceable>start</replaceable></parameter></paramdef> - <paramdef>node <parameter><replaceable>end</replaceable></parameter></paramdef> - </funcprototype> - </funcsynopsis> -</listitem> -</varlistentry> -<varlistentry> -<term>Shortest Path Distances</term> -<listitem> - <para>Compute the shortest path distances from node <emphasis>start</emphasis> to all other nodes of the graph. This computation respects if the graph is directed or undirected.</para> - <funcsynopsis> - <funcprototype> - <funcdef>array <function>distances</function></funcdef> - <paramdef>node <parameter><replaceable>start</replaceable></parameter></paramdef> - </funcprototype> - </funcsynopsis> -</listitem> -</varlistentry> -</variablelist> -</sect2> -</sect1> - -<sect1 id="scripting-backend-linkedlist"> -<title>The Linked List Backend</title> -<sect2> -<title>Linked List Properties and Functions</title> - -<sect3> -<title>The Linked List Structure</title> -<para> -Given a data structure object of type "Linked List", you can call the following member functions: -</para> -<programlisting> - node begin(); // gives the head node of the linked list - setBegin(node begin): // set node begin as begin of list and rearrange list - createNode(); // create a new list node -</programlisting> -</sect3> - -<sect3> -<title>Linked List Nodes</title> -<para> -Given a data structure object of type "Linked List", you can call the following member functions on the graph nodes additionally to the properties provided by the Data elements: -</para> -<programlisting> - node front(); // returns the node's predecessor -</programlisting> -</sect3> - -<sect3> -<title>Linked List Edges</title> -<para> -Given edges of a data structure of type "Linked List", only the properties of the base data structure are available. -</para> -</sect3> -</sect2> -</sect1> - -<sect1 id="scripting-backend-rootedtree"> -<title>The Rooted Tree Backend</title> -<sect2> -<title>Rooted Tree Properties and Functions</title> - -<sect3> -<title>Rooted Tree Backend</title> -<para> - The data structure properties dialog allows access to configure settings specific to the Graph backend. - There, by checking the <guilabel>Show all pointers</guilabel> property, all pointers between the tree nodes are shown. - If unchecked, multiple pointers between same nodes are collapsed to one. -</para> -</sect3> - -<sect3> -<title>The Rooted Tree Structure</title> -<para> -Given a data structure object of type "Rooted Tree", the following properties can be read or written: -</para> -<programlisting> - ShowAllPointers // set to true if show all edges, set to false if multiple edges shall be compressed -</programlisting> -<para> -Given a data structure object of type "Rooted Tree", you can call the following member functions: -</para> -<programlisting> - node add_data(string name); // add a node to tree with given name - void set_root_node(node root); // set root as root node of the tree - node root_node(); // return root node of the tree -</programlisting> -</sect3> - -<sect3> -<title>Rooted Tree Nodes</title> -<para> -Given a node object of type "Rooted Tree", the following properties can be read or written: -</para> -<programlisting> - int numberOfChilds // set the number of (allowed) children for this node - node left_child // read only: node that is the left child - node right_child // read only: node that is the right child - node node_parent // read only: node that is the parent -</programlisting> -<para> -Given a node object of type "Rooted Tree", you can call the following member functions: -</para> -<programlisting> - node add_left_child(node child); // add left child - node add_right_child(node child); // add right child - node add_child(node child, int i); // add a child as the i-th child of the node - node add_node_parent(node child); // add parent (only successful if no parent set, yet) - node left_child(); // return right child - node right_child(); // return left child - node child_at(int i); // return the i-th child of the node - node node_parent(); // return the node's parent -</programlisting> -</sect3> - -<sect3> -<title>Rooted Tree Edges</title> -<para> -Given edges of a data structure of type "Rooted Tree", only the properties of the base data structure are available. -</para> -</sect3> -</sect2> -</sect1> <sect1 id="scripting-controls"> <title>Controlling the Script Execution</title> @@ -834,8 +549,8 @@ Given edges of a data structure of type "Rooted Tree", only the properties of th You can control the text that is displayed at the script output by the following functions: </para> <programlisting> - output(string message); // displays the message as script output - debug(string message); // displays the message as debug output + Console.log(string message); // displays the message as script output + Console.debug(string message); // displays the message as debug output </programlisting> </sect2> @@ -877,92 +592,30 @@ Given edges of a data structure of type "Rooted Tree", only the properties of th </sect1> </chapter> -<chapter id="import-export"> -<title>Import and Export</title> -<sect1 id="import-export-projects"> - <title>Exchange &rocs; Projects</title> - <para> - &rocs; projects can be imported and exported as archived <literal>.tar.gz</literal> files. - These archives can be used to exchange projects. - Import and Export can be done with <menuchoice><guimenu>File</guimenu> <guimenuitem>Import Project</guimenuitem></menuchoice> and <menuchoice><guimenu>File</guimenu> <guimenuitem>Export Project</guimenuitem></menuchoice>, respectively. - </para> -</sect1> -<sect1 id="import-export-graphs"> - <title>Import and Export of Graph Documents</title> - <para>&rocs; currently supports import and export of the following file formats:</para> - <itemizedlist> - <listitem><para>DOT files, also known as Graphviz files</para></listitem> - <listitem><para>GML files</para></listitem> - <listitem><para>Trivial Graph Format files</para></listitem> - </itemizedlist> - -<sect2 id="format-specification-tgf"> -<title>Trivial Graph File Format</title> -<para> - The <emphasis>Trivial Graph Format</emphasis> (TGF) is a simple text-based file format for describing graphs. - A TGF file consists of a list of node definitions, that map the node IDs to labels, followed by a list of the edges. - In this format it is only possible to have one label per node and one value per edge. - &rocs; interprets imported graphs as undirected graphs. - Exported graphs will contain two edges per connection if connections are bidirectional. -</para> - -<sect3> -<title>Format Specification</title> - <itemizedlist> - <listitem><para>The file starts with a list of nodes (one node per line), followed by a line with the only character "#", followed by a list of edges (one edge per line).</para></listitem> - <listitem><para>A node consists of an integer (identifier), followed by a space, followed by an arbitrary string.</para></listitem> - <listitem><para>An edge consists of two integers (identifiers) separated by a space, followed by a space, followed by an arbitrary string. It is assumed that the directed edge points from the first identifier to the second identifier.</para></listitem> - </itemizedlist> -</sect3> -<sect3> -<title>Example</title> -<programlisting> -1 starting node -2 transmitter -3 sink -# -1 2 blue -2 1 red -2 3 green -</programlisting> -</sect3> -</sect2> - -<sect2 id="format-specification-dot"> -<title>DOT Language / Graphviz Graph File Format</title> +<chapter id="scripting-API"> +<title>Scripting Engine API</title> <para> - The DOT language is a plain text graph description language that allows both,a good human readable representation of graphs as well as an efficient processing by graph layout programs. - DOT is the default file format for the Graphviz graph visualization suite, but is also widely used by other graph tools. - The usual file endings for DOT are <emphasis>.gv</emphasis> and <emphasis>.dot</emphasis>. +Every backend provides a special set of functions and properties for its data structures and their elements. +But also every backend provides the properties and functions that are defined for the base data structure. </para> -<sect3> -<title>Unsupported Features</title> -<para> - &rocs; can parse every graph file that contains a graph specified according to the DOT language specification<footnote><para>http://www.graphviz.org/content/dot-language</para></footnote>. - The support of language features is complete, despite of the following exceptions: -</para> - <itemizedlist> - <listitem><para>subgraph: Due to the lack of a subgraph concept in &rocs;, subgraphs are only imported as a set of date elements and connections. Especially, connections to or from subgraphs are not imported.</para></listitem> - <listitem><para>&HTML; and &XML; attributes: Attributes (like labels) that contain &HTML; or &XML; syntax are read unchanged. Especially, not adjustment of fonts and styles are read from those attributes.</para></listitem> - </itemizedlist> -</sect3> -<sect3> -<title>Example</title> -<programlisting> -digraph myGraph { - a -> b -> c; - b -> d; -} -</programlisting> -</sect3> -</sect2> +&apiDatastructure; -</sect1> +&apiGraphstructure; + +&apiLinkedListstructure; + +&apiRootedTreestructure; + +&apiConsole; +</chapter> + + +<chapter id="import-export"> +&chapterImportExport; </chapter> -&scriptingapi; <!--Scripting Interface API Documentation--> <chapter id="credits"> <title>Credits and License</title> @@ -975,14 +628,14 @@ digraph myGraph { <listitem><para>Copyright 2008 Ugo Sangiori (ugorox AT gmail.com)</para></listitem> <listitem><para>Copyright 2008-2012 Tomaz Canabrava (tcanabrava AT kde.org)</para></listitem> <listitem><para>Copyright 2008-2012 Wagner Reck (wagner.reck AT gmail.com)</para></listitem> - <listitem><para>Copyright 2011-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem> + <listitem><para>Copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)</para></listitem> </itemizedlist> <para>Documentation Copyright:</para> <itemizedlist> <listitem><para>Documentation copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</para></listitem> <listitem><para>Documentation copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)</para></listitem> - <listitem><para>Documentation copyright 2011-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem> + <listitem><para>Documentation copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)</para></listitem> </itemizedlist> <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
