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.

Macros
#define	GLG_IH_CURR
	Specifies the ID of the current handler. More...
#define	GLG_IH_GLOBAL
	The ID of the global data storage. More...
#define	GLG_IH_NEW
	Specifies the ID of the just installed handler. More...

Typedefs
typedef GlgObject	GlgIH
	Opaque type that represents an installable interface handler. More...
typedef void *	GlgIHCallEvent
	Opaque type that represents installable interface handler events. More...
typedef void(*	GlgIHEntryPoint) (GlgIH ih, GlgIHCallEvent call_event)
	An entry point that is invoked to handle user interaction logic of an installable interface handler. More...
typedef GlgLong	GlgIHToken
	An installable interface handler token that identifies the event that needs to be handled. More...

Functions
GlgBoolean	GlgIHCallCurrIH (GlgIHCallEvent call_event)
	Passes an event to the current handler. More...
GlgBoolean	GlgIHCallCurrIHWithModifToken (GlgIHCallEvent call_event, GlgIHToken token)
	A variation on GlgIHCallCurrIHWithToken that reuses an existing user interface event. More...
GlgBoolean	GlgIHCallCurrIHWithToken (GlgIHToken token)
	Passes a token to the current handler. More...
void	GlgIHCallPrevIHWithModifToken (GlgIHCallEvent call_event, GlgIHToken token)
	A variation on GlgIHCallPrevIHWithToken that reuses an existing user interface event. More...
void	GlgIHCallPrevIHWithToken (GlgIHToken token)
	Passes the token to the parent handler of the currently active handler. More...
void	GlgIHChangeDParameter (GlgIH ih, char *name, double value)
	Changes a double value stored in a named parameter. More...
void	GlgIHChangeIParameter (GlgIH ih, char *name, GlgLong value)
	Changes an integer value stored in a named parameter. More...
void	GlgIHChangeOParameter (GlgIH ih, char *name, GlgObject value)
	Changes a GLG object ID stored in a named parameter. More...
void	GlgIHChangePParameter (GlgIH ih, char *name, void *value)
	Changes a pointer stored in a named parameter. More...
void	GlgIHChangeSParameter (GlgIH ih, char *name, char *value)
	Changes a string value stored in a named parameter. More...
GlgIH	GlgIHGetCurrIH (void)
	Retrieves ID of the current active interface handler. More...
double	GlgIHGetDParameter (GlgIH ih, char *name)
	Returns a double value stored in a named parameter. More...
GlgIHEntryPoint	GlgIHGetFunction (GlgIH ih)
	Returns function that implements the handler's logic. More...
GlgLong	GlgIHGetIParameter (GlgIH ih, char *name)
	Returns an integer value stored in a named parameter. More...
GlgObject	GlgIHGetOParameter (GlgIH ih, char *name)
	Returns a GLG object ID stored in a named parameter. More...
double	GlgIHGetOptDParameter (GlgIH ih, char *name, double default_value)
	Returns a double value stored in an optional named parameter. More...
GlgLong	GlgIHGetOptIParameter (GlgIH ih, char *name, GlgLong default_value)
	Returns an integer value stored in an optional named parameter. More...
GlgObject	GlgIHGetOptOParameter (GlgIH ih, char *name, GlgObject default_value)
	Returns a GLG object ID stored in an optional named parameter. More...
void *	GlgIHGetOptPParameter (GlgIH ih, char *name, void *default_value)
	Returns a pointer stored in an optional named parameter. More...
char *	GlgIHGetOptSParameter (GlgIH ih, char *name, char *default_value)
	Returns a string value stored in an optional named parameter. More...
void *	GlgIHGetPParameter (GlgIH ih, char *name)
	Returns a pointer stored in a named parameter. More...
GlgIHEntryPoint	GlgIHGetPrevFunction (void)
	Returns function used to implement the parent handler of the currently active handler. More...
GlgIH	GlgIHGetPrevIH (void)
	Retrieves ID of the currently active interface handler's parent handler. More...
char *	GlgIHGetSParameter (GlgIH ih, char *name)
	Returns a pointer stored in a named parameter. More...
GlgIHToken	GlgIHGetToken (GlgIHCallEvent call_event)
	Returns a token associated with the GLG_MESSAGE_EVENT event. More...
