User Interface Extension

Extending the user interface is the traditional way to add application specific menus and icons at a predefined places in the uDraw(Graph) user interface. It is even possible to configure the whole user interface of uDraw(Graph), so it is a good idea to look at this more flexible mechanism first.

Why attaching Menus and Icons to the uDraw(Graph) User Interface?

By extending uDraw(Graph) with application specific menus and icons, an application program connected to the API can offer the user a way to start operations (processed by the application itself) by interacting with a uDraw(Graph) graph visualization. So the user has the same kind of menu access to both the standard visualization operations offered by uDraw(Graph) and to operations that modify the graph structure and have to be executed by the application program.

For example, an application might add a menu named "Delete Node". If the user selects this menu in the uDraw(Graph) user interface, the application is informed about this event by receiving the answer menu_selection(...) from the API. With respect to the current node selection (which has been propagated by the API before with answer node_selections_labels(...)), the application is able to remove the selected node(s) in its own data structure. Afterwards, the application has to send one of the commands of the graph category back to the API to inform uDraw(Graph) about its modifications to the graph in order to update the visualization. Even with this trivial example, uDraw(Graph) has been extended by the functions of a simple graph editor without the need to provide the necessary code inside the visualization system. This way, uDraw(Graph) is as flexible and generic as possible to be extended by any kind of function, depending on the behavior of an application that is connected to the API.

Adding Application Menus and Icons

An application is able to attach menus in the uDraw(Graph) user interface at any time by sending command app_menu(create_menus(...)). It is even possible to add more menus later in a session, although this is not a recommended practice with respect to human computer interaction guidelines. uDraw(Graph) will always attach these application menus in the Edit menu hierarchy, because these operations should usually have to do with modification of the structure of a loaded graph. Each time the user selects an entry of a menu that is provided by the application, answer menu_selection(...) is sent back by the API to inform about this event. Afterwards, the application can perform any appropriated task to handle the event, e.g. by manipulating its own data and sending commands to the API.

Application icons, added by using the API command app_menu(create_icons(...)) are always attached on a separate plane of the icon bar. The other (default) plane of the icon bar, visible at start-up time, is reserved for the built-in icons which are shortcuts to frequently used menu operations. The user can switch between both icon planes by clicking on the arrow at the lower side of the icon bar. As soon as the API receives the first icons, the application plane and the arrow become visible automatically. Each time the user selects an icon that is provided by the application, answer icon_selection(...) is sent back by the API to inform about this event. Afterwards, the application can perform any appropriated task to handle the event, e.g. by manipulating the own data and sending commands to the API.

In multi-graph mode, each context (i.e. graph) has its own menus and icons. To guarantee that the user interface is consistent, application menus and icons cannot be removed later. If particular menu entries or icons are not applicable in a current situation (e.g. with respect to the current node or edge selection in uDraw(Graph)), the application should deactivate them by using the commands app_menu(activate_menus(...)). and app_menu(activate_icons(...)). Both activation commands enable the menus (or icons) specified in the command's parameter and automatically disable all remaining application menus (or icons).

A closer Integration by Interposing the File Menu Events

The application is unable to attach its menus in uDraw(Graph) at other places than the "Edit" menu, with the exception of user interface configuration at initialization time. This might be inappropriate for I/O operations, for example if the applications would like to have a menu to save its own data structure. With respect to most user interface style guides, such an operation should usually be available in the "File" menu. After connecting an application to the API, uDraw(Graph) will disable most of the entries in the File menu to avoid a situation where the user can load a different graph without permission by the application.

If desired, the application can use command app_menu(control_file_events) to take control of all entries of the "File" menu, except for File/Connect Application and File/Disconnect Application. After doing so, the application will receive events with the menu_selection(...) answer as soon as any entry of the "File" menu is selected by the user. After losing control of the "File" menu, uDraw(Graph) will not perform any operation if these menu entries are selected by the user. Instead, the application has to decide on its own what to do. To simulate the built-in behavior on these events, read the recommended actions below. The entries of the "File" menu have special predefined menu IDs (with prefix "#%") which are used in the string parameter of the menu_selection(...) answer in case of selection. These reserved menu IDs cannot be used as identifier for application menus.

