User Interaction and Selection

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

Detailed Description

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

These functions (other than GlgAddCallback) can be used inside Input and Trace callbacks to implement custom user interaction and selection logic.

Modules
	Chart Selection

Functions
void	GlgAddCallback (GlgObject viewport, GlgCallbackType type, GlgCallbackProc callback, GlgAnyType client_data)
	Adds a callback function to a viewport. More...
GlgObject	GlgCreateSelectionMessage (GlgObject top_vp, GlgRectangle *rectangle, GlgObject selected_vp, GlgSelectionEventType selection_type, GlgLong button)
	Searches for an Action object that would be activated by the user interaction event. More...
GlgObject	GlgCreateSelectionNames (GlgObject top_vp, GlgRectangle *rectangle, GlgObject selected_vp)
	Returns a list of names of objects intersecting a given rectangle. More...
GlgBoolean	GlgGetModifierState (GlgModifierType modifier)
	Provides a cross-platform way to query the state of the Control and Shift keys, as well as the type of the mouse click: a single or double click. More...
GlgLong	GlgGetSelectionButton (void)
	Queries the mouse button that initiated the callback. More...
GlgAnyType	GlgSendMessage (GlgObject object, char *resource_name, char *message, GlgAnyType param1, GlgAnyType param2, GlgAnyType param3, GlgAnyType param4)
	Sends a message to an object to request some action to be performed. More...
void	GlgSetFocus (GlgObject object, char *resource_name)
	Sets the keyboard focus to an object's viewport. More...
GlgTooltipFormatter	GlgSetTooltipFormatter (GlgTooltipFormatter formatter)
	Supplies a custom tooltip formatter. More...
void	GlgStopButtonRepeat (void)
	Stops the button repeat in progress, if any. More...

Function Documentation

GlgAddCallback()

void GlgAddCallback	(	GlgObject	viewport,
		GlgCallbackType	type,
		GlgCallbackProc	callback,
		GlgAnyType	client_data
	)

Adds a callback function to a viewport.

Parameters

viewport	Specifies the viewport the callback will be added to. For the GLG_INPUT_CB callbacks, it may also be a light viewport.
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	Specifies a callback function to be called.
client_data	Specifies client data to be passed to the callback function when it is called.

This function adds the specified callback to a viewport. A callback is a user-supplied function that is called by the GLG Toolkit upon some action:

• 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 GlgInputCallback, GlgSelectCallback, GlgTraceCallback and GlgHierarchyCallback 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 function with the same callback type will overwrite the previous value of the viewport's callback. To remove a callback, call GlgAddCallback with NULL as a value of the callback parameter.

Note: Callbacks must be added 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.

The GLG Wrapper Widgets also provide functions for adding callbacks to the drawings used by each widget.

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

GlgCreateSelectionMessage()

GlgObject GlgCreateSelectionMessage	(	GlgObject	top_vp,
		GlgRectangle *	rectangle,
		GlgObject	selected_vp,
		GlgSelectionEventType	selection_type,
		GlgLong	button
	)

Searches for an Action object that would be activated by the user interaction event.

This function provides a low-level API for searching all objects inside the given rectangle for an action with the specified selection trigger type attached to an object and returning a selection message for the first found action attached to the object.

It may be used inside the Trace callback to determine whether a mouse event was meant to trigger an action attached to a graphical object in a drawing.

Parameters

top_vp	The top viewport or light viewport of the selection query (must be an ancestor of selected_vp or the same as selected_vp). It may be either a viewport or a light viewport.
rectangle	The bounding rectangle in screen coordinates of the selected_vp viewport. All graphical shapes whose rendering intersects this rectangle, including shapes in the top_vp viewport, are included in the selection list.
selected_vp	The viewport relatively to which the bounding rectangle is defined. When used with the mouse events, this is the viewport in which the mouse event occurred. If a light viewport is supplied, its parent viewport will be used.
selection_type	Specifies the selection type: GLG_MOVE_SELECTION selects based on a custom mouse move events GLG_CLICK_SELECTION selects based on a mouse click events GLG_TOOLTIP_SELECTION selects the tooltip based on the mouse move events
button	The mouse button (1, 2 or 3) for the GLG_CLICK_SELECTION selection type.