GlgCallEventType	GlgIHGetType (GlgIHCallEvent call_event)
	Returns an event's type. More...
void	GlgIHInit (void)
	Initializes installable handler utilities, must be invoked after GlgInit but before any installable handler functions are used. More...
GlgIH	GlgIHInstall (GlgIHEntryPoint handler)
	Creates a handler with the specified entry point and installs it. More...
void	GlgIHPassToken (GlgIHEntryPoint handler, GlgIHToken token, GlgBoolean uninstall)
	Installs a handler, starts it and invokes its entry point with the specified token. More...
void	GlgIHResetup (GlgIH ih)
	Reinitializes the current handler that have already been installed and used to "restart" its logic. More...
void	GlgIHSetDParameter (GlgIH ih, char *name, double value)
	Creates and stores a named double parameter. More...
void	GlgIHSetIParameter (GlgIH ih, char *name, GlgLong value)
	Creates and stores a named integer parameter. More...
void	GlgIHSetOParameter (GlgIH ih, char *name, GlgObject value)
	Creates and stores a named parameter that keeps a GLG object ID. More...
void	GlgIHSetOParameterFromD (GlgIH ih, char *name, double value)
	Creates and stores a named double parameter that is stored as a GLG Data object of the GLG_D type. More...
void	GlgIHSetOParameterFromG (GlgIH ih, char *name, double value1, double value2, double value3)
	Creates and stores a named parameter that keeps X, Y and Z or R, G and B values stored as a GLG Data object of the GLG_G type. More...
void	GlgIHSetPParameter (GlgIH ih, char *name, void *value)
	Creates and stores a named pointer parameter. More...
void	GlgIHSetSParameter (GlgIH ih, char *name, char *value)
	Creates and stores a named string parameter. More...
void	GlgIHStart (void)
	Initializes and starts the current handler after it has been installed with GlgIHInstall. More...
void	GlgIHTerminate (void)
	Terminates installable handler utilities. More...
void	GlgIHUninstall (void)
	Uninstalls the current handler (the last handler on the handler stack). More...
void	GlgIHUninstallWithEvent (GlgIHCallEvent call_event)
	Uninstalls the current handler and passes an event to the previous handler. More...
void	GlgIHUninstallWithToken (GlgIHToken token)
	Uninstalls the current handler and passes a token to the previous handler. More...

Macro Definition Documentation

GLG_IH_CURR

#define GLG_IH_CURR

Specifies the ID of the current handler.

It may be used when no handler ID supplied by the handler's ih parameter is available.

GLG_IH_GLOBAL

#define GLG_IH_GLOBAL

The ID of the global data storage.

This ID can be used to access global data instead of the data of a specific interface handler.

GLG_IH_NEW

#define GLG_IH_NEW

Specifies the ID of the just installed handler.

It can be used to specify the handler after it was created using GlgIHInstall and before it is started with GlgIHStart.

Typedef Documentation

GlgIH

typedef GlgObject GlgIH

Opaque type that represents an installable interface handler.

GlgIHCallEvent

typedef void* GlgIHCallEvent

Opaque type that represents installable interface handler events.

See GlgIHGetType and GlgIHGetToken for more information.

GlgIHEntryPoint

typedef void(* GlgIHEntryPoint) (GlgIH ih, GlgIHCallEvent call_event)

An entry point that is invoked to handle user interaction logic of an installable interface handler.

Parameters

ih	The ID of the handler the entry point function belongs to. This ID can be used to access parameters stored in the handler's data storage.
call_event	The user interface event to be handled.

The code of this function implements functionality of the handler. See GlgIHStart for an example of a handler code.

GlgIHToken

typedef GlgLong GlgIHToken

An installable interface handler token that identifies the event that needs to be handled.

See GlgIHGetToken for more information.

Function Documentation

GlgIHCallCurrIH()

GlgBoolean GlgIHCallCurrIH

(

GlgIHCallEvent

call_event

)

Passes an event to the current handler.

Parameters

call_event

The user interface event to be passed.

Returns

True if the handler was uninstalled as a result of processing the event, False otherwise.

This function invokes the current handler's entry point with the specified user interface event.

GlgIHCallCurrIHWithModifToken()

GlgBoolean GlgIHCallCurrIHWithModifToken	(	GlgIHCallEvent	call_event,
		GlgIHToken	token
	)

