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 (other than AddListener) can be used inside Input and Trace listeners to implement custom user interaction and selection logic.

Functions
void	AddListener (GlgCallbackType type, Function callback)
	Adds a GLG event listener to the viewport. More...
static GlgObject	CreateSelectionMessage (GlgObject top_vp, GlgCube rectangle, GlgObject selected_vp, GlgSelectionEventType selection_type, int button)
	Searches for an Action object that would be activated by the user interaction event. More...
static GlgObject	CreateSelectionNames (GlgObject top_vp, GlgCube rectangle, GlgObject selected_vp)
	Returns a list of names of objects intersecting a given rectangle. More...
static GlgObject	CreateSelectionNamesFromEvent (int x, int y, int delta, GlgObject top_vp, GlgObject selected_vp)
	Returns a list of names of objects located under the mouse. More...
static GlgObject	GetSelectedPlot ()
	Returns the plot object corresponding to the last legend item selected with the mouse, if any. More...
Object	SendMessageToObject (String resource_name, String message, Object param1, Object param2, Object param3, Object param4)
	Sends a message to the object to request some action to be performed. More...
static GlgTooltipFormatter	SetTooltipFormatter (GlgTooltipFormatter formatter)
	Supplies a custom tooltip formatter. More...

Function Documentation

AddListener()

void AddListener	(	GlgCallbackType	type,
		Function	callback
	)

Adds a GLG event listener to the viewport.

An Input listener can also be added to the light viewport.

Parameters

type	Specifies the type of a listener to be added: INPUT_CB - adds Input listener SELECT_CB - adds Select listener TRACE_CB - adds Trace listener TRACE2_CB - adds Trace2 listener HIERARCHY_CB - adds Hierarchy listener.
callback	Specifies a callback function to be invoked to process GLG events. The function's type signature must match the type signature of the listener's single entry point (InputCallback for the GlgInputListener, TraceCallback for the GlgTraceListener, etc.).

This method adds the specified callback to the 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 widget, 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 GlgInputListener, GlgSelectListener, GlgTraceListener and GlgHierarchyListener for the description of the available listener types.

Only one callback of each callback type may be added to an individual viewport. Any subsequent invocations of AddListener with the same callback type will overwrite the previous value of the viewport's callback. To remove a callback, call AddListener 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.

If an event occurs in a child viewport that doesn't have a callback attached, the callback of the first encountered parent viewport that has the callback attached will be invoked.

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.

CreateSelectionMessage()

static GlgObject CreateSelectionMessage ( GlgObject  top_vp, GlgCube  rectangle, GlgObject  selected_vp, GlgSelectionEventType  selection_type, int  button  )

static

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

This method 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.

The method may be used inside the GlgTraceListener's TraceCallback method 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: MOVE_SELECTION selects based on a custom mouse move events CLICK_SELECTION selects based on a mouse click events TOOLTIP_SELECTION selects the tooltip based on the mouse move events
button	The mouse button (1, 2 or 3) for the 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.

CreateSelectionNames()

static GlgObject CreateSelectionNames ( GlgObject  top_vp, GlgCube  rectangle, GlgObject  selected_vp  )

static

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

This method 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 GlgTraceListener's TraceCallback method to implement custom handling of mouse events.

See also CreateSelectionNamesFromEvent that creates selection names from an event.

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

A more powerful CreateSelection method 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 method 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:

let selected_object = top_vp.GetResourceObject( path_name );

CreateSelectionNamesFromEvent()

static GlgObject CreateSelectionNamesFromEvent ( int  x, int  y, int  delta, GlgObject  top_vp, GlgObject  selected_vp  )

static

Returns a list of names of objects located under the mouse.

This method 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 GlgTraceListener's TraceCallback method to implement custom handling of mouse events.

See also CreateSelectionNames that creates selection names for the specified area.

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

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

Parameters

x	X coordinate of the event (relative to the selected_vp).
y	Y coordinate of the event (relative to the selected_vp).
delta	Specifies the radius of the area around the cursor position that will be used to select objects. All graphical shapes whose rendering intersects this area, including shapes in the top_vp viewport, are included in the selection list.
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.
selected_vp	The viewport in which the mouse event occurred. The X and Y coordinates are defined relatively to this viewport's area. 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.

Follow this link for information on using the returned array.

GetSelectedPlot()

static GlgObject GetSelectedPlot ( )

static

Returns the plot object corresponding to the last legend item selected with the mouse, if any.

Returns

Selected plot object or null if no plots were selected.

The setting of the chart's viewport ProcessMouse attribute controls when legend selection happens:

• NO_MOUSE_EVENTS disables legend selection.
• for MOUSE_CLICK, a plot is selected when a legend items is clicked on, and the selected plot is stored until it is replaced by a new selection.
• for MOUSE_OVER_SELECTION, a plot is selected when a mouse moves over a legend item, and the selected plot is reset when the mouse moves away from the item.
• for MOUSE_OVER_TOOLTIP, a plot is selected when a mouse is hovering over a legend item, and the selected plot is stored until it is replaced by a new selection.
• for a combination of MOUSE_CLICK and MOUSE_OVER_SELECTION, the selection will happen on both mouse click and mouse over events, but the selected plot will be reset when the mouse moves away from the item.
• for a combination of MOUSE_CLICK and MOUSE_OVER_TOOLTIP, the selection will happen on both the mouse click and mouse hover events, and the selected plot will be stored until it is replaced by a new selection.

This method can be used in conjunction with a mouse click Action attached to the Legend object. The DEMOS_HTML5/misc_demos/GlgRTChart.js file in the GLG installation directory provides an example of using this technique to highlight a plot when its legend icon is clicked on.

See also GetLegendSelection.

SendMessageToObject()

Object SendMessageToObject	(	String	resource_name,
		String	message,
		Object	param1,
		Object	param2,
		Object	param3,
		Object	param4
	)

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

In most cases, the object it is a viewport with a GLG input handler attached, such as a button or a slider.

Parameters

resource_name	Specifies the resource path of a child object to send the message to, or null to send the message to the object the method is invoked on. The resource path is relative to the invoking object. 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 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.

Integer parameters should be passed as GlgInteger objects created with CreateGlgInteger.

Integer return values are also returned as GlgInteger objects.

SetTooltipFormatter()

static GlgTooltipFormatter SetTooltipFormatter ( GlgTooltipFormatter  formatter )

static

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. Use CreateGlgTooltipFormatter to create a custom tooltip formatter.

Returns

The previously set formatter, if any, or null otherwise.