Returns

A message equivalent to the message received in the input callback when the event specified by the selection_type occurs in the specified rectangular area, or NULL if no matching actions were found.

GlgCreateSelectionNames()

GlgObject GlgCreateSelectionNames	(	GlgObject	top_vp,
		GlgRectangle *	rectangle,
		GlgObject	selected_vp
	)

Returns a list of names of objects intersecting a given rectangle.

This function provides a low-level API to determine whether a mouse event was meant to select graphical objects in a drawing, and may be used inside the Trace callback to implement custom handling of mouse events.

Action objects attached to objects in the drawing provide a higher level interface for custom object selection processing.

A more powerful GlgCreateSelection function of the Intermediate API returns object IDs of the selected objects and may be used to handle unnamed objects.

Parameters

top_vp	The top viewport or light viewport of the selection query (must be an ancestor of selected_vp or the same as selected_vp). It may be either a viewport or a light viewport.
rectangle	The bounding rectangle in screen coordinates of the selected_vp viewport. All graphical shapes whose rendering intersects this rectangle, including shapes in the top_vp viewport, are included in the selection list.
selected_vp	The viewport relatively to which the bounding rectangle is defined. When used with the mouse events, this is the viewport in which the mouse event occurred. If a light viewport is supplied, its parent viewport will be used.

Returns

An array of strings containing selected object names, or NULL if no named objects were selected. The returned array must be dereferenced with GlgDropObject when done.

The function returns an array of strings containing 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.

Each returned name string is a complete resource path name (relative to top_vp) which can be used get the object ID of the object:

GlgObject selected_object = GlgGetResourceObject( top_vp, path_name );

GlgGetModifierState()

GlgBoolean GlgGetModifierState

(

GlgModifierType

modifier

)

Provides a cross-platform way to query the state of the Control and Shift keys, as well as the type of the mouse click: a single or double click.

Parameters

modifier

Specifies the modifier state to query.

Returns

True if the modifier is active, False otherwise.

GlgGetSelectionButton()

GlgLong GlgGetSelectionButton

(

void

)

Queries the mouse button that initiated the callback.

Returns

1, 2, or 3 to indicate which button caused the callback to be invoked.

The function may be used only inside callback functions that are activated on a mouse click, otherwise the return value is undefined.

GlgSendMessage()

GlgAnyType GlgSendMessage	(	GlgObject	object,
		char *	resource_name,
		char *	message,
		GlgAnyType	param1,
		GlgAnyType	param2,
		GlgAnyType	param3,
		GlgAnyType	param4
	)

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

Parameters

object	Specifies an object to send the message to. In most cases, it is a viewport with a GLG input handler attached, such as a button or a slider.
resource_name	Specifies the resource name of a child object to send the message to, or NULL to send the message to the object specified by the object parameter. The resource path is relative to the object parameter. For example, to send the message to a viewport's handler, use the viewport as the object parameter and "Handler" as the resource_name parameter.
message	A string that defines the message type.
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 function 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 function 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 function's parameters and returned value for each of the GLG input handlers.

GlgSetFocus()

void GlgSetFocus	(	GlgObject	object,
		char *	resource_name
	)

Sets the keyboard focus to an object's viewport.

If the target object is a viewport, the focus is set to this viewport, otherwise the focus is set to the target object's parent viewport.

Parameters

object	An object used to determine the target viewport.
resource_name	The resource path of a child object to use, or NULL to use the object specified by the object parameter. The resource path is relative to the object specified by the object parameter.

GlgSetTooltipFormatter()

GlgTooltipFormatter GlgSetTooltipFormatter

(

GlgTooltipFormatter

formatter

)

Supplies a custom tooltip formatter.

A custom tooltip formatter may be used to supply custom context-sensitive tooltip strings by querying an object's properties and displaying them in the tooltip.

See GlgTooltipFormatter for more.

Parameters

formatter

Specifies a custom tooltip formatter.

Returns

The previously set formatter, if any, NULL otherwise.

GlgStopButtonRepeat()

void GlgStopButtonRepeat

(

void

)

Stops the button repeat in progress, if any.