(by Mattias Werner - July 13, 1998)

This file contains examples for commands that can be send to the daVinci
V2.1.x API. To play with the API you can send the commands by starting daVinci
in a shell with commandline option -pipe and copy/paste the commands into the 
shell. The answers from the API are printed in the shell. 

Some important notes:

  1. Before you start you have to replace all three occurances of '....' in 
     the commands below by the absolute path of the directory where you've 
     installed daVinci (i.e the value of shell variable $DAVINCIHOME).

  2. Send only one command at a time to the API. Don't send the comment 
     lines which are enclosed by '/*' and '*/'!
	
  3. This document with daVinci API commands is not a tutorial. It's a
     text to show the usage of each command, but not how to combine them 
     in order to use particular features of daVinci . Refer to the online 
     documentation for detailed information about the API.
     
-----------------------------------------------------------------------------

1. Commands of category graph(...): 
=================================== 

graph(new([l("1",n("A",[a("OBJECT","Node 1")],[l("1>2",e("A",[],l("2",n("B",[a("OBJECT","Node 2")],[l("2>4",e("A",[],l("4",n("A",[a("OBJECT","Node 4")],[])))),l("2>5",e("C",[],l("5",n("A",[a("OBJECT","Node 5")],[]))))])))),l("1>3",e("C",[],l("3",n("B",[a("OBJECT","Node 3")],[l("3>6",e("C",[],l("6",n("A",[a("OBJECT","Node 6")],[])))),l("3>4",e("C",[],r("4")))]))))]))]))
	/* 1.1.  Sends a graph in term representation format for 	*/
	/* 	 visualization.						*/

graph(new_placed([l("1",n("A",[a("OBJECT","Node 1")],[l("1>2",e("A",[],l("2",n("B",[a("OBJECT","Node 2")],[l("2>4",e("A",[],l("4",n("A",[a("OBJECT","Node 4")],[])))),l("2>5",e("C",[],l("5",n("A",[a("OBJECT","Node 5")],[]))))])))),l("1>3",e("C",[],l("3",n("B",[a("OBJECT","Node 3")],[l("3>6",e("C",[],l("6",n("A",[a("OBJECT","Node 6")],[])))),l("3>4",e("C",[],r("4")))]))))]))]))
	/* 1.2.  Same as above, put starts the layout algorithm (i.e.   */
	/* 	 edge crossing minimization) before showing the graph.	*/

graph(update([new_node("7","C",[a("OBJECT","Node 7")]),new_edge("7>2","B",[],"7","2")]))
	/* 1.3.  Updates the structure of the current graph which was  	*/
	/*	 loaded with command 1.2 above.     			*/

graph(change_attr([node("2",[a("COLOR","#f20fa2"),a("OBJECT","New Text\n   Here!")]),edge("2>5",[a("EDGEPATTERN","double"),a("EDGECOLOR","red")])]))
	/* 1.4.  Updates node/edge attributes of the current graph  	*/
	/*	 which was loaded with command 1.2 above.  		*/


2. Commands of category multi(...): 
=================================== 

multi(new_context)
	/* 2.1.  Opens an additional context to visualize another graph.*/

multi(open_context("some context id"))
	/* 2.2.  Same as above, but with a given context-id. 		*/

multi(set_context("some context id"))
	/* 2.3	 Sets the current context which is the graph affected by*/
	/*	 all the other API commands.				*/

	
3. Commands of category menu(...): 
================================== 

menu(file(new))
	/* 3.1.	 Removes the graph and clear the window.		*/
	
menu(file(open_graph("..../example_graphs/graph_example.daVinci")))
	/* 3.2.	 Loads a graph in term representation format from file.	*/
	
menu(file(open_graph_placed("..../example_graphs/graph_example.daVinci")))
	/* 3.3.  Same as above, put starts the layout algorithm (i.e.   */
	/* 	 edge crossing minimization) before showing the graph.	*/
	
