11. Interface Handler Methods

Detailed Description

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

The Interface Handler methods 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 Methods 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_JAVA/GlgDiagram.java 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.

Constants
static GlgObject	IH_CURR
	ID of the current installable interface handler. More...
static GlgObject	IH_GLOBAL
	ID of the global data cache of the installable interface handlers. More...
static GlgObject	IH_NEW
	ID of the last installed installable interface handler. More...

Functions
static boolean	IHCallCurrIH (GlgIHCallEvent call_event)
	Passes an event to the current handler. More...
static boolean	IHCallCurrIHWithModifToken (GlgIHCallEvent call_event, int token)
	A variation on IHCallCurrIHWithToken that reuses an existing user interface event. More...
static boolean	IHCallCurrIHWithToken (int token)
	Passes a token to the current handler. More...
static void	IHCallPrevIHWithModifToken (GlgIHCallEvent call_event, int token)
	A variation on IHCallPrevIHWithToken that reuses an existing user interface event. More...
static void	IHCallPrevIHWithToken (int token)
	Passes the token to the parent handler of the currently active handler. More...
static void	IHChangeBParameter (GlgObject ih, String name, boolean value)
	Changes a boolean value stored in a named parameter. More...
static void	IHChangeDParameter (GlgObject ih, String name, double value)
	Changes a double value stored in a named parameter. More...
static void	IHChangeIParameter (GlgObject ih, String name, int value)
	Changes an integer value stored in a named parameter. More...
static void	IHChangeNParameter (GlgObject ih, String name, Object value)
	Replaces a native object stored in a named parameter. More...
static void	IHChangeOParameter (GlgObject ih, String name, GlgObject value)
	Replaces a GLG object stored in a named parameter. More...
static void	IHChangeSParameter (GlgObject ih, String name, String value)
	Replaces a string stored in a named parameter. More...
static boolean	IHGetBParameter (GlgObject ih, String name)
	Returns a boolean value stored in a named parameter. More...
static GlgObject	IHGetCurrIH ()
	Retrieves the current active interface handler. More...
static double	IHGetDParameter (GlgObject ih, String name)
	Returns a double value stored in a named parameter. More...
static GlgIHHandlerInterface	IHGetHandlerInterface (GlgObject ih)
	Retrieves a handler interface instance used to implement a handler. More...
static int	IHGetIParameter (GlgObject ih, String name)
	Returns an integer value stored in a named parameter. More...
static Object	IHGetNParameter (GlgObject ih, String name)
	Returns a native object stored in a named parameter. More...
static GlgObject	IHGetOParameter (GlgObject ih, String name)
	Returns a GLG object stored in a named parameter. More...
static boolean	IHGetOptBParameter (GlgObject ih, String name, boolean default_value)
	Returns a boolean value stored in an optional named parameter. More...
static double	IHGetOptDParameter (GlgObject ih, String name, double default_value)
	Returns a double value stored in an optional named parameter. More...
static int	IHGetOptIParameter (GlgObject ih, String name, int default_value)
	Returns an integer value stored in an optional named parameter. More...
static Object	IHGetOptNParameter (GlgObject ih, String name, Object default_value)
	Returns a native object stored in an optional named parameter. More...
static GlgObject	IHGetOptOParameter (GlgObject ih, String name, GlgObject default_value)
	Returns a GLG object stored in an optional named parameter. More...
static String	IHGetOptSParameter (GlgObject ih, String name, String default_value)
	Returns a string stored in an optional named parameter. More...
static GlgIHHandlerInterface	IHGetPrevHandlerInterface ()
	Retrieves a handler interface instance used to implement the parent handler of the currently active handler. More...
static GlgObject	IHGetPrevIH ()
	Retrieves the currently active interface handler's parent handler. More...
static String	IHGetSParameter (GlgObject ih, String name)
	Returns a string stored in a named parameter. More...
static int	IHGetToken (GlgIHCallEvent call_event)
	Returns a token associated with the MESSAGE_EVENT event. More...
static GlgCallEventType	IHGetType (GlgIHCallEvent call_event)
	Returns an event's type. More...
static void	IHInit ()
	Initializes installable handler utilities, must be invoked after Init, but before any installable handler methods are used. More...
static GlgObject	IHInstall (GlgIHHandlerInterface handler_interface)
	Creates an interface handler with the specified handler interface and installs it. More...
static void	IHPassToken (GlgIHHandlerInterface handler_interface, int token, boolean uninstall)
	Installs a handler, starts it and invokes its entry point with the specified token. More...
static void	IHResetup (GlgObject ih)
	Reinitializes the current handler that have already been installed to "restart" its logic. More...
