Interface Handler Functions

Detailed Description

This group contains Intermediate API functions used to implement complex state-based user interaction. These functions have very specific use and are placed in a separate category.

The Interface Handler functions are used in the editor-style applications that need to implement complex user interaction that uses persistent state variables to manage nested menus and dialogs. The GLG Graphics Builder and GLG HMI Configurator use the Interface Handler Functions to implement their user interfaces.

Installable Interface Handlers (referred to as interface handlers in the rest of this section) provide a mechanism for handling user interaction where persistency is necessary to handle interrelated sequences of user actions. Interface handlers are hierarchical, allowing an application to handle nested operations, such as nested dialogs or chained operations. Internally, a stack is used to maintain a hierarchy of handlers, making it possible to handle arbitrary nested sequences, for example display a confirmation dialog based on the action of the parent dialog (such as parent dialog closing).

The use of the stack allows to easily pass control to the previous handler in the stack after the currently active handler is uninstalled and deleted from the stack. The handlers also automate the flow of control: if the currently active handler at the bottom of the stack is not interested in the event, it can uninstall itself from the stack and pass the event to the previous handler on the stack, which, in turn, can pass the event further to the next handler in the stack.

For example, a top-level handler can be used to handle events from toolbar icons and main pull- down menu, and a nested second-level handler can be installed to handle a popup dialog. A third-level handler can be used to confirm closing of the dialog managed by the second handler. When the dialog closing is confirmed, the third and then the second handlers are uninstalled (get removed from the stack), and the control returns to the main top-level handler.

Each handler maintains its own persistent data storage for intermediate data, which is automatically cleaned up when the handler is uninstalled. A variable number of dynamic parameters can be supplied to each handler to modify its behavior as needed. Parameters can be either optional or mandatory. Optional parameters allow the developer to extend a handler's functionality while maintaining backward compatibility.

User interaction events passed to an interface handler are encoded as integer tokens for efficiency and are passed to the currently active handler (the bottom handler currently stored on a stack).

The source code for each handler is provided by an application; the code handles a set of user interaction events identified by the tokens. A handler is typically designed to handle a particular set of tokens, for example tokens for an Apply or Cancel button for a specific dialog. If an unrecognized token is encountered, the handler can either ignore the event to implement a modal dialog, or it can uninstall itself and pass the event to the parent handler, which, in turn, can pass it to its parent, and so on.

Interface handlers extend functionality of event handling callbacks and listeners (referred collectively as callbacks in the rest of this section). A disadvantage of a callback is that it does not provide data persistency: when a callback is invoked to handle a particular event, any changes to an application state have to be kept in an external global structure shared by all callbacks. A callback exits after processing each event and does not provide any means for storing intermediate interaction state in the callback itself. For example, if a dialog has several buttons, individual callbacks are invoked on each button press event, making it difficult to implement a single integrated event handler for the dialog as a whole.

Interface handlers address this problem by supporting persistency, providing data storage for intermediate data that control user interaction. An interface handler stays active to process all events for a dialog or a page, until the handler is uninstalled when dialog closes or a page is switched to display another page. The interface handlers provide a flexible alternative to the Hierarchical State Machines (HMS) that are often used to handle the state of the user interface transitions. Unlike HMS, interface handlers allow a developer to extend the handler functionality by adding handler parameters and augment the handler source code based on the parameter values passed to it, which could be easier than adding new states to the state machine.

The /DEMOS/diagram/diagramG.c file in the GLG installation directory provides examples of implementing several design patterns for handling various types of user interaction. Many other alternative options of using the interface handlers are possible, and an application can implement any desirable design pattern depending on the application requirements.

Modules
	Data Types and Macros
	Installing and Uninstalling
	Invoking and Event Handling
	Parameter Access
	Utilities