Callbacks

Detailed Description

This group contains callbacks that can be installed to handle user interaction, custom formatting, as well as platform-independent timers and work procedures.

Include file: GlgApi.h

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 void(*	GlgHierarchyCallback) (GlgObject viewport, GlgAnyType client_data, GlgHierarchyCBStruct *hierarchy_info)
	A Hierarchy callback used to get access to the drawing to be displayed in the SubWindow and SubDrawing objects before the drawing is displayed, installed via GlgAddCallback. More...
typedef void(*	GlgCustomSetupHandler) (GlgObject object, GlgCustomSetupType type)
	A custom setup handler installed via GlgSetCustomSetupHandler. More...
typedef GlgBoolean(*	GlgWorkProc) (GlgAnyType client_data)
	A platform-independent work procedure callback installed via GlgAddWorkProc. More...
typedef void(*	GlgTimerProc) (GlgAnyType client_data, GlgIntervalID *timer_id)
	A platform-independent timer callback installed via GlgAddTimeOut. More...
typedef void(*	GlgErrorHandler) (char *message, GlgErrorType error_type)
	A custom error handler installed via GlgSetErrorHandler. More...
typedef void(*	GlgHandler) (GlgCallEvent *call_event)
	A function that implements a custom interaction handler. More...
typedef GlgLong(*	GlgChartFilter) (GlgChartFilterCBReason reason, GlgChartFilterData *filter_data, void *client_data)
	A custom chart filter callback installed via GlgSetChartFilter. More...
typedef char *(*	GlgLabelFormatter) (GlgObject axis, GlgLabelType label_type, GlgValueType value_type, double value, time_t sec, double fractional_sec, void *reserved)
	A label formatter used to supply custom labels for chart axes and installed via GlgSetLabelFormatter. More...
typedef char *(*	GlgTooltipFormatter) (GlgObject viewport, GlgObject object, GlgObject tooltip_obj, GlgLong root_x, GlgLong root_y)
	A tooltip formatter used to supply custom tooltip strings and installed via GlgSetTooltipFormatter. More...
typedef void(*	GlgAlarmHandler) (GlgObject data_obj, GlgObject alarm_obj, char *alarm_label, char *action, char *subaction, GlgAnyType reserved)
	An alarm handler used to handle alarms attached to the GLG objects in the drawing and installed via GlgSetAlarmHandler. More...
typedef char *(*	GlgGetURLCallback) (char *request, void *reserved)
	A custom callback used to fetch data from URLs, installed via GlgSetGetURLCallback. More...

Typedef Documentation

GlgAlarmHandler

typedef void(* GlgAlarmHandler) (GlgObject data_obj, GlgObject alarm_obj, char *alarm_label, char *action, char *subaction, GlgAnyType reserved)

An alarm handler used to handle alarms attached to the GLG objects in the drawing and installed via GlgSetAlarmHandler.

Alarms are generated by the Alarm objects attached to objects in the drawing and activated when their controlled values go outside the ranges specified in the Alarm objects.

This application-supplied method is invoked to implement custom alarm processing when an alarm occurs.

Parameters

data_obj	The data object the alarm is attached to and whose value has changed.
alarm_obj	The alarm object attached to the data object to monitor its value. It is the alarm that generated the alarm message.
alarm_label	The value of the alarm's AlarmLabel attribute used to identify alarm object.
action	The value of the alarm's AlarmAction attribute, provides details about the condition that caused the alarm.
subaction	The value of the alarm's AlarmSubaction attribute, provides details about the condition that caused the alarm.
reserved	This parameter is reserved for future implementations.

An alarm handler should not change object hierarchy by actions such as adding or deleting objects from the drawing or changing a factor of a series object.

Refer to the Alarm Object section of the GLG User's Guide and Builder Reference Manual for more information.

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.

GlgChartFilter

typedef GlgLong(* GlgChartFilter) (GlgChartFilterCBReason reason, GlgChartFilterData *filter_data, void *client_data)

A custom chart filter callback installed via GlgSetChartFilter.

This function is invoked by a chart to aggregate the plot's data to display a smaller number of data samples.

Parameters

reason	The reason the filter is invoked.
filter_data	Contains data passed to the filter by the chart.
client_data	Contains client data passed to the filter by the application when the filter was attached.

Returns

Return value that is interpreted differently depending on the reason parameter.