menu(file(open_status("..../example_graphs/xerox_star.status")))
	/* 3.4.	 Loads a graph in status format from file.		*/

menu(file(save_graph("/tmp/xerox_star.daVinci")))
	/* 3.5.	 Saves the graph in term representation format to a 	*/
	/*	 file.							*/

menu(file(save_status("/tmp/xerox_star.status")))
	/* 3.6.	 Saves the graph in status format to a file.		*/

menu(file(print("/tmp/xerox_star.ps")))
	/* 3.7.	 Saves the graph in PostScript format to a file.	*/

menu(file(print))
	/* 3.8.	 Opens the print dialog window.				*/
	
menu(file(close))
	/* 3.9.	 Closes the current context.				*/

menu(file(exit))
	/* 3.10. Exits daVinci.	Afterwards, start daVinci again and	*/
	/* 	 send command 3.4.

menu(view(open_new_view))
	/* 3.11. Opens another view window to the same graph.		*/

menu(view(open_survey_view))
	/* 3.12. Opens a survey view window to the same graph.		*/

menu(view(full_scale))
	/* 3.13. Sets the scale to 100%.				*/

menu(view(fit_scale_to_window))
	/* 3.14. Sets the scale such that the graph fits into the 	*/
	/* 	 window.						*/

menu(view(scale(50)))
	/* 3.15. Sets the scale to the given value between 1 and 100.	*/

menu(view(scale))
	/* 3.16. Opens the scale dialog window.				*/
	
menu(view(graph_info))
	/* 3.17. Opens the graph info dialog window.			*/
	
menu(view(daVinci_info))
	/* 3.18. Opens the daVinci info dialog window.			*/
	
menu(navigation(select_parents(["Alto"])))
	/* 3.19. Selects all parent nodes of the given node(s) in the	*/
	/*	 graph previously loaded before with command 3.4.	*/

menu(navigation(select_siblings(["Alto"])))
	/* 3.20. Selects all parent nodes of the given node(s) in the	*/
	/*	 graph previously loaded before with command 3.4.	*/

menu(navigation(select_children(["Alto"])))
	/* 3.21. Selects all parent nodes of the given node(s) in the	*/
	/*	 graph previously loaded before with command 3.4.	*/

menu(navigation(navigator("Alto",down,false)))
	/* 3.22. Navigates in the given direction in the graph 		*/
	/*	 previously loaded before with command 3.4. by starting	*/
	/*	 at the given node.					*/

menu(navigation(navigator))
	/* 3.23. Opens the navigator dialog window.			*/

menu(navigation(find("mac",false,false)))
	/* 3.24. Searches a node with text "mac" in the graph previously*/
	/*	 loaded before with command 3.4. The two boolean flags  */
	/*	 are used for considering the case and exact match.	*/

menu(navigation(find))
	/* 3.25. Opens the find dialog window.				*/

menu(abstraction(hide_subgraph(["Alto"])))
	/* 3.26. Hides the subgraph of the given nodes(s) in the graph 	*/
	/*	 previously loaded before with command 3.4. 		*/

menu(abstraction(show_subgraph(["Alto"])))
	/* 3.27. Shows the subgraph again of the given nodes(s) in the  */
	/*	 graph previously loaded before with command 3.4. 	*/
	
menu(abstraction(restore_all_subgraphs))
	/* 3.28. Restores all subgraph abstractions in one step	 	*/

menu(abstraction(hide_edges(["Alto"])))
	/* 3.29. Hides the edges of the given nodes(s) in the graph 	*/
	/*	 previously loaded before with command 3.4. 		*/

menu(abstraction(show_edges(["Alto"])))
	/* 3.30. Shows the edges again of the given nodes(s) in the  */
	/*	 graph previously loaded before with command 3.4. 	*/
	
menu(abstraction(restore_all_edges))
	/* 3.31. Restores all egde abstractions in one step.	 	*/

