Interaction Handler Methods

This group contains methods used to develop custom interaction handlers. More...

Detailed Description

This group contains methods used to develop custom interaction handlers.

See GlgHandler for more information.

Functions
static void	AddHandler (String handler_name, GlgHandler handler)
	Registers a custom interaction handler. More...
static GlgObject	CreateMessage (GlgObject viewport)
	Creates a GLG message object that may be sent by an interaction handler to a parent handler or a parent's Input callback via SendMessageToParent. More...
static Object	GetHandlerData (GlgObject viewport)
	Retrieves stored data used by a custom handler instance. More...
static void	SendMessageToParent (GlgObject viewport, GlgObject message_obj, String action, String subaction)
	Sends a message to the Input callback. More...
static void	SetHandlerData (GlgObject viewport, Object data)
	Stores data used by the custom handler instance. More...

Function Documentation

AddHandler()

static void AddHandler ( String  handler_name, GlgHandler  handler  )

static

Registers a custom interaction handler.

Parameters

handler_name	The handler name. The name may be assigned to the Handler attribute of a viewport or a light viewport in the GLG drawing. The name should start with the $ character to avoid generating error messages in GLG editors if the handler assigned to the viewport is not activated in the editor via the GLG Editor Custom Option DLL described here.
handler	The handler's interface that implements the handler's functionality.

See GlgHandler for more information.

CreateMessage()

static GlgObject CreateMessage ( GlgObject  viewport )

static

Creates a GLG message object that may be sent by an interaction handler to a parent handler or a parent's Input callback via SendMessageToParent.

Parameters

viewport

The handler's viewport.

Returns

New message object.

The message object's Origin resource will be set to the viewport's name, and the Object resource will be set to the viewport's object ID. The handler can add objects containing additional information to the message object.

The message object is usually stored to be reused for the duration of the handler lifetime, as shown in the Sample Implementation.

GetHandlerData()

static Object GetHandlerData ( GlgObject  viewport )

static

Retrieves stored data used by a custom handler instance.

This method is invoked on the viewport or light viewport the handler is attached to.

Parameters

viewport

The viewport the handler is attached to.

Returns

The stored data.

SendMessageToParent()

static void SendMessageToParent ( GlgObject  viewport, GlgObject  message_obj, String  action, String  subaction  )

static

Sends a message to the Input callback.

This method is used by custom interaction handlers to invoke an application's Input callback.

Parameters

viewport	The handler's viewport.
message_obj	A GLG message object created via CreateMessage.
action	The action to be set as the message's Action resource. If action=null, the message will be sent as is without setting its action and sub_action.
subaction	The subaction to be set as the message's SubAction resource.

The message is first sent to the handler of the viewport's parent (if any), which can either process and stop message propagation, or send the message to the Input callback. For example, when a spinner's Increase button is pressed, it sends a message to the spinner's handler, which increments the value and stops message propagation. If a stand-alone Increase button is pressed, the message is sent directly to the Input callback. This logic allows parent input handlers handle messages from their children's handlers.

SetHandlerData()

static void SetHandlerData ( GlgObject  viewport, Object  data  )

static

Stores data used by the custom handler instance.

This method is invoked on the viewport or light viewport the handler is attached to.

Parameters

viewport	The viewport the handler is attached to.
data	The data to be stored.

A custom handler can store its data on set up using this method, and obtain the stored data using GetHandlerData when the handler is invoked to handle user interaction.