Resource Access Optimization

If null is passed as the resource_name parameter of methods for setting and querying resources, the data object supplied by the object parameter will be used directly, avoiding an overhead of a resource search. This can be used to optimize performance when the same resource is accessed repeatedly. The GetResourceObject method of the Intermediate API may be used to obtain an object ID of a data object once and then use it repeatedly.

For example:

// Store a data object for repeated use.
GlgObject data_obj = viewport.GetResourceObject( "WaterTank/Level" );
 
...
 
// Use the stored data object to update the drawing with data.
if( data_obj != null )
  data_obj.SetDResource( null, new_water_level_value );

The AddDataSampleNode method of the Intermediate API can also be used instead of setting values of chart entry points to prefill a chart with a large number of data samples.

Container Objects

GLG Container objects include ARRAY "Dynamic Array", LIST "List" and VECTOR "Vector" objects.

The following composite objects are also containers and may be used with container methods:

Viewport is a container of objects rendered inside it, which can be accessed as elements of the viewport.
Group is a container used to group objects in a drawing.
GIS Object is a container of GIS icons displayed on top of the map in lat/lon coordinates.
Polygon, Spline and Connector objects are containers of their control points, which can also be accessed as their elements.

When a container object is created, one of the creation parameters is the type of elements it will contain (see GlgContainerType for more information):

There are three types of containers:

ARRAY "Dynamic Array" grows its size as needed when new elements are added. It is used by objects, such as groups and viewports, that need to hold their subobjects, as well as by polygons that use it to contain their control points.
LIST "List" provides an efficient handling in cases when elements need to be frequently added and removed. It is used by chart plots to keep their data samples.
VECTOR "Vector" is a fixed size container mostly used by the Toolkit's internals.

There are two flavors of container methods:

Methods that use indexing to access container's elements provide convenient access to elements of the dynamic array containers. These method still work on both arrays and lists, but are less efficient when they are used for list objects because they require traversing list elements.
Methods that iterate a container or use its current position may be used with both dynamic array and list containers, and provide more efficient handling of list containers.

The Extended API provides additional methods for adding and deleting elements of a container.

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.