menu(layout(improve_all))
	/* 3.32. Start the layout algorithm for the whole graph.	*/

menu(layout(improve_edges))
	/* 3.33. Start the layout algorithm only for the dummies	*/
	/*	 to get a better edge routing.				*/

menu(layout(improve_spacing))
	/* 3.34. Calculates a more compact layout which is useful after	*/
	/*	 hiding	subgraphs.					*/

menu(layout(orientation(left_right)))
	/* 3.35. Switches the layout orientation.			*/


4. Commands of category app_menu(...): 
====================================== 

app_menu(create_menus([submenu_entry("applmenu","Application",[menu_entry("applmenu A","Command A"),menu_entry("applmenu B","Command B"),blank,submenu_entry("applmenu_sub","Submenu",[menu_entry("applmenu C","Command C"),menu_entry("applmenu D","Command D"),])])]))
	/* 4.1.	 Attaches some menus to daVinci's Edit menu. The menus 	*/
	/*	 can be activated with command 4.2.			*/
	
app_menu(activate_menus(["applmenu","applmenu A","applmenu_sub","applmenu C","applmenu D"]))
	/* 4.2.	 Activates menus previously created with command 4.1.	*/

app_menu(create_icons([icon_entry("icon 1","testicon.xbm","Explanation for icon 1"),icon_entry("icon 2","testicon.xbm","Explanation for icon 2"),blank,icon_entry("icon 3","testicon.xbm","Explanation for icon 3"),blank]))
	/* 4.3.	 Attaches some icons to daVinci's icon bar. The icons 	*/
	/*	 can be activated with command 4.4.			*/

app_menu(activate_icons(["icon 1","icon 2","icon 3"]))
	/* 4.4.	 Activates icons previously created with command 4.3.	*/
	
app_menu(control_file_events)
	/* 4.5.  Takes control on the events of the daVinci File menu.	*/
	
	
5. Commands of category set(...): 
================================= 

set(layout_accuracy(4))
	/* 5.1.  Sets the quality of the graph layout algorithm.	*/
	
set(font_size(18))
	/* 5.2.	 Sets the font size used for text of graph nodes.	*/
	
set(gap_width(10))
	/* 5.3.	 Sets the minimal distance between nodes at a level.	*/
	
set(gap_height(10))
	/* 5.4.	 Sets the minimal distance between graph levels.	*/
	
set(multi_edge_gap(10))
	/* 5.5.	 Sets the distance used for drawing multi-edges.	*/
	
set(self_edge_radius(10))
	/* 5.6.	 Sets the radius used for drawing self-edges.		*/
	
set(animation_speed(80))
	/* 5.7.	 Sets the speed of scrolling animation which is used	*/
	/*	 when moving the focus in a graph visualization (e.g. 	*/
	/*	 navigation).						*/
	
set(no_cache(true))
	/* 5.8.	 Switches the pixmap cache on or off. This is useful	*/
	/*	 im case of problems with not enough memory.		*/


6. Commands of category window(...): 
====================================

window(title("my window title"))
	/* 6.1.	 Sets the title of the daVinci window.			*/
	
window(show_message("This is a message"))
	/* 6.2.	 Displays an temporary information message in the  	*/
	/*	 windows footer area.					*/

window(show_status("A Status"))
	/* 6.3.	 Displays an permanent status message in the windows  	*/
	/*	 footer area.						*/
	
window(position(300,400))
	/* 6.4.	 Sets the origin position of the daVinci window.	*/

window(size(400,400))
	/* 6.5.	 Sets the width and height of the daVinci window.	*/

window(raise)
	/* 6.6.	 Brings the daVinci window to the front.		*/

window(iconify)
	/* 6.7.	 Iconifies the daVinci window.				*/

window(deiconify)
	/* 6.8.	 Deiconifies the daVinci window.			*/

window(deactivate)
	/* 6.9.	 Blocks all user input.					*/

