User Interaction and Selection

This group contains methods for handling object selection and other user interaction with the GLG drawing. More...

Detailed Description

This group contains methods for handling object selection and other user interaction with the GLG drawing.

These methods can be used inside Input and Trace callbacks to implement custom user interaction and selection logic.

Modules
	Chart Selection

Functions
void	EnableCallback (GlgCallbackType callback_type, GlgObject callback_viewport=NULL)
	Enables Input, Select, Trace and Hierarchy callbacks of this object. More...
virtual void	Hierarchy (GlgObjectC &callback_viewport, GlgHierarchyCBStruct *hierarchy_info)
	A Hierarchy callback is used to get access to the drawing to be displayed in the SubWindow and SubDrawing objects before the drawing is displayed. More...
virtual void	Input (GlgObjectC &callback_viewport, GlgObjectC &message_object)
	An Input callback is used to handle user interaction with input objects, as well as object selection and action processing. More...
virtual void	Select (GlgObjectC &callback_viewport, char **name_array)
	A simplified selection callback is used to process object selection using object names. More...
GlgAnyType	SendMessage (char *resource_path, char *message, GlgAnyType param1=NULL, GlgAnyType param2=NULL, GlgAnyType param3=NULL, GlgAnyType param4=NULL)
	Sends a message to an object to request some action to be performed. More...
virtual void	Trace (GlgObjectC &callback_viewport, GlgTraceCBStruct *trace_info)
	A Trace callback is used to handle native windowing events. More...
virtual void	Trace2 (GlgObjectC &callback_viewport, GlgTraceCBStruct *trace_info)
	A Trace2 callback is used to handle native windowing events. More...

Function Documentation

EnableCallback()

void EnableCallback	(	GlgCallbackType	callback_type,
		GlgObject	callback_viewport = NULL
	)

Enables Input, Select, Trace and Hierarchy callbacks of this object.

Parameters

callback_type	Specifies the type of a callback to be added: GLG_INPUT_CB - adds Input callback GLG_SELECT_CB - adds Select callback GLG_TRACE_CB - adds Trace callback GLG_TRACE2_CB - adds Trace2 callback GLG_HIERARCHY_CB - adds Hierarchy callback.
callback_viewport	If not NULL, specifies the child viewport of this object to add the callbacks to. If NULL, the callbacks will be added to this viewport.

This method enables the specified callback of a viewport object. The GlgObjectC class provides several callbacks that are invoked by the GLG Toolkit upon various actions. An application can subclass the GlgObjectC class to provide custom implementation of the callbacks that overrides the callbacks of the base class.

The following callbacks are provided:

• Input callback is invoked when an input widgets, such as a slider or a toggle, receives some user input. It is also invoked when an object in the viewport is selected.
• Select callback is invoked when a user selects an object in the widget's drawing area.
• Trace callback is invoked for every native windowing system event received by the viewport or its child viewports and may be used to handle these events.
• Hierarchy callback may be used to initialize loaded subdrawings.

See Input, Select, Trace and Hierarchy callbacks for the description of the available callback types.

Only one callback of each callback type may be added to an individual viewport. Any subsequent invocations of this method with the same callback type will overwrite the previous value of the viewport's callback.

Note: Callbacks must be enabled before the drawing's hierarchy is set up.

Several callbacks of the same type may be added to different viewports on different levels of the drawing hierarchy. However, only the first encountered callback on the lowest level of the hierarchy will be called. For example, if an input callback is attached to a viewport and its child viewport, only the child viewport's callback will be invoked when input event occurs in the child viewport.

The viewport's ProcessMouse attribute controls processing of the mouse selection events and tooltips inside the viewport and its child viewports.

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

Hierarchy()

virtual void Hierarchy ( GlgObjectC &  callback_viewport, GlgHierarchyCBStruct *  hierarchy_info  )

virtual

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

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

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 is 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 to 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 is set up, when the drawing is set up but before it is drawn, as well as before and after the drawing is reset. The condition field of the hierarchy_info structure provides information on when the callback is invoked.

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

Parameters

callback_viewport	The viewport the callback is attached to.
hierarchy_info	The structure containing information about the subdrawing triggered the callback. See GlgHierarchyCBStruct for more information.

Reimplemented in GlgWrapperC.

Input()

virtual void Input ( GlgObjectC &  callback_viewport, GlgObjectC &  message_object  )

virtual

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

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Parameters

callback_viewport	The viewport the callback is attached to.
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 and process attached command actions.

