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

Detailed Description

This group contains functions used to develop custom interaction handlers.

The Toolkit provides a number of stock interaction handlers, such as GlgButton, GlgSlider, etc. Custom interaction handlers may be developed to be used in the GLG editors as well as in the application at run time.

A custom handler implements an application-specific logic for handling user interaction and is associated with a viewport in a GLG drawing the same way as the stock interaction handlers. In GLG editors, a custom handler is attached to a viewport or a light viewport by assigning the handler name as a value of the viewport's Handler attribute. To avoid error messages in case the custom handler is implemented only in the runtime application code, the custom handler name should start with the $ character, for example "$SampleHandler".

Custom interaction handler code implements a single handler entry point function that will be invoked with different parameters to handle handler initialization and user interaction. The handler is installed by registering this function as a named handler using the GlgAddHandler function, which takes the handler name and its entry point as parameters:

GlgAddHandler( "$TestHandler", TestHandler );

GlgAddHandler

void GlgAddHandler(char *handler_name, GlgHandler func)

Registers a custom interaction handler.

This activates the custom handler in the application at run time.

Using Custom Handlers in the Graphics Builder

To activate the handler in GLG editors, the handler's code can be added to the GLG Editor Custom Options DLL described in the OEM Editor Extensions, Custom Editor Options and Dialogs DLL section of the OEM Customization chapter of the GLG User's Guide and Builder Reference Manual.

Sample Implementation

Sample source code of a custom interaction handler is provided by the src/SampleHandler/SampleHandler.c file in the GLG installation directory.

The sample code is also integrated into the GLG Editor Custom Option DLL to make the sample handler active inside GLG editors. To test the sample handler in the Graphics Builder, run the following script:

On Linux/Unix:
<glg_dir>/editor_extensions/custom_option_example/run_option_example</i>
On Windows:
<glg_dir>\editor_extensions\custom_option_example\run_option_example.bat

then load the sample_handler.g drawing into the Graphics Builder from one of the following locations:

<GLG_DIR>/editor_extensions/custom_option_example/sample_handler.g

<GLG_DIR>/src/SampleHandler/sample_handler.g

Start the prototype mode using the Run, Start menu option, then press the Skip Command button. Click on the buttons to interact with the handler: it will count clicks, and will also trace and display mouse coordinates.

Functions
void	GlgAddHandler (char *handler_name, GlgHandler func)
	Registers a custom interaction handler. More...

GlgObject	GlgCreateMessage (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 GlgSendMessageToParent. More...

void *	GlgGetHandlerData (GlgObject viewport)
	Retrieves stored data used by a custom handler instance. More...

PlatformDependent	GlgHandlerGetNativeEvent (GlgCallEvent *call_event)
	Retrieves a native event that triggered handler invocation. More...

void	GlgSendMessageToParent (GlgObject viewport, GlgObject message_obj, char action, char subaction)
	Sends a message to the Input callback. More...

void	GlgSetHandlerData (GlgObject viewport, void *data)
	Stores data used by the custom handler instance. More...

Function Documentation

◆ GlgAddHandler()

void GlgAddHandler	(	char *	handler_name,
		GlgHandler	func
	)

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.
func	The handler's entry point function that implements the handler's functionality.

See Interaction Handler Functions for more information.

◆ GlgCreateMessage()

GlgObject GlgCreateMessage ( 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 GlgSendMessageToParent.

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 and has to be dereferenced with GlgDropObject when the handler is cleaned up to prevent memory leaks, as shown in the Sample Implementation.

◆ GlgGetHandlerData()

void* GlgGetHandlerData ( GlgObject viewport )

Retrieves stored data used by a custom handler instance.

Parameters

viewport The viewport or the light viewport the handler is attached to.

Returns: The stored data.

◆ GlgHandlerGetNativeEvent()

PlatformDependent GlgHandlerGetNativeEvent ( GlgCallEvent * call_event )

Retrieves a native event that triggered handler invocation.

Parameters

call_event A pointer to the call_event structure the handler was invoked with.

Returns

A pointer to a native event that triggered handler invocation:

GXEvent * on Windows
XEvent * in X11
MSG * on Windows

The returned native event can be used to retrieve the type of the event and the mouse coordinates if the handler needs to handle mouse and keyboard events. The code for handling native events is the same as the code in the Trace callback.

The GLG_NATIVE_EVENT case of the Sample Implementation source code provides an example of handling of mouse events.

◆ GlgSendMessageToParent()

void GlgSendMessageToParent	(	GlgObject	viewport,
		GlgObject	message_obj,
		char *	action,
		char *	subaction
	)

Sends a message to the Input callback.

This function 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 GlgCreateMessage.
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.

◆ GlgSetHandlerData()

void GlgSetHandlerData	(	GlgObject	viewport,
		void *	data
	)

Stores data used by the custom handler instance.

Parameters

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

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