The src subdirectory of the GLG installation contains source code of custom filter examples for various programming environments (CustomChartFilter.c, CustomChartFilter.java and CustomChartFilter.cs) that provide extensive self-documented examples of custom filters.

Each example implements several types of custom filters (MIN_MAX, AVERAGE and DISCARD), and contains detailed explanation of all possible values of the reason parameter, as well as the fields of the filter_data structure.

GlgCustomSetupHandler

typedef void(* GlgCustomSetupHandler) (GlgObject object, GlgCustomSetupType type)

A custom setup handler installed via GlgSetCustomSetupHandler.

This method implements custom object processing logic and is invoked for objects tagged using the CustomSetup flag in the GLG drawing.

The custom setup may be used to automate object data tags assignment based on the object ID, or to attach Input and Trace callbacks to objects representing custom widgets that handle user interaction.

The GlgViewer.c and HMIPage.c files in the DEMOS/SCADAViewer directory of GLG installation provide an elaborate example of an application framework that uses a custom setup handler to process special custom widgets.

Parameters

object	A tagged object to be processed.
type	Indicates when the method is invoked: GLG_BEFORE_HI_SETUP - before hierarchy setup. GLG_AFTER_HI_SETUP - after hierarchy setup. GLG_FINISHED_SETUP - after finishing object setup, when all transformed values are valid. GLG_BEFORE_RESET_SETUP - before an object's reset. GLG_AFTER_RESET_SETUP - after an object's reset.

GlgErrorHandler

typedef void(* GlgErrorHandler) (char *message, GlgErrorType error_type)

A custom error handler installed via GlgSetErrorHandler.

This function is invoked with a diagnostic message when an error occurs and may be used to implement custom error handling.

Parameters

message	Error description
error_type	Specifies an error type.

A custom error handler may be used to suppress some messages, while still using the default error handler to process the rest of the error messages.

The default error handler is returned by the GlgSetErrorHandler function that was used to install a custom error handler. A custom error handler can invoke the default error handler for error messages that don't require custom processing.

GlgGetURLCallback

typedef char*(* GlgGetURLCallback) (char *request, void *reserved)

A custom callback used to fetch data from URLs, installed via GlgSetGetURLCallback.

URLs may be used to load drawing files from remote servers, as well as to use map server installed at a remote web server.

Parameters

request	URL string to fetch data from, or NULL if the callback is invoked to delete the last fetched temporary file.
reserved	This parameter is reserved for future implementations.

Returns

Temporary file name containing the fetched data or NULL to indicate that fetching failed. NULL should also be returned if the callback is invoked with NULL request to delete the previously fetched temporary file.

A custom callback implementation on Linux should delete a temporary file containing the previously fetched URL when it is invoked to fetch the next URL. When GlgTerminate is invoked, the callback will be invoked with NULL request to clean up the last used temporary file.

A default GlgGetURLCB callback is provided as a part of the GLG API library and is activated by default for the GLG editors on all platforms, as well as for the GLG C API runtime on Windows. GlgSetGetURLCallback may be used activate the default callback for the GLG C API runtime on Linux:

GlgSetGetURLCallback( GlgGetURLCB );

To use the default callback on Linux, the GLG_WGET_PATH environment variable should be set and contain the path to the wget command that will be used for fetching URLs.

GlgHandler

typedef void(* GlgHandler) (GlgCallEvent *call_event)

A function that implements a custom interaction handler.

Parameters

call_event

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

This function is invoked to handle user interaction of the viewport the handler is attached to. The code of this function implements functionality of the handler.

See Interaction Handler for more information.

GlgHierarchyCallback

typedef void(* GlgHierarchyCallback) (GlgObject viewport, GlgAnyType client_data, GlgHierarchyCBStruct *hierarchy_info)

A Hierarchy callback used to get access to the drawing to be displayed in the SubWindow and SubDrawing objects before the drawing is displayed, installed via GlgAddCallback.

SubWindow objects may be used to switch drawings displayed in them, and an application may want to install a separate Input callback for each loaded drawing to handle user interaction instead of having one giant Input callback that handles input events from all drawings. An Input callback has to be added to the viewport of a drawing displayed in the subwindow before the drawing has been set up and drawn. The Hierarchy callback is invoked with the ID of the subwindow's drawing after it has been loaded but before its hierarchy has been set up, making it possible to add Input callbacks as well as initialize the drawing with data before it is painted on the screen.

The Hierarchy callback can also be used to set up data tags defined in a SubDrawing object when an instance of the subdrawing is created.

