Programmer's Guide for API Users

The following is an overview of the API for programmers who want to connect their application with uDraw(Graph).

Commands of the API

After connecting your application program with uDraw(Graph) (section How to connect an Application explains this topic in detail), you can start sending commands to the API. The Overview of API Commands is a useful reference to browse through the command syntax. The commands are divided into categories with respect to their semantics. They are built hierarchically with parenthesis according to the category they belong to, e.g. command "menu(file(exit))" belongs to category "menu". The following categories are available:

• graph(...)
  

  The graph category covers commands to send and update graphs. You can send a complete graph in term representation format or update the structure of an already loaded graph by adding and deleting nodes and edges. Further, it is possible to change the attributes of existing nodes and edges (more information about attributes) and to change the type of nodes and edges (more information about types). Graph updates and attribute modifications can be combined to be performed in one step.

• multi(...)
  

  The multi category covers commands to work with many graphs in different windows at the same time. Please read the introduction to multi-graph/view/window modes for background information. In the multi category, commands are available to open a new context, i.e. to get a new empty base window where an additional graph can be visualized. Each context (graph) has its own unique context ID. In multi-graph mode, uDraw(Graph) maintains a current context state which can be set with command multi(set_context(...)). The current context specifies the graph that should be affected by all subsequent commands sent to the API. On the other side, in multi-graph mode each answer from the API has a preluding answer context(...) to specify the graph where the event happened. The multi-graph mode is entered as soon as the first context is opened. If you intend to use more than one graph later in a session, you should open the first context at initialization time.

  In multi-graph mode, you can only access each context (graph) on its own, but you have no access to the individual base windows opened in a context. Especially the commands of the window category may not work as expected, because they only apply to the master view of a context. Accessing all base windows is only possible by using the multi-window mode that is available after using command-line option -window_api by opening the first context. Here, the current context must be set with a different command multi(set_context(...)) where both the context and window ID are specified. The current context and window represent the graph and base window that will be affected by subsequent commands sent to the API. On the other side, in multi-window mode each answer from the API has a preluding answer context_window(...) to specify the graph and window where the event happened. Further, in multi-window mode the application is informed about creation and destruction of base windows by using the answers open_window and close_window(...).

• menu(...)
  

  The menu category covers commands to call the menu functions of the uDraw(Graph) user interface. All these commands are further divided into subcategories with respect to the menu they belong to: file, view, navigation, abstraction, layout and option.

• app_menu(...)
  

  The application menu category covers commands to let the application attach its own menus and icons to the uDraw(Graph) user interface. Please read the introduction about user interface extension for background information. Application menus are always attached to the Edit menu and application icons are placed on a separate plane of the icon bar. Using these commands is the traditional way to extend the user interface, but meanwhile it is also possible to configure the whole user interface with the commands of the gui category, see below. Application menus and icons that are not applicable in a current state should be disabled by the application. This can be done with activation commands where the list of currently enabled menus/icons is specified; all the remaining menus/icons are automatically disabled. To interpose the file operations, the application can take control on the uDraw(Graph) file menu events, for example to store its own data structure when the user selects the "File/Save" menu in uDraw(Graph).

  The commands of this category are not available if the command-line option -nogui has been used.

• gui(...)
  

  The graphical user interface category covers commands to let the application configure all menus, icons and footer areas of the uDraw(Graph) user interface. Please read the introduction about user interface configuration for background information. The configuration has to be done at initialization time before the first base window gets visible. Otherwise the base windows will only have the graph area and the scrollbars without access to the other user interface elements (menus, icons and footer). There are activation commands for all menus and icons where the list of currently enabled menus/icons is specified; all the remaining menus/icons are automatically disabled in this case. Further commands can be used to set the values of radio menus and icons.

  The commands of this category are only available if the command-line option -nogui has been used.

• set(...)
  

  The set category covers commands to set different options of uDraw(Graph) which are usually manipulated by the user with the dialog windows of the option menu. Commands are available to set the accuracy of the graph layout algorithm, to specify if the node levels should be preserved by the layout algorithm, to set the fine-tuning constraints, to specify the font size, edge style, and distances between nodes and edges in the graph visualization, to control the scrolling behavior, to define the speed of animation used for scrolling, to specify the name of the web browser and the location of the online documentation, to set the print command and measure unit used in the print dialog and to define the tooltip delay. One option that cannot be set in the user interface is the precedence used for visualization definitions, i.e. the attribute evaluation order. The precedence can only be set with an API command.

• window(...)
  

  The window category covers commands to manipulate the base windows. In multi-graph mode, only the master view is affected this way; use the multi-window mode if you want to manipulate any base window that is opened in a context. The window category contains commands to set the window title, to show messages and status information in the footer area, to set the window position and size, to raise the window (i.e. bring it to the front), and to iconify or deiconify the window. With the commands activate and deactivate, all user input can be blocked for a time. Finally, there is a command to use the uDraw(Graph) file browser for the application's own purpose and to set the background color.

