Invoking and Event Handling

Detailed Description

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...
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	GlgIHPassToken (GlgIHEntryPoint handler, GlgIHToken token, GlgBoolean uninstall)
	Installs a handler, starts it and invokes its entry point with the specified token. More...

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.

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.

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.