A variation on GlgIHCallCurrIHWithToken that reuses an existing user interface event.

Parameters

call_event	The user interface event of the current handler that will be reused to pass the token.
token	The token to be passed.

Returns

True if the handler was uninstalled as a result of processing the token, False otherwise.

This function is the same as GlgIHCallCurrIHWithToken, except that it reuses the existing event by setting its token instead of creating a new call event to pass the token to the handler.

GlgIHCallCurrIHWithToken()

GlgBoolean GlgIHCallCurrIHWithToken

(

GlgIHToken

token

)

Passes a token to the current handler.

Parameters

token

The token to be passed.

Returns

True if the handler was uninstalled as a result of processing the token, False otherwise.

This function creates a call event object, uses it to pass the token to the entry point of the current handler and destroys the event object when done.

GlgIHCallPrevIHWithModifToken()

void GlgIHCallPrevIHWithModifToken	(	GlgIHCallEvent	call_event,
		GlgIHToken	token
	)

A variation on GlgIHCallPrevIHWithToken that reuses an existing user interface event.

Parameters

call_event	The user interface event of the current handler that will be reused to pass the token.
token	The token to be passed.

This function is the same as GlgIHCallPrevIHWithToken, except that it reuses the existing event by setting its token instead of creating a new call event to pass the token to the handler.

Note: When the parent handler is invoked, the current handler is not the parent handler but the handler that invoked it. Therefore, the parent handler cannot uninstall itself by simply calling GlgIHUninstall.

GlgIHCallPrevIHWithToken()

void GlgIHCallPrevIHWithToken

(

GlgIHToken

token

)

Passes the token to the parent handler of the currently active handler.

Parameters

token

The token to be passed.

The parent handler is the handler preceding the current handler on the stack of installed handlers.

Note: When the parent handler is invoked, the current handler is not the parent handler but the handler that invoked it. Therefore, the parent handler cannot uninstall itself by simply calling GlgIHUninstall.

GlgIHChangeDParameter()

void GlgIHChangeDParameter	(	GlgIH	ih,
		char *	name,
		double	value
	)

Changes a double value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetDParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeIParameter()

void GlgIHChangeIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	value
	)

Changes an integer value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetIParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeOParameter()

void GlgIHChangeOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	value
	)

Changes a GLG object ID stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetOParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangePParameter()

void GlgIHChangePParameter	(	GlgIH	ih,
		char *	name,
		void *	value
	)

Changes a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetIParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeSParameter()

void GlgIHChangeSParameter	(	GlgIH	ih,
		char *	name,
		char *	value
	)

Changes a string value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetSParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHGetCurrIH()

GlgIH GlgIHGetCurrIH

(

void

)

Retrieves ID of the current active interface handler.

The current active handler can also be accessed by using GLG_IH_CURR macro.

Returns

The current handler's ID.

GlgIHGetDParameter()

double GlgIHGetDParameter	(	GlgIH	ih,
		char *	name
	)

Returns a double value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHGetFunction()

GlgIHEntryPoint GlgIHGetFunction

(

GlgIH

ih

)

Returns function that implements the handler's logic.

Parameters

ih	Handler ID.

Returns

The handler's function.

The GLG_IH_CURR macro can be used as the ih parameter to access the current handler. The following example demonstrates the use of GlgIHGetFunction to identify the currently active handler.

extern GlgIHEntryPoint MyIH;
if( GlgIHGetFunction( GLG_IH_CURR ) == MyIH )
  ...

GlgIHGetIParameter()

GlgLong GlgIHGetIParameter	(	GlgIH	ih,
		char *	name
	)

Returns an integer value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHGetOParameter()

GlgObject GlgIHGetOParameter	(	GlgIH	ih,
		char *	name
	)

Returns a GLG object ID stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist.

GlgIHGetOptDParameter()

double GlgIHGetOptDParameter	(	GlgIH	ih,
		char *	name,
		double	default_value
	)

Returns a double value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetDParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptIParameter()

GlgLong GlgIHGetOptIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	default_value
	)

Returns an integer value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetIParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptOParameter()

GlgObject GlgIHGetOptOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	default_value
	)

Returns a GLG object ID stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetOParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptPParameter()

void* GlgIHGetOptPParameter	(	GlgIH	ih,
		char *	name,
		void *	default_value
	)

