GlgHandler

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 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:

GlgObject.AddHandler( "$TestHandler", TestHandlerInterface );

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.
• 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.java 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
GlgHandler	Clone ()
	The handler's clone method. More...
void	EntryPoint (GlgCallEvent call_event)
	A handler's entry point. More...

Member Function Documentation

Clone()

GlgHandler Clone

(

)

The handler's clone method.

For interaction handlers that do not have instance variables, this method can return this handler. For handlers that have instance variables, it must create and return a new instance of the handler.

Returns

A copy of the GlgHandler object.

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.