window(activate)
	/* 6.10. Enables user input again.				*/

window(file_browser(true,"my own file browser","Open","","",[bt("C Files","*.c","to open a C file"),bt("all Files","*","to open all files")],true))
	/* 6.11. Displays a customized file browser for private use.	*/


7. Commands of category tcl(...): 
=================================

tcl(eval("button .b -text Hello -command {daVinci tcl_answer Pressed} ; pack .b"))
	/* 7.1.  Sends a Tcl/Tk script to daVinci for execution.	*/
	
tcl(eval_file("<some Tcl/Tk script>"))
	/* 7.2.  Load a Tcl/Tk script from file for execution.		*/


8. Commands of category special(...): 
=====================================

special(select_nodes(["Alto","Smalltalk"]))
	/* 8.1.  Selects the given nodes in the graph previously loaded */
	/*	 before with command 3.4. 				*/
	
special(focus_node("Mac II"))
	/* 8.2.  Scrolls to the given node in the graph previously  	*/
	/*	 loaded before with command 3.4. 			*/

special(focus_node_animated("Memex"))
	/* 8.3.  Scrolls to the given node in the graph previously  	*/
	/*	 loaded before with command 3.4. by using animation.	*/

9. Commands for visualization definitions:
==========================================

To see the effects of the following commands, please send command 1.1 first.

visual(new_rules([nr("A",[a("COLOR","#ff0000")]),nr("B",[a("COLOR","#0000ff")]),er("A",[a("EDGECOLOR","#ff0000")]),er("C",[a("EDGECOLOR","#0000ff")])]))
	/* 9.1.  Set visualization rules to define the color of nodes	*/
	/*	 and edges.		 				*/

graph(change_type([node("1","B")]))
	/* 9.2.  Change the type of a node to let another rule match.	*/

visual(add_rules([nr("A",[a("COLOR","#00ff00"),a("_GO","triangle")])]))
	/* 9.3.  Change visualization rules for a node type to set	*/
	/*	 color and geometrical object.				*/

graph(change_attr([node("2",[a("COLOR","white")])]))
	/* 9.4.	Attributes specified for individual nodes precede rules.*/
	
set(rules_first(true))
	/* 9.5.	Or you have to define that rules precede individual	*/
	/*	attributes.						*/

visual(new_rules([nr("",[a("COLOR","#ff0000"),a("_GO","circle"),m([menu_entry("Knoten Typ A","Knoten vom Typ A"),blank,submenu_entry("","Submenu",[menu_entry_disabled("Submenu 1","Submenu 1"),menu_entry("Submenu 2","Submenu 2")]),submenu_entry_disabled("","Disabled Submenu",[])])]),er("A",[m([menu_entry("Kante Typ A","Kante vom Typ A")])]),er("",[a("EDGECOLOR","#ff0000"),a("HEAD","circle")])]))
	/* 9.6.	Overwrite the default attributes for nodes and edges.	*/
	/*	attributes. Press right mouse button over a node, to see*/
	/*	how node popup menus work.				*/

10. Commands for drag and drop:
===============================

To see the effects of the following commands, please send command 1.1 first.

drag_and_drop(dragging_on)
	/* 10.1. Switch drag and drop mode on.				*/

Now press the middle mouse button somewhere in the graph area but not over a
node!

drag_and_drop(new_node_at_coord(new_node("DD","C",[a("OBJECT","DD")])))
	/* 10.2. Insert a new node at the coordinate.			*/

Now press the middle mouse button over a node and drag the mouse to some place
in the graph-area but not over a node and release the button.

drag_and_drop(new_edge_and_node_at_coord(new_node("DD2","C",[a("OBJECT","DD2")]),new_edge("DD","B",[],"....","DD2")))
	/* 10.3. Replace "...." by the ID returned in the event you've	*/
	/*	 just got. This inserts a new edge and node.		*/