Returns a pointer stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetPParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptSParameter()

char* GlgIHGetOptSParameter	(	GlgIH	ih,
		char *	name,
		char *	default_value
	)

Returns a string value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetSParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetPParameter()

void* GlgIHGetPParameter	(	GlgIH	ih,
		char *	name
	)

Returns a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist.

GlgIHGetPrevFunction()

GlgIHEntryPoint GlgIHGetPrevFunction

(

void

)

Returns function used to implement the parent handler of the currently active handler.

Returns

The parent handler's function.

The parent handler is the handler preceding the current handler on the handler stack.

GlgIHGetPrevIH()

GlgIH GlgIHGetPrevIH

(

void

)

Retrieves ID of the currently active interface handler's parent handler.

The parent handler is the handler preceding the current active handler on the stack of installed handlers.

Returns

The parent handler's ID.

GlgIHGetSParameter()

char* GlgIHGetSParameter	(	GlgIH	ih,
		char *	name
	)

Returns a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHGetToken()

GlgIHToken GlgIHGetToken

(

GlgIHCallEvent

call_event

)

Returns a token associated with the GLG_MESSAGE_EVENT event.

Parameters

call_event

The user interface event the handler was invoked with.

Returns

The event's token.

Tokens are application-defined integer values used to uniquely identify each user interaction event. For example, IH_OK token can be associated with pressing a dialog's OK button, and IH_MOUSE_MOVED can be used to identify a mouse move event that provides coordinates of the cursor. Integer values are used to allow efficient event processing using switch statements. An enum is usually used to define tokens, for example:

enum MyTokens
{
  IH_UNDEFINED_TOKEN = 0,
  IH_OK,
  IH_CANCEL
}

In a GLG application, Input and Trace callbacks are used to convert interface events to tokens, as shown in the /DEMOS/diagram/diagramG.c file in the GLG installation directory. The tokens are then passed to the currently active handler via the GlgIHCallCurrIHWithToken function call.

GlgIHGetType()

GlgCallEventType GlgIHGetType

(

GlgIHCallEvent

call_event

)

Returns an event's type.

Parameters

call_event

The user interface event a handler was invoked with.

Returns

The event's type:

• GLG_HI_SETUP_EVENT is received when the handler is started using GlgIHStart; is used to perform any required initialization.
• GLG_HI_RESETUP_EVENT is received when the handler is reinitialized via GlgIHResetup.
• GLG_CLEANUP_EVENT is received before destroying the handler when it is uninstalled; is used to perform any required cleanup.
• GLG_MESSAGE_EVENT is a message event that is further identified by the associated token.

GlgIHInit()

void GlgIHInit

(

void

)

Initializes installable handler utilities, must be invoked after GlgInit but before any installable handler functions are used.

GlgIHInstall()

GlgIH GlgIHInstall

(

GlgIHEntryPoint

handler

)

Creates a handler with the specified entry point and installs it.

Parameters

handler

An application-provided function that implements the handler's interaction logic.

Returns

ID of the installed handler.

This function creates the handler, adds it to a stack of handlers and returns handler's ID. A stack of handlers is used to keep track of nested handlers; the last handler pushed onto the stack becomes the active handler, referred to as the current handler in the rest of this section.

After the handler has been installed, parameters can be passed to it by using its data storage. See GlgIHStart for an example of a handler code.

GlgIHPassToken()

void GlgIHPassToken	(	GlgIHEntryPoint	handler,
		GlgIHToken	token,
		GlgBoolean	uninstall
	)

Installs a handler, starts it and invokes its entry point with the specified token.

Parameters

handler	An application-provided function that implements functionality of the handler.
token	The token that will be passed to the handler.
uninstall	If True, the handler will be uninstalled after processing the token, unless the handler has already uninstalled itself. If the handler installs other handlers while processing the token, the last installed handler (the current handler) will be uninstalled instead of the new handler the token is passed to. If False, the handler will not be uninstalled and will remain a currently active handler. This function is used to implement pass-through handlers for processing global accelerators, stateless options, as well as managing floating stay-open dialogs, such as the Edit Properties dialog shown on the GLG Diagram demo.

GlgIHResetup()

void GlgIHResetup

(

GlgIH

ih

)

Reinitializes the current handler that have already been installed and used to "restart" its logic.

Parameters

ih	Handler ID.

