Invoking and Event Handling

Detailed Description

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 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	IHPassToken (GlgIHHandlerInterface handler_interface, int token, boolean uninstall)
	Installs a handler, starts it and invokes its entry point with the specified token. More...

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.

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:

const
  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_HTML5/misc_demos/GlgDiagramgEditor.js 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.

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.