Reserved Menu IDs:
#%new	-> user has selected menu File/New
#%open	-> user has selected menu File/Open...
#%save	-> user has selected menu File/Save
#%saveas	-> user has selected menu File/Save As...
#%print	-> user has selected menu File/Print...
#%export	-> user has selected menu File/Export...
#%close	-> user has selected menu File/Close
#%exit	-> user has selected menu File/Exit

These menu IDs can be used with command app_menu(activate_menus(...)) to enable or disable the corresponding entries in the "File" menu. Of course, "File" menu events not applicable in the current situation can simply be ignored by the application, but it is better to deactivate these menu entries for ergonomic reasons.

Note: each time the command app_menu(activate_menus(...)) is sent to the API, all the other menus not listed in the command's parameter list will be automatically deactivated, even in the "File" menu (but of course only if the application has taken control of the "File" menu). So an application programmer must always consider the entries of the "File" menu with each menu activation, because otherwise the user might not be able to exit uDraw(Graph) when menu "File/Exit" has automatically been disabled this way.

Very important: After taking control of the "File" menu events, the application is responsible for closing a context and quitting uDraw(Graph) when the user selects the corresponding operation, i.e. menu File/Close (or the equivalent generic window function of the operating system respective window manager) and File/Exit. In this case, the answer menu_selection("#%close") respective menu_selection("#%exit") is sent to the application which should usually be handled by performing the recommended actions that are listed directly below. The user will not be able to close windows or exit uDraw(Graph) if the application ignores these events.

Recommended Actions on File Events

If the application controls the "File" menu (read above) and the user selects an entry of this menu, then uDraw(Graph) does not perform any operation. Instead, the event is forwarded to the application by using the API answer menu_selection(...). At this time, the application has to decide what to do. For example, if menu File/New is selected, the application will receive the answer menu_selection("#%new"). An appropriate behavior to handle this event might be to clear the application's internal graph data structure and send an empty graph back to uDraw(Graph).

If the application would like to simulate the built-in behavior that is usually executed in case of file events, it can do so by sending the following API commands back to the API:

• Menu event "File/New"
  The application receives the answer menu_selection("#%new"). Clear the graph in uDraw(Graph) by sending command menu(file(new)).
• Menu event "File/Open..."
  The application receives the answer menu_selection("#%open"). Use a file browser in "open" mode with command window(file_browser(...)) and wait for answer browser_answer(...). Load the selected file by using command menu(file(open_graph(...))) or menu(file(open_status(...))) with the filename returned with the browser answer.
• Menu event "File/Save"
  The application receives the answer menu_selection("#%save"). Save the status of the graph that is currently loaded in uDraw(Graph) with command menu(file(save_status(...))).
• Menu event "File/Save As..."
  The application receives the answer menu_selection("#%saveas"). Use a file browser in "save" mode with command window(file_browser(...)) and wait for answer browser_answer(...). Save the loaded graph in term representation or status format (depending on the selected type in the browser answer) by using command menu(file(save_graph(...))) or menu(file(save_status(...))) with the filename returned by the browser answer.
• Menu event "File/Print..."
  The application receives the answer menu_selection("#%print"). Open the print dialog window with command menu(file(print)).
• Menu event "File/Export..."
  The application receives the answer menu_selection("#%export"). Open the export dialog window with command menu(file(export)).
• Menu event "File/Close"
  The application receives the answer menu_selection("#%close"). Close the current context (i.e. graph) by sending command menu(file(close)). This menu should only be available in multi-graph mode. Never close a context in single-graph mode!
• Menu event "File/Exit"
  The application receives the answer menu_selection("#%exit"). Terminate uDraw(Graph) with command menu(file(exit)). Maybe you should exit your application program, too.

Note: in multi-graph mode, you also have to consider the context of the menu event sent to the application in a preluding context(...) answer. The current context must be set using command multi(set_context(...)) to the context ID returned by the event answer before sending the next command. Otherwise, the reaction of your application may affect other graphs than the one where the event actually happened.