Installing and Uninstalling

Detailed Description

Functions
static void	IHInit ()
	Initializes installable handler utilities, must be invoked before any installable handler methods are used. More...
static GlgObject	IHInstall (GlgIHHandlerInterface handler_interface)
	A low-level method that creates and installs an interface handler with the specified handler interface. More...
static GlgObject	IHInstallAsInterface (Function entry_point)
	Provides a simplified interface to the IHInstall method. More...
static void	IHResetup (GlgObject ih)
	Reinitializes the current handler that have already been installed to "restart" its logic. More...
static void	IHStart ()
	Initializes and starts the current handler after it has been installed with IHInstallAsInterface or IHInstall. More...
static void	IHTerminate ()
	Terminates installable handler utilities. More...
static void	IHUninstall ()
	Uninstalls the current handler (the last handler on the handler stack). More...
static void	IHUninstallWithEvent (GlgIHCallEvent call_event)
	Uninstalls the current handler and passes an event to the previous handler. More...
static void	IHUninstallWithToken (int token)
	Uninstalls the current handler and passes a token to the previous handler. More...

Function Documentation

IHInit()

static void IHInit ( )

static

Initializes installable handler utilities, must be invoked before any installable handler methods are used.

IHInstall()

static GlgObject IHInstall ( GlgIHHandlerInterface  handler_interface )

static

A low-level method that creates and installs an interface handler with the specified handler interface.

The IHInstallAsInterface method provides a simplified interface for creating and installing interface handlers.

Parameters

handler_interface

An interface object that implements the handler's interaction logic and is created using CreateGlgIHHandlerInterface.

Returns

An opaque internal object representing installed handler.

This method creates an interface handler, adds it to a stack of handlers and returns created handler object. 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 IHStart for an example of a handler code.

IHInstallAsInterface()

static GlgObject IHInstallAsInterface ( Function  entry_point )

static

Provides a simplified interface to the IHInstall method.

The method creates a GlgIHHandlerInterface object with a supplied function as a entry point, then creates and installs an interface handler that uses this handler interface.

Parameters

entry_point

A function that implements the handler's interaction logic. The function's type signature must match the type signature of the EntryPoint method of the GlgIHHandlerInterface interface.

Returns

An opaque internal object representing installed handler.

This method creates an interface handler, adds it to a stack of handlers and returns created handler object. 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 IHStart for an example of a handler code.

IHResetup()

static void IHResetup ( GlgObject  ih )

static

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

For example, if a handler handles selecting a text object with the mouse, and a user selects an a polygon, the handler can issue an error message and restart its operation by invoking IHResetup.

Parameters

ih	Handler ID.

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

function ConfirmIH( ih, call_event )
{
   // Retrieve the OK dialog ID provided as a parameter when the handler was installed.
   let ok_dialog = GLG.IHGetOParameter( ih, "ok_dialog" );
 
   let event_type = GLG.IHGetType( call_event );
   switch( event_type )
   {
     case GLG.HI_SETUP_EVENT:
       // Retrieve the dialog message provided as a parameter when the handler was installed.
       let message = GLG.IHGetOptSParameter( ih, "message" );
 
       // Set the dialog's message to the requested message.
       message.SetSResource( ok_dialog, "DialogMessageString" );
       // Fall through to popup the dialog.
 
     case GLG.HI_RESETUP_EVENT: // Popup the dialog again.
       ok_dialog.SetDResource( "Visibility", 1. );
       ok_dialog.Update();
       break;
 
     ...
   }
}

Refer to the DEMOS_HTML5/misc_demos/GlgDiagramgEditor.js file in the GLG installation directory for a source code example of using this method.

IHStart()

static void IHStart ( )

static

Initializes and starts the current handler after it has been installed with IHInstallAsInterface or IHInstall.

This method invokes the handler's entry point with the 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 methods prior to invoking IHStart, as shown in the following example:

GLG.IHInstallAsInterface( ConfirmIH )
GLG.IHSetOParameter( GLG.IH_NEW, "ok_dialog", ok_dialog );
GLG.IHSetSParameter( GLG.IH_NEW, "message", "OK to discard changes?" );
GLG.IHStart();

The first argument of the SetParameter methods defines the handler to add parameters to. For convenience, the IH_NEW object can be used to supply the ID of the just installed handler instead of using the handler ID returned by IHInstall, 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.

function ConfirmIH( ih, call_event )
{
   // Retrieve the OK dialog object provided as a parameter when the handler was installed.
   let ok_dialog = GLG.IHGetOParameter( ih, "ok_dialog" );
 
   let event_type = GLG.IHGetType( call_event );
   switch( event_type )
   {
     case GLG.CallEventType.HI_SETUP_EVENT:
       // Retrieve the dialog message provided as a parameter when the handler was installed.
       let message = GLG.IHGetOptSParameter( ih, "message" );
 
       // Display a dialog with the requested message.
       ok_dialog.SetSResource( "DialogMessageString", message );
       ok_dialog.SetDResource( "Visibility", 1. );
       ok_dialog.Update();
       break;
 
     case GLG.CallEventType.MESSAGE_EVENT:
       let token = GLG.IHGetToken( call_event );
       switch( token )
       {
         case IH_OK:
         case IH_CANCEL:
           // Uninstall the handler and pass selection to the parent.
           GLG.IHUninstallWithToken( token );
           break;
 
         default:   // Some other event.
           if( GLG.IHGetOptIParameter( ih, "modal_dialog", False ) )
             GLG.Bell();  // Don't allow to leave in a modal mode.
           else
             // Uninstall the handler and pass event to the parent.
             GLG.IHUninstallWithEvent( call_event );
           break;
       }
       break;
 
     case GLG.CallEventType.CLEANUP_EVENT:
       ok_dialog.SetDResource( "Visibility", 0. );  // Erase the dialog.
       ok_dialog.Update();
       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 a call to the IHCallCurrIHWithToken method.

Refer to the DEMOS_HTML5/misc_demos/GlgDiagramgEditor.js file in the GLG installation directory for a complete source code example.

IHTerminate()

static void IHTerminate ( )

static

Terminates installable handler utilities.

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

IHUninstall()

static void IHUninstall ( )

static

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

The handler's entry point is invoked with the 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.

IHUninstallWithEvent()

static void IHUninstallWithEvent ( GlgIHCallEvent  call_event )

static

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 method can be used to uninstall the handler and pass the event to the previous handler.

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

IHUninstallWithToken()

static void IHUninstallWithToken ( int  token )

static

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 method uninstalls the handler using IHUninstall and invokes the previous handler (which becomes current after IHUninstall is invoked) with the specified token.