:- module(daVinci).
:- export daVinci_draw_graph / 1.
:- export daVinci_exit / 0.
:- export daVinci_edge_attribute / 3.
:- export daVinci_node_attribute / 3.
:- export daVinci_edge / 3.
:- export daVinci_node / 2.
:- export daVinci_node / 1.
:- export daVinci_end / 0.
:- export daVinci_begin / 0.
:- comment(summary, "This library provides a simple interface to the daVinci graph drawing tool").
:- comment(desc, html("\nThis library provides a simple interface to the daVinci graph drawing\ntool.  It allows to specify a graph with nodes, edges and their\nattributes, and draws the graph inside the daVinci tool.  The\ninterface does not allow callbacks back from the daVinci system, nor\ndoes it handle the customisation of the daVinci interface that is\npossible.<p> The daVinci system is a graph drawing tool developed at\nthe University of Bremen in Germany and is freely available for\nnon-profit and internal use.  Please download the software from their\nWEB site <a\nhref=http://www.informatik.uni-bremen.de/agbkb/forschung/daVinci/daVinci.html>daVinci\nHome page</a> and register with the developers.  We do not provide the\nexecutable as part of this library.<p> The communication between\nEclipse and daVinci is handled by a socket interface, where we\nexchange text messages terminated by a line-feed.  In order to gain a\nbit of flexibility in the interface, we use two string streams to\nbuffer information about edges and attributes.  The three streams used\nfor communication are called daVinciOut, daVinciEdge and\ndaVinciAttribute.  If the stream daVinciOut exists, we assume that the\ndaVinci server is running and that we can send information to it.  If\nthe stream does not exist, then we open the daVinci program in server\nmode and connect the stream to the socket connection on the port\n2542.<p> ")).
:- comment(author, "H. Simonis").
:- comment(date, "$Date: 2006/09/23 01:54:55 $").
:- comment(daVinci_begin / 0, [summary : "Start the connection to daVinci and begin the transfer of a new graph", args : [], desc : html("\nThis commands opens the connection to the daVinci system if not\nalready open and starts the information about a new graph.  This\npredicate should be called once for each graph to be transmitted.  <p>\n"), fail_if : "no", resat : no, eg : "\n:-use_module(daVinci).\n\ntop:-\n\tdaVinci_begin,\n\tdaVinci_node(1),\n\tdaVinci_node(2,'a bigger label'),\n\tdaVinci_node(aa),\n\n\tdaVinci_edge(1,1,2),\n\tdaVinci_edge(2,2,2),\n\tdaVinci_edge(3,2,aa),\n\n\tdaVinci_node_attribute(1,'COLOR','red'),\n\tdaVinci_node_attribute(2,'COLOR','dodgerblue'),\n\n\tdaVinci_node_attribute(2,'FONTSTYLE','italic'),\n\tdaVinci_edge_attribute(3,'EDGECOLOR','blue'),\n\tdaVinci_edge_attribute(3,'EDGEPATTERN','dashed'),\n\tdaVinci_node(4),\n\tdaVinci_edge(4,2,4),\n\tdaVinci_edge(5,4,2),\n\tdaVinci_end.\n", see_also : [daVinci_end / 0]]).
:- comment(daVinci_draw_graph / 1, [summary : "Draw a graph in lib(graph_algorithms) format", amode : daVinci_draw_graph(+), args : ["Graph" : "a graph description"], eg : "\n:- lib(graph_algorithms).\n:- lib(daVinci).\n\ntop :-\n\tmake_random_graph(10,20,true,true,true,Graph),\n\tdaVinci_draw_graph(Graph).\n", desc : html("\nThis predicate takes a graph in the format defined by the\nlibrary lib(graph_algorithms), and draws it.\n")]).
:- comment(daVinci_edge / 3, [summary : "This command adds an edge between two nodes in the graph.", amode : daVinci_edge(?, ?, ?), args : ["Name" : "a Prolog term ", "Node1" : "a Prolog term ", "Node2" : "a Prolog term "], desc : html("\nThis command adds an edge between two nodes in the graph.  The edge is\nfrom Node1 to Node2.  Both nodes must exist in the final graph, but do\nnot need to be defined before the edge is entered.  Each edge must\nhave a unique name, typically a number or an atom.  Names for nodes\nand edges do not have to be disjoint.  <p> "), fail_if : "no", resat : no, eg : " see daVinci_begin/0 ", see_also : [daVinci_edge_attribute / 3]]).
:- comment(daVinci_edge_attribute / 3, [summary : "Set an attribute for an edge in the graph", amode : daVinci_edge_attribute(?, ++, ++), args : ["Name" : " a Prolog term", "Type" : " an atom", "Value" : " an atom"], desc : html("\nThis predicate is used to set some attribute of an edge in the graph. \nFor a list of all possible attributes and their values, please refer\nto the daVinci documentation\n<a href=http://www.tzi.de/daVinci/docs/referenceF.html>Reference\nManual</a>.  Typical attributes are 'EDGECOLOR' or 'EDGEPATTERN' to\nset the appearance of the edge.  Note that it is currently not\npossible in daVinci to specify labels for the edges.  <p> "), fail_if : "", resat : yes, eg : " see daVinci_begin/0 ", see_also : [daVinci_edge / 3]]).
:- comment(daVinci_end / 0, [summary : "This commands ends the information about a graph and calls daVinci to draw it.", args : [], desc : html("\nThis commands is called once when all information about a graph have\nbeen transmitted.  It sends the graph description to the daVinci tool\nand causes it to bbe drawn.  After this command, the next daVinci\ncommand should be daVinci_begin/0 to begin the information about the\nnext graph.  <p> "), fail_if : "fails if the stream daVinciEdge does not exist", resat : no, eg : "\nsee daVinci_begin/0\n", see_also : [daVinci_begin / 0]]).
:- comment(daVinci_exit / 0, [summary : "This commands closes the connection and exits daVinci.", args : [], see_also : [daVinci_begin / 0]]).
:- comment(daVinci_node / 1, [summary : "Define one node for the graph. The label of the node is equal to its name.", amode : daVinci_node(?), args : ["Node" : " a Prolog term, normally a number or an atom"], desc : html("\nThis command defines one node for the graph.  The label of the node is\nequal to the name of the node.  Often, the name is a number or an\natom, but it can be any Prolog structure.  The node name must be\nunique, and should not contain backslash, tilde or double quote\ncharacters.<p> "), fail_if : "no", resat : no, eg : "\nsee daVinci_begin/0\n", see_also : [daVinci_node / 2, daVinci_node_attribute / 3]]).
:- comment(daVinci_node / 2, [summary : "Defines a node in the graph. The label of the node can be different from the name.", amode : daVinci_node(?, ?), args : ["Node" : " a Prolog term, often a number or an atom", "Info" : " a Prolog term"], desc : html("\nThis command defines one node for the graph.  The label of the node is\ngiven as the second argument, and can be different from the name. \nBoth arguments can be arbitrary Prolog terms, but the name often is a\nnumber of an atom.  The name of each node must be unique, and should\nnot contain backslash, tilde or double quote characters.  <p> "), fail_if : "no", resat : no, eg : "\nsee daVinci_begin/0\n", see_also : [daVinci_node / 1, daVinci_node_attribute / 3]]).
:- comment(daVinci_node_attribute / 3, [summary : "Set an attribute for a node in the graph", amode : daVinci_node_attribute(?, ++, ++), args : ["Name" : " a Prolog Term", "Type" : " an atom", "Value" : " an atom "], desc : html("\nThis predicate is used to set an attribute of a node in the graph. \nFor a list of all possible attributes and their values, please refer\nto the daVinci documentation <a\nhref=http://www.tzi.de/daVinci/docs/referenceF.html>Reference\nManual</a>.  Typical attributes are 'COLOR','FONTSYTLE','BORDER' to\nset the appearance of the node, and 'OBJECT' to change the label\ndisplayed in the node.  <p> "), fail_if : "no", resat : no, eg : "\nsee daVinci_begin/0\n", see_also : [daVinci_node / 1, daVinci_node / 2]]).
