Installing and Uninstalling

Detailed Description

Functions
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	GlgIHResetup (GlgIH ih)
	Reinitializes the current handler that have already been installed and used to "restart" its logic. 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...

Function Documentation

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.

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.

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.