GlgHandler Interface Reference

Interface used to implement custom interaction handlers. More...

Detailed Description

Interface used to implement custom interaction handlers.

The Toolkit provides a number of stock interaction handlers, such as GlgButton, GlgSlider, etc., which also use this interface. 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's EntryPoint method that is invoked with different parameters to handle handler initialization and user interaction.

A custom handler is created using GlgHandler.CreateGlgHandler and is installed by registering the handler object as a named handler using the AddHandler method, which takes the handler name and its entry point as parameters:

let GLG = new GlgToolkit();
...
let test_handler = GLG.CreateGlgHandler( TestHandlerFunction );
GLG.AddHandler( "$TestHandler", test_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 C version of the handler 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.

Interaction Handler Methods

The following methods may be used by the handler's code:

• SetHandlerData and GetHandlerData can be used to store application-specific handler's data in the handler instance.
• GetNativeEventType, GetNativeEventXY, GetNativeEventKey retrieve properties of the native event that triggered handler invocation.
• CreateMessage and SendMessageToParent can be used to sends a message to the Input callback.

Sample Implementation

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

The C version of the sample code is provided in the src/SampleHandler/SampleHandler.c file and is integrated into the GLG Editor Custom Option DLL to make the sample handler active inside GLG editors. To test the the sample handler in the Graphics Builder, run the following script:

• On Linux/Unix:

  <glg_dir>/editor_extensions/custom_option_example/run_option_example

  
  
• On Windows:

  <glg_dir>\editor_extensions\custom_option_example\run_option_example.bat

then load the sample_handler.g drawing into a 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.

Inherited by GlgBrowserHandler, GlgButtonHandler, GlgClockHandler, GlgFontBrowserHandler, GlgKnobHandler, GlgMenuHandler, GlgNButtonHandler, GlgNListHandler, GlgNOptionHandler, GlgNSliderHandler, GlgNTextHandler, GlgPaletteHandler, GlgSliderHandler, GlgSpinnerHandler, GlgTextHandler, GlgTimerHandler, and GlgXftFontBrowserHandler.

Public Member Functions
void	EntryPoint (GlgCallEvent call_event)
	A handler's entry point. More...

Static Public Member Functions
static GlgHandler	CreateGlgHandler (function handler_func)
	Constructor. More...

Member Function Documentation

CreateGlgHandler()

static GlgHandler CreateGlgHandler ( function  handler_func )

static

Constructor.

Creates an interaction handler that can be used as a parameter of the GlgObject::AddHandler method. The static method is invoked on the GLG Toolkit handle obtained via a 'new GlgToolkit()' call at the application start-up.

Parameters

handler_func

A custom interaction handler function that implements the handler's logic. The function's type signature must match the type signature of the EntryPoint method.

Returns

An opaque internal object representing GlgHandler.

EntryPoint()

void EntryPoint

(

GlgCallEvent

call_event

)

A handler's entry point.

This method implements interaction handler's functionality and is invoked to handle user interaction of the viewport the handler is attached to.

Parameters

call_event

The user interaction event to be handled, provides information about the event that triggered handler invocation.