The Hierarchy callback may be added to the top level viewport or any of its children viewports. If any of a subwindow's (or subdrawing's) parent viewports has a hierarchy callback added, the callback of the closest parent viewport will be invoked each time a subwindow loads a new drawing or a subdrawing loads its template.

The hierarchy callback is invoked multiple times for each template drawing: when the drawing is loaded but before it has been set up, when the drawing has been set up but before it has been drawn for the first time, as well as before and after the drawing has been reset. The condition field of the GlgHierarchyCBStruct structure received as the hierarchy_info provides information on when the callback is invoked.

The DEMOS/SCADAViewer/GlgViewer.c file in the GLG installation directory provides an elaborate example of using the Hierarchy callback.

Parameters

viewport	The viewport the callback is attached to.
client_data	The client data specified when the callback was installed.
hierarchy_info	The structure containing information about the subdrawing that triggered the callback. See GlgHierarchyCBStruct for more information.

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.

GlgLabelFormatter

typedef char*(* GlgLabelFormatter) (GlgObject axis, GlgLabelType label_type, GlgValueType value_type, double value, time_t sec, double fractional_sec, void *reserved)

A label formatter used to supply custom labels for chart axes and installed via GlgSetLabelFormatter.

This function is invoked every time a new label string needs to be generated. It can create and return a label string, or return NULL to use a default label string.

When the created label string is no longer needed, it will be freed by the Toolkit using GlgFree. Therefore, it must be allocated using GlgAlloc or one of the GLG string utility functions, such as GlgStrClone or GlgConcatStrings.

Parameters

axis	The label's axis object.
label_type	The type of the label: GLG_TICK_LABEL_TYPE or GLG_SELECTION_LABEL_TYPE.
value_type	The type of the axis' value: GLG_NUMERICAL_VALUE or GLG_TIME_VALUE.
value	The value corresponding to the label position.
sec	An integer number of seconds since the Epoch corresponding to the label position for GLG_TIME_VALUE axes.
fractional_sec	The fractional number of seconds for GLG_TIME_VALUE axes.
reserved	This parameter is reserved for future implementations.

Returns

An allocated custom label string that can be freed with GlgFree, or NULL to use the default label format.

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.

GlgTimerProc

typedef void(* GlgTimerProc) (GlgAnyType client_data, GlgIntervalID *timer_id)

A platform-independent timer callback installed via GlgAddTimeOut.

Parameters

client_data	The client data supplied when the timer was added.
timer_id	A pointer to the timer id.

GlgTooltipFormatter

typedef char*(* GlgTooltipFormatter) (GlgObject viewport, GlgObject object, GlgObject tooltip_obj, GlgLong root_x, GlgLong root_y)

A tooltip formatter used to supply custom tooltip strings and installed via GlgSetTooltipFormatter.

This function is invoked every time a new tooltip string needs to be generated. It can query an object's properties and use them to generate a returned tooltip string.

If the GlgTooltipFormatterOnErase global configuration resource is set to 1, the method will also be invoked with NULL parameters when the tooltip is erased.

When the tooltip string is no longer needed, it will be freed by the Toolkit using GlgFree. Therefore, it must be allocated using GlgAlloc or one of the GLG string utility functions, such as GlgStrClone or GlgConcatStrings.

Parameters

viewport	The viewport object for which tooltips are enabled via the ProcessMouse property.
object	The object that owns the TooltipString resource.
tooltip_obj	The TooltipString object (S data object).
root_x	The x coordinate of the cursor. In the GTK environment, the coordinate is relative to the top level frame window containing the viewport. In all other environment, it is relative to the device screen.
root_y	The y coordinate of the cursor. In the GTK environment, the coordinate is relative to the top level frame window containing the viewport. In all other environment, it is relative to the device screen.

Returns

An allocated string that can be freed with GlgFree:

• non-NULL string to display it in the tooltip
• NULL to use the default tooltip
• an empty string to disable displaying the tooltip.

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.

GlgWorkProc

typedef GlgBoolean(* GlgWorkProc) (GlgAnyType client_data)

A platform-independent work procedure callback installed via GlgAddWorkProc.

Parameters

client_data

The client data supplied when the work procedure was added.

Returns

• If work procedure callback returns True, it is removed and will not be called again.
• If it returns False, it will be called continuously until the application calls the GlgRemoveWorkProc function.

A work procedure must return quickly to avoid response time delays.