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!
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:
The appropriate action in this case is to send
"menu(file(exit))" in any context to terminate uDraw(Graph).
|