static void	IHSetBParameter (GlgObject ih, String name, boolean value)
	Creates and stores a named boolean parameter. More...
static void	IHSetDParameter (GlgObject ih, String name, double value)
	Creates and stores a named string parameter. More...
static void	IHSetIParameter (GlgObject ih, String name, int value)
	Creates and stores a named integer parameter. More...
static void	IHSetNParameter (GlgObject ih, String name, Object value)
	Creates and stores a named parameter that holds any native object. More...
static void	IHSetOParameter (GlgObject ih, String name, GlgObject value)
	Creates and stores a named parameter that holds a GLG object. More...
static void	IHSetOParameterFromD (GlgObject ih, String name, double value)
	Creates and stores a named double parameter that is stored as a GLG Data object of the D type. More...
static void	IHSetOParameterFromG (GlgObject ih, String 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 G type. More...
static void	IHSetOParameterFromG (GlgObject ih, String name, GlgPoint point)
	Creates and stores a named parameter that contains geometrical (XYZ) or color (RGB) data and is stored as a GLG Data object of the G type. More...
static void	IHSetSParameter (GlgObject ih, String name, String value)
	Creates and stores a named string parameter. More...
static void	IHStart ()
	Initializes and starts the current handler after it has been installed with 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...

Variable Documentation

IH_CURR

GlgObject IH_CURR

static

ID of the current installable interface handler.

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

IH_GLOBAL

GlgObject IH_GLOBAL

static

ID of the global data cache of the installable interface handlers.

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

IH_NEW

GlgObject IH_NEW

static

ID of the last installed installable interface handler.

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

Function Documentation

IHCallCurrIH()

static boolean IHCallCurrIH ( GlgIHCallEvent  call_event )

static

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 method invokes the current handler's entry point with the specified user interface event.

IHCallCurrIHWithModifToken()

static boolean IHCallCurrIHWithModifToken ( GlgIHCallEvent  call_event, int  token  )

static

A variation on IHCallCurrIHWithToken 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 method is the same as IHCallCurrIHWithToken, 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.

IHCallCurrIHWithToken()

static boolean IHCallCurrIHWithToken ( int  token )

static

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 method 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.

IHCallPrevIHWithModifToken()

static void IHCallPrevIHWithModifToken ( GlgIHCallEvent  call_event, int  token  )

static

A variation on IHCallPrevIHWithToken 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 method is the same as IHCallPrevIHWithToken, 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 IHUninstall.

IHCallPrevIHWithToken()

static void IHCallPrevIHWithToken ( int  token )

static

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 IHUninstall.

IHChangeBParameter()

static void IHChangeBParameter ( GlgObject  ih, String  name, boolean  value  )

static

Changes a boolean value stored in a named parameter.

Parameters

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

This method is similar to IHSetBParameter, 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.

IHChangeDParameter()

static void IHChangeDParameter ( GlgObject  ih, String  name, double  value  )

static

Changes a double value stored in a named parameter.

Parameters

ih	Handler ID, or IH_GLOBAL to replace a global parameter.
name	Parameter name.
value	New parameter value.

This method is similar to IHSetDParameter, 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.

IHChangeIParameter()

static void IHChangeIParameter ( GlgObject  ih, String  name, int  value  )

static

Changes an integer value stored in a named parameter.

Parameters

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

This method is similar to IHSetIParameter, 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.

IHChangeNParameter()

static void IHChangeNParameter ( GlgObject  ih, String  name, Object  value  )

static

Replaces a native object stored in a named parameter.

Parameters

ih	Handler ID, or IH_GLOBAL to replace a global parameter.
name	Parameter name.
value	New parameter value.

This method is similar to IHSetNParameter, 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.

IHChangeOParameter()

static void IHChangeOParameter ( GlgObject  ih, String  name, GlgObject  value  )

static

Replaces a GLG object stored in a named parameter.

Parameters

ih	Handler ID, or IH_GLOBAL to replace a global parameter.
name	Parameter name.
value	New parameter value.

This method is similar to IHSetOParameter, 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.

IHChangeSParameter()

static void IHChangeSParameter ( GlgObject  ih, String  name, String  value  )

static

Replaces a string stored in a named parameter.

Parameters

ih	Handler ID, or IH_GLOBAL to replace a global parameter.
name	Parameter name.
value	New parameter value.

This method is similar to IHSetSParameter, 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.

IHGetBParameter()

static boolean IHGetBParameter ( GlgObject  ih, String  name  )

static

Returns a boolean value stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetCurrIH()

static GlgObject IHGetCurrIH ( )

static

Retrieves the current active interface handler.

The current active handler can also be accessed via IH_CURR.

Returns

The current handler.

IHGetDParameter()

static double IHGetDParameter ( GlgObject  ih, String  name  )

static

Returns a double value stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetHandlerInterface()

static GlgIHHandlerInterface IHGetHandlerInterface ( GlgObject  ih )

static

Retrieves a handler interface instance used to implement a handler.

Parameters

ih	The handler to query. IH_CURR object can be used as the ih parameter to access the current handler.

Returns

The handler's interface instance.

IHGetIParameter()

static int IHGetIParameter ( GlgObject  ih, String  name  )

static

Returns an integer value stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetNParameter()

static Object IHGetNParameter ( GlgObject  ih, String  name  )

static

Returns a native object stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetOParameter()

static GlgObject IHGetOParameter ( GlgObject  ih, String  name  )

static

Returns a GLG object stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetOptBParameter()

static boolean IHGetOptBParameter ( GlgObject  ih, String  name, boolean  default_value  )

static

Returns a boolean value stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetBParameter, 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.

IHGetOptDParameter()

static double IHGetOptDParameter ( GlgObject  ih, String  name, double  default_value  )

static

Returns a double value stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetDParameter, 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.

IHGetOptIParameter()

static int IHGetOptIParameter ( GlgObject  ih, String  name, int  default_value  )

static

Returns an integer value stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetIParameter, 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.

IHGetOptNParameter()

static Object IHGetOptNParameter ( GlgObject  ih, String  name, Object  default_value  )

static

Returns a native object stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetNParameter, 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.

IHGetOptOParameter()

static GlgObject IHGetOptOParameter ( GlgObject  ih, String  name, GlgObject  default_value  )

static

Returns a GLG object stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetOParameter, 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.

IHGetOptSParameter()

static String IHGetOptSParameter ( GlgObject  ih, String  name, String  default_value  )

static

Returns a string stored in an optional named parameter.

Parameters

ih	Handler ID, or 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 method is the same as IHGetSParameter, 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.

IHGetPrevHandlerInterface()

static GlgIHHandlerInterface IHGetPrevHandlerInterface ( )

static

Retrieves a handler interface instance used to implement the parent handler of the currently active handler.

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

Parameters

ih	The handler to query. IH_CURR object can be used as the ih parameter to access the current handler.

Returns

The parent handler's interface instance.

IHGetPrevIH()

static GlgObject IHGetPrevIH ( )

static

Retrieves 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.

IHGetSParameter()

static String IHGetSParameter ( GlgObject  ih, String  name  )

static

Returns a string stored in a named parameter.

Parameters

ih	Handler ID, or 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.

IHGetToken()

static int IHGetToken ( GlgIHCallEvent  call_event )

static

Returns a token associated with the 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:

static final int
  IH_UNDEFINED_TOKEN = 0,
  IH_OK = 1,
  IH_CANCEL = 2;

In a GLG application, Input and Trace callbacks are used to convert interface events to tokens, as shown in the DEMOS_JAVA/GlgDiagram.java file in the GLG installation directory. The tokens are then passed to the currently active handler via IHCallCurrIHWithToken.

IHGetType()

static GlgCallEventType IHGetType ( GlgIHCallEvent  call_event )

static

Returns an event's type.

Parameters

call_event

The user interface event a handler was invoked with.

Returns

The event's type:

• HI_SETUP_EVENT is received when the handler is started using IHStart; is used to perform any required initialization.
• HI_RESETUP_EVENT is received when the handler is reinitialized via IHResetup.
• CLEANUP_EVENT is received before destroying the handler when it is uninstalled; is used to perform any required cleanup.
• MESSAGE_EVENT is a message event that is further identified by the associated token.

IHInit()

static void IHInit ( )

static

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

IHInstall()

static GlgObject IHInstall ( GlgIHHandlerInterface  handler_interface )

static

Creates an interface handler with the specified handler interface and installs it.

Parameters

handler_interface

An interface object that implements the handler's interaction logic.

Returns

Installed handler object.

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.

IHPassToken()

static void IHPassToken ( GlgIHHandlerInterface  handler_interface, int  token, boolean  uninstall  )

static

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

Parameters

handler_interface	A handler interface 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 method 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.

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:

import com.genlogic.*;
import static com.genlogic.GlgObject.*;
 
class ConfirmIH implements GlgIHHandlerInterface
{
   public void EntryPoint( GlgObject ih, GlgIHCallEvent call_event )
   {
      // Retrieve the OK dialog ID provided as a parameter when the handler was installed.
      GlgObject ok_dialog = IHGetOParameter( ih, "ok_dialog" );
 
      GlgCallEventType event_type = IHGetType( call_event );
      switch( event_type )
      {
        case HI_SETUP_EVENT:
          // Retrieve the dialog message provided as a parameter when the handler was installed.
          String message = IHGetOptSParameter( ih, "message" );
 
          // Set the dialog's message to the requested message.
          message.SetSResource( ok_dialog, "DialogMessageString" );
          // Fall through to popup the dialog.
 
        case HI_RESETUP_EVENT: // Popup the dialog again.
          ok_dialog.SetDResource( "Visibility", 1. );
          ok_dialog.Update();
          break;
 
        ...
      }
   }
}

Refer to the DEMOS_JAVA/GlgDiagram.java file in the GLG installation directory for a source code example of using this method.

IHSetBParameter()

static void IHSetBParameter ( GlgObject  ih, String  name, boolean  value  )

static

Creates and stores a named boolean 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 IHGetBParameter. 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.

IHSetDParameter()

static void IHSetDParameter ( GlgObject  ih, String  name, double  value  )

static

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 IHGetDParameter. 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.

IHSetIParameter()

static void IHSetIParameter ( GlgObject  ih, String  name, int  value  )

static

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 IHGetIParameter. 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 following placeholders can also be passed as the ih argument:

• IH_NEW can be used to specify the handler after it was created using IHInstall and before it is started with IHStart.
• IH_CURR can be used to specify the currently active handler, which can eliminate the need to pass the ih handler ID into all methods the handler may invoke.
• IH_GLOBAL object can be used to add parameters to the global data storage instead of the data storage of the current handler.

When a handler is uninstalled, all parameters stored in its data storage are discarded.

IHSetNParameter()

static void IHSetNParameter ( GlgObject  ih, String  name, Object  value  )

static

Creates and stores a named parameter that holds any native object.

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 IHGetNParameter. 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.

IHSetOParameter()

static void IHSetOParameter ( GlgObject  ih, String  name, GlgObject  value  )

static

Creates and stores a named parameter that holds a GLG object.

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 IHGetOParameter. 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.

IHSetOParameterFromD()

static void IHSetOParameterFromD ( GlgObject  ih, String  name, double  value  )

static

Creates and stores a named double parameter that is stored as a GLG Data object of the 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 IHGetDParameter, or to query the stored parameter object using IHGetOParameter. 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.

IHSetOParameterFromG() [1/2]

static void IHSetOParameterFromG ( GlgObject  ih, String  name, double  value1, double  value2, double  value3  )

static

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 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 stored parameter object using IHGetOParameter. 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.

IHSetOParameterFromG() [2/2]

static void IHSetOParameterFromG ( GlgObject  ih, String  name, GlgPoint  point  )

static

Creates and stores a named parameter that contains geometrical (XYZ) or color (RGB) data and is stored as a GLG Data object of the G type.

Parameters

ih	Handler ID.
name	Parameter name.
point	A GlgPoint object containing parameter values.

The name argument specifies the name of the parameter; this name can be used to query the stored parameter object using IHGetOParameter. 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.

IHSetSParameter()

static void IHSetSParameter ( GlgObject  ih, String  name, String  value  )

static

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 IHGetSParameter. 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.

IHStart()

static void IHStart ( )

static

Initializes and starts the current handler after it has been installed with 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:

IHInstall( ConfirmIH )
IHSetOParameter( IH_NEW, "ok_dialog", ok_dialog );
IHSetSParameter( IH_NEW, "message", "OK to discard changes?" );
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.

import com.genlogic.*;
import static com.genlogic.GlgObject.*;
 
class ConfirmIH implements GlgIHHandlerInterface
{
   public void EntryPoint( GlgObject ih, GlgIHCallEvent call_event )
   {
      // Retrieve the OK dialog object provided as a parameter when the handler was installed.
      GlgObject ok_dialog = IHGetOParameter( ih, "ok_dialog" );
 
      GlgCallEventType event_type = IHGetType( call_event );
      switch( event_type )
      {
        case HI_SETUP_EVENT:
          // Retrieve the dialog message provided as a parameter when the handler was installed.
          String message = 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 MESSAGE_EVENT:
          int token = IHGetToken( call_event );
          switch( token )
          {
            case IH_OK:
            case IH_CANCEL:
              // Uninstall the handler and pass selection to the parent.
              IHUninstallWithToken( token );
           break;
 
         default:   // Some other event.
           if( IHGetOptIParameter( ih, "modal_dialog", False ) )
             Bell();  // Don't allow to leave in a modal mode.
           else
             // Uninstall the handler and pass event to the parent.
             IHUninstallWithEvent( call_event );
           break;
       }
       break;
 
     case 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_JAVA/GlgDiagram.java 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.