This function invokes the handler's entry point with the GLG_HI_RESETUP_EVENT event. This can be used to reinitialize the handler by sharing some of the code of the GLG_HI_SETUP_EVENT case. The following handler example reuses handler initialization code that pops up a dialog when the handler starts up or restarts:

void ConfirmIH( GlgIH ih, GlgIHCallEvent call_event )
{
   char * message;
 
   // Retrieve the OK dialog object provided as a parameter when the handler was installed.
   GlgObject ok_dialog = GlgIHGetOParameter( ih, "ok_dialog" );
 
   GlgCallEventType event_type = GlgIHGetType( call_event );
   switch( event_type )
   {
     case GLG_HI_SETUP_EVENT:
       // Retrieve the dialog message provided as a parameter when the handler was installed.
       message = GlgIHGetOptSParameter( ih, "message" );
 
       // Set the dialog's message to the requested message.
       GlgSetSResource( ok_dialog, "DialogMessageString", message );
       // Fall through to popup the dialog.
 
     case GLG_HI_RESETUP_EVENT: // Popup the dialog again.
       GlgSetDResource( ok_dialog, "Visibility", 1. );
       GlgUpdate( ok_dialog );
       break;
 
     ...
   }
}

Refer to the /DEMOS/diagram/diagramG.c file in the GLG installation directory for a source code example of using this function.

GlgIHSetDParameter()

void GlgIHSetDParameter	(	GlgIH	ih,
		char *	name,
		double	value
	)

Creates and stores a named double parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetDParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetIParameter()

void GlgIHSetIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	value
	)

Creates and stores a named integer parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetIParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

Using IH Parameters

A parameter is added to the data storage of the handler specified by the ih argument. The GLG_IH_CURR macro can be used to specify the currently active handler, which can eliminate the need to pass the ih handler ID into all functions the handler may invoke.

The GLG_IH_GLOBAL macro can be used to add parameters to the global data storage instead of the data storage of the current handler. When parameters are added, string parameters are cloned and object parameters are referenced.

When a handler is uninstalled, all parameters stored in its data storage are automatically cleaned: string parameters are freed and object parameters are dereferenced. If pointer parameters are used to store addresses of allocated memory, the memory should be freed, as shown in the following example:

case GLG_HI_SETUP_EVENT:
  ptr = GlgAlloc( sizeof my_struct );
  GlgIHSetPParameter( ih, "my_struct", ptr );
  break;
 
...
 
case GLG_CLEANUP_EVENT:
  ptr = GlgIHGetPParameter( "my_struct" );
  GlgFree( ptr );
  break;

GlgIHSetOParameter()

void GlgIHSetOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	value
	)

Creates and stores a named parameter that keeps a GLG object ID.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

The stored object is referenced and is dereferenced when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetOParameterFromD()

void GlgIHSetOParameterFromD	(	GlgIH	ih,
		char *	name,
		double	value
	)

Creates and stores a named double parameter that is stored as a GLG Data object of the GLG_D type.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query parameter value using GlgIHGetDParameter, or to query the parameter's object ID using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetOParameterFromG()

void GlgIHSetOParameterFromG	(	GlgIH	ih,
		char *	name,
		double	value1,
		double	value2,
		double	value3
	)

Creates and stores a named parameter that keeps X, Y and Z or R, G and B values stored as a GLG Data object of the GLG_G type.

Parameters

ih	Handler ID.
name	Parameter name.
value1,value2,value3	Parameter values.

The name argument specifies the name of the parameter; this name can be used to query the parameter's object ID using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetPParameter()

void GlgIHSetPParameter	(	GlgIH	ih,
		char *	name,
		void *	value
	)

Creates and stores a named pointer parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetPParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

It is an application's responsibility to allocate memory used by the stored pointer and free it when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetSParameter()

void GlgIHSetSParameter	(	GlgIH	ih,
		char *	name,
		char *	value
	)

Creates and stores a named string parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetSParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

A copy of the string is stored and is freed when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.

GlgIHStart()

void GlgIHStart

(

void

)

Initializes and starts the current handler after it has been installed with GlgIHInstall.

This function invokes the handler's entry point with the GLG_HI_SETUP_EVENT event, which allows the handler to perform any desired initialization, such as displaying a dialog associated with the handler, if any.