• tcl(...)
  

  The tcl category covers commands to access a Tcl/Tk interpreter which is used to implement the user interface of uDraw(Graph). This way the application is able to evaluate scripts written for Tcl/Tk version 8.4, for example to implement dialog windows which should appear when application menus or icons are selected. Please read the introduction to the Tcl/Tk interface for background information.

• special(...)
  

  The special category covers commands to set the current node or edge selection, to scroll to a particular node with and without animation, to display a HTML page (URL) in the browser and to add a file with additional text translations for internationalization.

• visual(...)
  

  The visual category covers commands to create new rules or add rules used for visualization definitions.

• drag_and_drop(...)
  

  The drag and drop category covers commands to control direct manipulation in a graph visualization. Commands are available to activate and deactivate the drag and drop mode and to create a node or a node and edge at the position where the mouse button was released. Please read the introduction to the drag and drop mode for background information.

Answers from the API

All commands sent to the API are confirmed after execution by returning an answer which is usually ok or communication_error(...) when the command failed. Some commands (listed here) return another confirmation answer instead of ok. It is very important to wait for confirmation before sending the next command, because in rare situations, the API accepts new commands even if the previous command is still in process and not yet confirmed, so the confirmation answers may not appear in the right order afterwards. The rest of the answers (listed here) are events that are triggered by the user, e.g. to inform the application about selection of a graph node. Events can occur at any time, except when an API command is currently executed and not yet confirmed.

Very important note about Asynchronization

Due to the strange effects of asynchronous communication caused by message delays, an event must also be expected by the application after sending a command to the API and before receiving the corresponding confirmation answer! uDraw(Graph) guarantees that event answers are not propagated during execution of an API command, but if the event occurred during transfer time of the command (i.e. after it is sent by the application and before it is received by the API), then the event answer may interfere and will arrive at the application side in the time interval after sending the command and before receiving the corresponding confirmation answer. So never expect that the confirmation answer will come back directly after sending an API command. Your application must accept event answers at any time!

Important Notes about the API

Please consider the following facts when using the uDraw(Graph) API:

• No return characters inside API commands
  

  API commands must not contain newline (ASCII 10) or return characters (ASCII 13). They must have exactly one newline at the end of the command ("end-of-line") to flush the write buffer. No other characters, even no spaces, should follow after this concluding return, except of the next complete command. When these restrictions are not considered, communication with the API will likely fail. For example, in "C" you can send a command to the API this way, whereby "dv_fd" is a file descriptor of a pipe or socket to send API commands to uDraw(Graph):

  fprintf(dv_fd,"window(show_message(\"Hi\"))\n");

  Note that there is a newline at the end of the "C" string and that there is another API string inside the "C" string. Quotes inside "C" strings have to be escaped with a backslash character "\". The same is true for quotes inside API strings, refer to the next list item.

• No unescaped double quotes inside API commands
  

  Some API commands have a string parameter which is always enclosed by double quotes, for example:

  window(show_message("This is a string"))

  If you have to use double quotes inside a string, make sure that they are always escaped with a backslash character "\". Example:

  window(show_message("Here is a quote \" inside."))

  But do not escape the outermost double quotes of the string!

• Use only balanced braces "{" and "}" in API commands
  

  Because Tcl/Tk is used for the implementation of the uDraw(Graph) user interface, some characters have a special meaning. Braces ("{" and "}") are used as delimiters for sending strings to Tcl/Tk. As a restriction, you cannot use unbalanced braces somewhere inside of an API string, even if they are escaped with "\". Using strings like "}" or "{" inside of an API command will result in Tcl/Tk error messages on command-line, whereas a balanced "{}" is allowed. So you have to avoid sending strings with unbalanced braces.

• Initial ok answer
  

  After connecting an application to the uDraw(Graph) API, the application program has to wait for the initial ok answer before sending any commands to the API.

• Disconnection
  

  An application will receive the answer disconnect if the user selects menu File/Disconnect. The appropriate action for this event is to terminate the application in order to let the user connect another application in uDraw(Graph).

• Multi-graph mode
  

  In multi-graph mode, each answer has a preluding context(...) answer to specify the context (graph) where the event happened. So, your application has to receive two answers at a time after entering multi-graph mode.

• Multi-window mode
  

  In multi-window mode, each answer has a preluding context_window(...) answer to specify the context (graph) and base window where the event happened. So, your application has to receive two answers at a time after entering multi-window mode. Further, the application is informed about creation (answer open_window) and destruction (answer close_window(...)) of all base windows.

• Close and exit when file events are controlled
  

  When the application controls the "File" menu events, it will receive the following answer each time the user wants to close a particular context (graph) by using menu File/Close:

  menu_selection("#%close")

  The appropriate action in this case is to set the current context (and window in multi-window mode) to the ID where the event happened and to close this context by sending command "menu(file(close))". In the same way, the application will receive the following answer when the user wants to exit uDraw(Graph) by using menu File/Exit:

  menu_selection("#%exit")

  The appropriate action in this case is to send "menu(file(exit))" in any context to terminate uDraw(Graph).