University of Bremen

Manual

Main->API->Programmer's Guide

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:

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!

Your application is responsible for handling an event answer. The event may trigger an operation in the application or can simply be ignored.

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).