void GlgExample::Input( GlgObjectC& callback_viewport, GlgObjectC& message_object )
{
   const 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.
   message_object.GetSResource( "Format", &format );
 
   // Handle default input object events.
   if( strcmp( format, "Button" ) == 0 ) // A message from a push button.
   {
      // Query the action that triggered the callback.
      message_object.GetSResource( "Action", &action );
 
      // Query the name of the button input object that triggered the callback.
      message_object.GetSResource( "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.
      message_object.GetSResource( "ActionObject/Command/CommandType", &command_type );
 
      // Act based on the command type.
      if( strcmp( command_type, "Quit" ) == 0 )
        exit( 0 );
   }
}

The examples_c_cpp/RealTimeChart_cpp/GlgChart.cpp 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.

Reimplemented in GlgWrapperC.

Select()

virtual void Select ( GlgObjectC &  callback_viewport, char **  name_array  )

virtual

A simplified selection callback is used to process object selection using object names.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Select callback uses object names to handle selection. A more versatile Input callback may be used to handle object selection using object IDs, which will also handle unnamed objects.

Alternatively, 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

callback_viewport	The viewport the callback is attached to.
name_array	A NULL-terminated list of names of all named selected objects.

The name array contains names of all objects that overlap with the given rectangle completely or partially. Both the selected objects at the bottom of the hierarchy and all their named parents 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.

The name string is a complete resource path name (relative to viewport) which can be used to access resources of the object:

// Erase the object when it is clicked on.    
char * visiblity_res_name = GlgConcatStrings( path_name, "/Visibility" );
callback_viewport.SetDResource( visiblity_res_name, 0. );
GlgFree( visiblity_res_name );

The examples_c_cpp/animation/GlgAnimationG.cpp file in the GLG installation directory provides an example of using the Select callback.

Reimplemented in GlgWrapperC.

SendMessage()

GlgAnyType SendMessage	(	char *	resource_path,
		char *	message,
		GlgAnyType	param1 = NULL,
		GlgAnyType	param2 = NULL,
		GlgAnyType	param3 = NULL,
		GlgAnyType	param4 = NULL
	)

Sends a message to an object to request some action to be performed.

This is a wrapper for GlgSendMessage.

Parameters

resource_path	If NULL, the message is sent to this object, otherwise the message is sent to the object's child specified by the resource path. The resource path is relative to this object. For example, to send the message to a viewport's handler, invoke the viewport's SendMessage with "Handler" as the resource_path parameter.
message	A string defining the type of the message.
param1	Message type dependent.
param2	Message type dependent.
param3	Message type dependent.
param4	Message type dependent.

Returns

The query result of messages that execute some query, is ignored otherwise.

This method is used to send a message to an input object with a request to execute some action. For example, a program can send an "Activate" message to a push button widget to simulate a user click, which will activate any click processing Action objects attached to the button. "Set" and "Reset" messages may be sent to a toggle button widget to change its value, which will also process any Action objects attached to the toggle.

The method also serves as an escape mechanism for actions that can not be easily accomplished by setting or querying a single resource, such us adding items to a list widget or querying a state of a multiple-selection list.

Refer to the Input Objects chapter of the of the GLG User's Guide and Builder Reference Manual for the description of the method's parameters and returned value for each of the GLG input handlers.

Some messages return an object that is is owned by the called and should be dereferenced. If the returned object is assigned to a GlgObjectC instance, use the instance's Drop method to dereference it.

Trace()

virtual void Trace ( GlgObjectC &  callback_viewport, GlgTraceCBStruct *  trace_info  )

virtual

A Trace callback is used to handle native windowing events.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

Parameters

callback_viewport	The viewport the callback is attached to.
trace_info	The 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 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 method is used to handle both callbacks, the reason field of the trace_info structure can be used to find which callback is invoked, GLG_TRACE_CB or GLG_TRACE2_CB.

The examples_c_cpp/GIS_cpp/GlgMapViewer.cpp file in the GLG installation directory provides an elaborate example of using the Trace callback.

Reimplemented in GlgWrapperC.

Trace2()

virtual void Trace2 ( GlgObjectC &  callback_viewport, GlgTraceCBStruct *  trace_info  )

virtual

A Trace2 callback is used to handle native windowing events.

It is a virtual callback method to be overridden by a derived class and is enabled via EnableCallback.

The Trace2 callback is similar to Trace, but is invoked after the event has been processed. See Trace for more information.

Parameters

callback_viewport	The viewport the callback is attached to.
trace_info	The structure containing information about the native windowing event that triggered the callback. See GlgTraceCBStruct for more information.

Reimplemented in GlgWrapperC.