Information about API Answers
Information about API Answers
Answer at initialization time
uDraw(Graph) can be connected to an application program
using several options, refer to page
How to connect an Application
for details.
After connecting uDraw(Graph) to the application, an initial answer
ok
is sent to the application to signal preparedness for receiving
commands.
An application must not start sending commands to uDraw(Graph) before
receiving the initial "ok" as the first answer from the API.
Answers to confirm API commands
In general,
commands
sent to the API are confirmed by sending the answer
ok
back to the application after successfully executing the command.
All commands that do not return "ok" are listed below.
If an error occurred while executing the command, uDraw(Graph) will
send the answer
communication_error
instead of "ok".
Usually, this exception should not happen when the application
meets all rules and restrictions of the API.
The application can find the reason for the error in the string
parameter of answer "communication_error(...)".
These are the API commands that do not return the "ok" answer:
In
multi-window mode,
the following commands answer
open_window
instead of
ok:
Answers to notify events
Beside the
answers used to confirm a command
sent to the API, some answers may occur at any time.
These are notifications for events that are triggered by the user.
A uDraw(Graph) application must be prepared to receive these
answers at any time, even in the time interval between sending
a command and receiving the corresponding confirmation answer.
The API sends the following events:
VERY IMPORTANT:
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 occurs during transfer
time of the command (i.e. after it has been sent by the application and
before it has been 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!
Answers in Multi-Graph Mode
When uDraw(Graph) has left the default single-graph mode to enter
the
multi-graph mode,
the behavior for confirming commands and sending event
notifications will slightly change.
In multi-graph mode, all answers from uDraw(Graph) will always
have a preluding answer
context(...)
to specify the context (graph) where the following answer happened.
So in multi-graph mode, an application will
always get two answers
instead of one:
The first one is the context and the second one is the event
or confirmation answer.
Answers in Multi-Window Mode
In the
multi-view
mode where the user (or the application) has opened additional
views (base windows) to the graph, the application is unable to
access each individual view.
To solve this restriction, you can use the
multi-window mode
by using command-line option
-window_api.
Here, the behavior of
sending two answers
with each confirmation or event is the same, but instead
the preluding answer
context_window(...)
is used where the application can find an additional window ID.
Further, the commands
menu(view(open_new_view))
and
menu(view(open_survey_view))
return the confirmation answer
open_window
instead of the usual
ok
that is sent by these commands when the multi-window mode is not active.
|