User Interaction

This group lists callbacks installed with GlgAddCallback and used to handle user interaction with objects in the drawing. More...

Detailed Description

This group lists callbacks installed with GlgAddCallback and used to handle user interaction with objects in the drawing.

Typedefs
typedef void(*	GlgCallbackProc) (GlgObject viewport, GlgAnyType data1, GlgAnyType data2)
	A platform-independent GLG callback installed via GlgAddCallback and used for the Input, Select, adds Trace and Hierarchy callbacks. More...
typedef void(*	GlgInputCallback) (GlgObject viewport, GlgAnyType client_data, GlgObject message_object)
	An Input callback is used to handle user interaction with input objects, as well as to perform object selection and action processing. More...
typedef void(*	GlgSelectCallback) (GlgObject viewport, GlgAnyType client_data, char **name_array)
	A simplified selection callback used to process name-based object selection, installed via GlgAddCallback. More...
typedef void(*	GlgTraceCallback) (GlgObject viewport, GlgAnyType client_data, GlgTraceCBStruct *trace_info)
	A Trace callback used to handle native windowing events, installed via GlgAddCallback. More...

Typedef Documentation

GlgCallbackProc

typedef void(* GlgCallbackProc) (GlgObject viewport, GlgAnyType data1, GlgAnyType data2)

A platform-independent GLG callback installed via GlgAddCallback and used for the Input, Select, adds Trace and Hierarchy callbacks.

Parameters

viewport	The viewport object the callback is attached to.
data1	Callback type specific data.
data2	Callback type specific data.

See GlgInputCallback, GlgSelectCallback, GlgTraceCallback and GlgHierarchyCallback for a description of available callback types.

See the Callback Events section of the Handling User Input and Other Events chapter of the GLG Programming Reference Manual for more information.

The SCADAViewer directory of the GLG installation provides coding examples of using various callbacks. Many simpler demos and coding examples are also provided.

GlgInputCallback

typedef void(* GlgInputCallback) (GlgObject viewport, GlgAnyType client_data, GlgObject message_object)

An Input callback is used to handle user interaction with input objects, as well as to perform object selection and action processing.

It is installed via GlgAddCallback.

Parameters

viewport	The viewport the callback is attached to.
client_data	The client data specified when the callback was installed.
message_object	The message object containing information about the event or action that triggered the callback.

See the Appendix B: Message Object Resources section of the Appendices chapter of the GLG Programming Reference Manual for a description of data contained in the message object.

The example below demonstrates a very simple input callback which terminates the application when a Quit button is pressed. The example demonstrates how to handle the default input object events, as well as an attached command actions.

void InputCallback( GlgObject viewport, GlgAnyType client_data, GlgObject message_object )
{
   char
       origin; // Name of the input object.
       format; // Message type
       action, // Reason the callback was invoked.
       command_type; // Command to be executed for <i>Command</i> action types.
 
   // Query message format.
   GlgGetSResource( message_object, "Format", &format );
 
   // Handle default input object events.
   if( strcmp( format, "Button" ) == 0 ) // A message from a push button.
   {
      // Query action that triggered the callback.
      GlgGetSResource( message_object, "Action", &action );
 
      // Query the name of the button input object that triggered the callback.
      GlgGetSResource( message_object, "Origin", &origin );
 
      // Check is the button was pressed (<i>Activate</i> action) and the button name was "Quit".
      if( strcmp( action, "Activate" ) == 0 && strcmp( origin, "Quit" ) == 0 )
        exit( 0 );
   }
   // Handle command actions attached to a button or an object.
   else if( strcmp( format, "Command" ) == 0 )   // <i>Command</i> action was triggered.
   {
      // Query command type.
      GlgGetSResource( message_object, "ActionObject/Command/CommandType", &command_type );
 
      // Act based on the command type.
      if( strcmp( command_type, "Quit" ) == 0 )
        exit( 0 );
   }
}

The DEMOS/RealTime_StripChart/stripchart.c file in the GLG installation directory provides an elaborate example of using the Input callback. Other GLG Demos and Examples also provide coding examples of using the callback.

GlgSelectCallback

typedef void(* GlgSelectCallback) (GlgObject viewport, GlgAnyType client_data, char **name_array)

A simplified selection callback used to process name-based object selection, installed via GlgAddCallback.

The Select callback provides a simplified name-based interface to handle object selection and is invoked when the user selects objects in the drawing with a mouse click.

An Input callback provides a more elaborate alternative for handling selection events using either object IDs or selection commands attached to objects in the Graphics Builder as Actions. The Input callback doesn't depend on object names and can handle unnamed objects.

An Action attached to an object provides the most effective way to handle object selection. An Input callback is used to process selection triggered by the Action objects.

GlgGetSelectionButton may be used inside the Select callback to query the mouse button that triggered the callback.

Parameters

viewport	The viewport the callback is attached to.
client_data	The client data specified when the callback was installed.
name_array	A NULL-terminated list of names of all named objects selected with the mouse, or NULL if no objects were selected. The pointer to the list as well as pointers to the individual strings point to internal data structures which should not be modified.

The name array is a NULL-terminated list of pointers to strings, each of which represents the complete resource path name of one object selected by the mouse click. If more than one object is selected, the list will contain several strings. Both the selected objects at the bottom of the hierarchy and all their named ancestors will be included.

Objects in the array are listed in the reversed order compared to their drawing order, so that the objects that are at the bottom of the drawing list and are drawn on top of other objects will be listed first in the array.

Since each name string is a complete resource path name (relative to viewport), it can be used to access resources of the object:

// Erase the object when it is clicked on.
char * visiblity_res_name = GlgConcatStrings( selected_name, "/Visibility" );
GlgSetDResource( viewport, visiblity_res_name, 0. );
GlgFree( visiblity_res_name );

The DEMOS/process_demo/processG.c file in the GLG installation directory provides an example of using the Select callback.

GlgTraceCallback

typedef void(* GlgTraceCallback) (GlgObject viewport, GlgAnyType client_data, GlgTraceCBStruct *trace_info)

A Trace callback used to handle native windowing events, installed via GlgAddCallback.

Parameters

viewport	The viewport the callback is attached to.
client_data	The client data specified when the callback was installed.
trace_info	The GlgTraceCBStruct structure containing information about the native windowing event that triggered the callback. See GlgTraceCBStruct for more information.

The trace callback is used as an escape mechanism to provide a low-level access to native windowing events. It is invoked whenever a viewport receives a native windowing event and passes the event to the application code for processing. If a viewport object has a trace callback attached, the trace callback will be invoked for all events received by the viewport and all of its child viewports.

There are two trace callbacks: the Trace callback is invoked before the event is dispatched for processing, and the Trace2 callback is invoked after the event has been processed. If the same function is used to handle both callbacks, the reason field of the GlgTraceCBStruct structure received as the trace_info parameter can be used to find which callback is invoked, GLG_TRACE_CB or GLG_TRACE2_CB.

The DEMOS/airtraffic/airtraffic.c file in the GLG installation directory provides an elaborate example of using the Trace callback.