Parameters can be passed to a handler by storing them in the installed handler's data storage via the SetParameter functions prior to invoking GlgIHStart, as shown in the following example:

GlgIHInstall( ConfirmIH )
GlgIHSetOParameter( GLG_IH_NEW, "ok_dialog", ok_dialog );
GlgIHSetSParameter( GLG_IH_NEW, "message", "OK to discard changes?" );
GlgIHStart();

The first argument of the SetParameter functions defines the handler to add parameters to. For convenience, a GLG_IH_NEW macro can be used to supply the ID of the just installed handler instead of using the handler ID returned by GlgIHInstall, as shown in the above example.

The following shows an example of a handler code that uses parameters from the above example to initialize the handler. The handler displays a confirmation dialog with a supplied message on start up and closes it when the handler is uninstalled. An optional modal parameter specifies if the dialog is modal.

void ConfirmIH( GlgIH ih, GlgIHCallEvent call_event )
{
   GlgIHToken token;
   char * message;
 
   // Retrieve the ID of the OK dialog provided as a parameter when the handler was installed.
   GlgObject ok_dialog = GlgIHGetOParameter( ih, "ok_dialog" );
 
   GlgCallEventType event_type = GlgIHGetType( call_event );
   switch( event_type )
   {
     case GLG_HI_SETUP_EVENT:
       // Retrieve the dialog message provided as a parameter when the handler was installed.
       message = GlgIHGetOptSParameter( ih, "message" );
 
       // Display a dialog with the requested message.
       GlgSetSResource( ok_dialog, "DialogMessageString", message );
       GlgSetDResource( ok_dialog, "Visibility", 1. );
       GlgUpdate( ok_dialog );
       break;
 
     case GLG_MESSAGE_EVENT:
       token = GlgIHGetToken( call_event );
       switch( token )
       {
         case IH_OK:
         case IH_CANCEL:
           // Uninstall the handler and pass selection to the parent.
           GlgIHUninstallWithToken( token );
           break;
 
         default:   // Some other event.
           if( GlgIHGetOptIParameter( ih, "modal_dialog", False ) )
             GlgBell( ok_dialog );  // Don't allow to leave in a modal mode.
           else
             // Uninstall the handler and pass event to the parent.
             GlgIHUninstallWithEvent( call_event );
           break;
       }
       break;
 
     case GLG_CLEANUP_EVENT:
       GlgSetDResource( ok_dialog, "Visibility", 0. );  // Erase the dialog.
       GlgUpdate( ok_dialog );
       break;
   }
}

The IH_OK and IH_CANCEL tokens used in the above example are generated by the GLG Input callback that converts interface events to integer tokens for efficiency. The tokens are then passed to the currently active handler via the GlgIHCallCurrIHWithToken function call. Refer to the /DEMOS/diagram/diagramG.c file in the GLG installation directory for a complete source code example.

GlgIHTerminate()

void GlgIHTerminate

(

void

)

Terminates installable handler utilities.

All currently installed handlers must be uninstalled before invoking this function.

GlgIHUninstall()

void GlgIHUninstall

(

void

)

Uninstalls the current handler (the last handler on the handler stack).

The handler's entry point is invoked with the GLG_CLEANUP_EVENT event prior to uninstalling to let the handler perform any required cleanup. After the handler is uninstalled, a previous handler in the handler stack (if any) becomes the current active handler. Uninstalling a handler deletes its stored data and invalidates its ID; the ID should not be used after the handler has been uninstalled.

GlgIHUninstallWithEvent()

void GlgIHUninstallWithEvent

(

GlgIHCallEvent

call_event

)

Uninstalls the current handler and passes an event to the previous handler.

Parameters

call_event

The even that will be passed to the previous handler.

If a handler receives an event that is not related to the handler's logic, this function can be used to uninstall the handler and pass the event to the previous handler.

This function uninstalls the current handler using GlgIHUninstall and passes the event to the previous handler (which becomes current after GlgIHUninstall is invoked).

GlgIHUninstallWithToken()

void GlgIHUninstallWithToken

(

GlgIHToken

token

)

Uninstalls the current handler and passes a token to the previous handler.

Parameters

token

The token that will be passed to the previous handler.

The function uninstalls the handler using GlgIHUninstall and invokes the previous handler (which becomes current after GlgIHUninstall is invoked) with the specified token.