Detailed Description

This group contains functions of the GLG Intermediate API.

These functions provide additional methods that can be used to traverse all objects defined in the drawing to discover the structure of the drawing, perform coordinate conversion or implement custom object manipulation, such as dragging objects with the mouse.

It also includes:

Functions to modify objects in the drawing and save the modified drawing, as well as to perform various object queries.
Specialized Chart functions to prefill a chart and handle used interaction with the chart.
Functions for implementing custom interaction handlers.
Interface Handler functions used in the editor-style applications that need to implement complex state-based user interaction.

Include file: GlgApi.h

void	GlgSetObjectData (GlgObject object, void *data)
	Attaches arbitrary application data to a graphical object. More...

void *	GlgGetObjectData (GlgObject object)
	Retrieves application data attached to the object via GlgSetObjectData. More...

GlgBoolean	GlgSaveObject (GlgObject object, char *filename)
	Saves an object to a file. More...

void *	GlgSerializeFull (GlgObject object, GlgLong *size)
	Saves a GLG object into a raw memory block. More...

GlgBoolean	GlgSerialize (GlgObject object, GlgBoolean(func)(void data, GlgLong size, void user_data), void user_data)
	Saves a GLG object into a data stream by invoking a custom serialization callback, which can be used to implement custom save methods. More...

GlgLong	GlgGetSize (GlgObject container)
	Returns size of a container object. More...

GlgObject	GlgGetElement (GlgObject container, GlgLong index)
	Returns the object at the specified position in a container. More...

GlgBoolean	GlgContainsObject (GlgObject container, GlgObject object)
	Checks if object belongs to a container. More...

GlgObject	GlgGetNamedObject (GlgObject container, char *name)
	Finds an object with the specified name inside the container of GLG objects and returns it. More...

GlgLong	GlgGetIndex (GlgObject container, GlgObject object)
	Returns index of the first occurrence of an object in a container. More...

GlgLong	GlgGetStringIndex (GlgObject container, char *string)
	Returns index of the first occurrence of a string in a container of the GLG_STRING type. More...

GlgObject	GlgFindObject (GlgObject container, GlgAnyType object, GlgSearchType search_type, GlgAnyType reserved)
	A generic find function that finds an object in a container. More...

void	GlgSetStart (GlgObject container)
	Initializes the container object for the forward traversing. More...

GlgObject	GlgIterate (GlgObject container)
	Traverses the container object's elements in the forward direction. More...

void	GlgSetEnd (GlgObject container)
	Initializes the container object for the backward traversing. More...

GlgObject	GlgIterateBack (GlgObject container)
	Traverses the container object's elements in the backward direction. More...

GlgBoolean	GlgIsAt (GlgObject container, GlgPositionType position)
	Checks the position of the iteration pointer (the current element of the container). More...

GlgBoolean	GlgReorderElement (GlgObject container, GlgLong old_index, GlgLong new_index)
	Changes an element's position inside a container. More...

void	GlgInverse (GlgObject container)
	Inverses the order of elements inside a container object. More...

GlgObject	GlgGetResourceObject (GlgObject parent, char *resource_name)
	Retrieves an object ID of a resource object. More...

GlgObject	GlgGetTagObject (GlgObject object, char *search_string, GlgBoolean by_name, GlgBoolean unique_tags, GlgBoolean single_tag, GlgTagType tag_type_mask)
	Retrieves a tag object with a specified tag name, data tag source, or export tag category, or retrieves a list of tags matching the specified tag name, tag source or category pattern. More...

GlgBoolean	GlgHasTag (GlgObject object, char *tag_name, GlgTagType tag_type_mask)
	Checks if a data or export tag with a specified tag name exists. More...

GlgObject	GlgQueryTags (GlgObject object, GlgTagType tag_type_mask)
	Returns a group of all tags of the requested tag type defined in the object. More...

GlgObject	GlgGetAlarmObject (GlgObject object, char *alarm_label, GlgBoolean single_alarm, GlgLong reserved)
	Returns an alarm object with a specified alarm label, or a list of alarms matching the specified alarm label pattern. More...

GlgObject	GlgGetParent (GlgObject object, GlgLong *num_parents)
	ADVANCED: Returns an object's parent object, if one exists, or an array of all parents for constrained data objects. More...

GlgBoolean	GlgFindObjects (GlgObject object, GlgFindObjectsData *data)
	Finds either one or all parents or children of the specified object that match the supplied search criteria. More...

void	GlgTraverseObjects (GlgObject object, GlgBoolean(func)(GlgObject object, void data), void *data)
	Traverses the object hierarchy of the object and invokes the supplied function on the object itself and all its subobjects, including object attributes. More...

void	GlgTraverseObjectsExt (GlgObject object, GlgBoolean(enter_func)(GlgObject object, void data), GlgBoolean(exit_func)(GlgObject object, void data), void *data)
	Traverses the object hierarchy of the object and invokes the supplied functions on the object itself and all its subobjects, including object attributes. More...

GlgObject	GlgCreatePointArray (GlgObject object, GlgControlPointType type)
	ADVANCED: Creates and returns an array containing all control points of an object. More...

GlgObject	GlgCreateResourceList (GlgObject object, GlgBoolean list_named_res, GlgBoolean list_def_attr, GlgBoolean list_aliases)
	Returns a list of an object's resources. More...

GlgBoolean	GlgIsDrawable (GlgObject object)
	Checks if an object is drawable. More...

GlgCube *	GlgGetBoxPtr (GlgObject object)
	Returns an object's bounding box extent in screen coordinates. More...

GlgObject	GlgGetParentViewport (GlgObject object, GlgBoolean heavy_weight)
	Returns parent viewport of a drawable GLG object. More...

GlgObject	GlgGetObjectViewport (GlgObject object, GlgBoolean heavy_weight, GlgBoolean self)
	Returns parent viewport of a drawable GLG object. More...

GlgObject	GlgGetAction (GlgObject object, GlgActionType action_type, GlgTriggerType trigger_type, GlgLong button, GlgArmedStateType armed_state, GlgDoubleClickStateType double_click_state, char action, char subaction, GlgBoolean enabled_only)
	Returns the first found action with the matching parameters attached to the object. More...

GlgBoolean	GlgDeleteTags (GlgObject object, GlgTagType tag_type_mask)
	Deletes all object's data tags or all object's public properties. More...

GlgBoolean	GlgConstrainObject (GlgObject from_attribute, GlgObject to_attribute)
	Constrains an attribute or a point of an object to an attribute or a point of another object. More...

GlgBoolean	GlgUnconstrainObject (GlgObject attribute)
	Unconstrains a object's attribute or an object's point. More...

GlgObject	GlgSuspendObject (GlgObject object)
	Suspends a drawn object for editing. More...

void	GlgReleaseObject (GlgObject object, GlgObject suspend_info)
	Releases an object that was suspended for editing. More...

void	GlgSetCustomSetupHandler (GlgCustomSetupHandler handler)
	Installs a custom setup handler that will be invoked to perform custom processing of objects tagged using the CustomSetup flag in the GLG drawing. More...

GlgObject	GlgGetDrawingMatrix (GlgObject object)
	ADVANCED: Returns transformation matrix used to draw the object. More...

GlgObject	GlgCreateInversedMatrix (GlgObject matrix)
	Inverts a matrix object. More...

void	GlgTransformPoint (GlgObject matrix, GlgPoint in_point, GlgPoint out_point)
	Transforms a single point. More...

GlgBoolean	GlgScreenToWorld (GlgObject object, GlgBoolean inside_vp, GlgPoint in_point, GlgPoint out_point)
	Converts a point's screen coordinates to the GLG world coordinate system. More...

GlgBoolean	GlgWorldToScreen (GlgObject object, GlgBoolean inside_vp, GlgPoint in_point, GlgPoint out_point)
	Converts a point's coordinates from the GLG world coordinate system to the screen coordinate system. More...

GlgBoolean	GlgTranslatePointOrigin (GlgObject from_viewport, GlgObject to_viewport, GlgPoint *point)
	Converts screen coordinates of a point in one viewport to the screen coordinates of another viewport. More...

GlgBoolean	GlgRootToScreenCoord (GlgObject viewport, GlgPoint2 *point)
	Converts screen coordinates relative to the root window to the screen coordinates in the specified viewport. More...

void	GlgGetMatrixData (GlgObject matrix, GlgMatrixData *matrix_data)
	ADVANCED: Queries matrix coefficients. More...

void	GlgSetMatrixData (GlgObject matrix, GlgMatrixData *matrix_data)
	ADVANCED: Sets matrix coefficients. More...

GlgObject	GlgCreateSelection (GlgObject top_vp, GlgRectangle *rectangle, GlgObject selected_vp)
	Returns a list of the objects intersecting a given rectangle. More...

GlgBoolean	GlgTransformObject (GlgObject object, GlgObject xform, GlgCoordType coord_type, GlgObject parent)
	ADVANCED: Transforms all control points of an object with an arbitrary transformation. More...

GlgBoolean	GlgMoveObjectBy (GlgObject object, GlgCoordType coord_type, double x, double y, double z)
	Moves an object by the specified distances. More...

GlgBoolean	GlgMoveObject (GlgObject object, GlgCoordType coord_type, GlgPoint start_point, GlgPoint end_point)
	Moves an object by a move vector. More...

GlgBoolean	GlgScaleObject (GlgObject object, GlgCoordType coord_type, GlgPoint *center, double x_scale, double y_scale, double z_scale)
	Scales an object. More...

GlgBoolean	GlgRotateObject (GlgObject object, GlgCoordType coord_type, GlgPoint *center, double x_angle, double y_angle, double z_angle)
	Rotates an object. More...

GlgBoolean	GlgPositionObject (GlgObject object, GlgCoordType coord_type, GlgLong anchoring, double x, double y, double z)
	Positions an object at the specified location. More...

GlgBoolean	GlgFitObject (GlgObject object, GlgCoordType coord_type, GlgCube *box, GlgBoolean keep_ratio)
	Fits an object to the specified rectangular area. More...

GlgBoolean	GlgLayoutObjects (GlgObject object, GlgObject anchor, GlgLayoutType type, double distance, GlgBoolean use_box, GlgBoolean process_subobjects)
	Performs operations ranging from setting an object's width and height to aligning and layout of groups of objects. More...

GlgBoolean	GlgEnableAttachmentPoints (GlgBoolean state)
	Controls the use of attachment points to determine object extents when the objects are aligned. More...

char *	GlgCreateTooltipString (GlgObject object, double x, double y, double dx, double dy, char *format)
	Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates. More...

GlgBoolean	GlgPositionToValue (GlgObject object, char resource_name, double x, double y, GlgBoolean outside_x, GlgBoolean outside_y, double value)
	Returns a value corresponding to the specified position on top of a Chart or an Axis object. More...

GlgDataSampleNode *	GlgCreateDataSampleNode (GlgObject plot, GlgBoolean extended)
	Creates a data sample node structure to be used with the GlgAddDataSampleNode function. More...

void	GlgFreeDataSampleNode (GlgObject plot, GlgDataSampleNode *node)
	Returns a data sample node to the plot cache for reuse, if possible. More...

GlgDataSample *	GlgGetNodeDataSample (GlgDataSampleNode *node)
	Returns the node's data sample. More...

GlgBoolean	GlgAddDataSampleNode (GlgObject plot, GlgDataSampleNode *node, GlgBoolean quick_mode)
	Adds a data sample node directly to a plot's data buffer. More...

GlgObject	GlgGetLegendSelection (GlgObject object, double x, double y)
	Returns the plot object corresponding to the legend item at the specified position, if any. More...

GlgObject	GlgCreateChartSelection (GlgObject object, GlgObject plot, double x, double y, double dx, double dy, GlgBoolean screen_coord, GlgBoolean include_invalid, GlgBoolean x_priority)
	Selects a chart's data sample closest to the specified position and returns a message object containing the selected sample's information. More...

void	GlgAddHandler (char *handler_name, GlgHandler func)
	Registers a custom interaction handler. More...

void	GlgSetHandlerData (GlgObject viewport, void *data)
	Stores data used by the custom handler instance. More...

void *	GlgGetHandlerData (GlgObject viewport)
	Retrieves stored data used by a custom handler instance. More...

GlgObject	GlgCreateMessage (GlgObject viewport)
	Creates a GLG message object that may be sent by an interaction handler to a parent handler or a parent's Input callback via GlgSendMessageToParent. More...

void	GlgSendMessageToParent (GlgObject viewport, GlgObject message_obj, char action, char subaction)
	Sends a message to the Input callback. More...

PlatformDependent	GlgHandlerGetNativeEvent (GlgCallEvent *call_event)
	Retrieves a native event that triggered handler invocation. More...

Function Documentation

◆ GlgAddDataSampleNode()

GlgBoolean GlgAddDataSampleNode	(	GlgObject	plot,
		GlgDataSampleNode *	node,
		GlgBoolean	quick_mode
	)

Adds a data sample node directly to a plot's data buffer.

This function is used to quickly prefill a chart with a large number of samples.

Parameters

plot A chart's plot to add datasample to.

node A data sample node containing the data sample to be added. GlgCreateDataSampleNode may be used to create data sample nodes.

quick_mode

Enables a quick mode that bypasses chart autoscroll and autoscale logic for faster chart prefilling, and also disables all validity checks for increased performance.

When the last data sample is added, a chart with the SCROLL X axis can be scrolled to show the last added sample by setting EndValue of the chart's X axis to the time stamp of the last data sample.

For a chart with the SWEEP X axis, the GlgUpdateChartTimeAxis function can be used to scroll the chart.

The GlgUpdateChartState function may also be used to update the chart's autoscale and scrollbars when done.

Returns: Success or failure status.

This function is used to enhance performance of prefilling a chart with a large number of data samples. For periodic updates, new data may be pushed into the plot's entry points using GlgSetDResource or GlgSetDTag.

It is recommended that the initial development is done with the quick mode disabled, enabling it when all potential errors have been dealt with.

The DEMOS/RealTime_StripChart/stripchart.c file in the GLG installation directory provides a coding example of prefilling a chart with data using GlgAddDataSampleNode.

◆ GlgAddHandler()

void GlgAddHandler	(	char *	handler_name,
		GlgHandler	func
	)

Registers a custom interaction handler.

Parameters

handler_name	The handler name. The name may be assigned to the Handler attribute of a viewport or a light viewport in the GLG drawing. The name should start with the $ character to avoid generating error messages in GLG editors if the handler assigned to the viewport is not activated in the editor via the GLG Editor Custom Option DLL described here.
func	The handler's entry point function that implements the handler's functionality.

See Interaction Handler for more information.

◆ GlgConstrainObject()

GlgBoolean GlgConstrainObject	(	GlgObject	from_attribute,
		GlgObject	to_attribute
	)

Constrains an attribute or a point of an object to an attribute or a point of another object.

Parameters

from_attribute The attribute or point object to be constrained. To obtain the object ID of the from_attribute, the GlgGetResourceObject function must be used with a default resource name rather than a user-defined resource name as the last part of resource path. For example, "object1/FillColor" must be used to get the object ID of the FillColor attribute of my_object, and not "my_object/my_color".

For objects that have a fixed number of control points (Arc, Text, etc.), use the default attribute name ("PointN") to access an object's Nth control point. For objects with a variable number of points (e.g. polygons), use the GlgGetElement or GlgIterate function to get their points and use them as the from_attribute.

Parameters

to_attribute The attribute or the point to constrain to. This object may be queried by using either the default or a user-defined resource name.

Returns: Success or failure status.

This function constrains the attribute or the point specified by from_attribute to the attribute or the point specified by to_attribute. If two attributes are constrained, changing the value of either attribute changes the values of both. For more information about constraining, see the Constraints section in the Structure of a GLG Drawing chapter of the GLG User's Guide and Builder Reference Manual.

If the object whose from_attribute attribute is being constrained has already been drawn, an error message will be generated. You should either constrain object attributes before drawing the object or use the GlgSuspendObject and GlgReleaseObject functions to temporarily suspend a drawn object for editing.

You cannot constrain any objects beside the attribute objects (a control point is an attribute object as well). The from_attribute and to_attribute attribute objects should be of the same data subtype. That is, you cannot constrain a color attribute object (G type) to the line width attribute object (D type) because they have different data types.

If any of the conditions above are not satisfied, the function fails and returns False. If constraining is successful, the function returns True.

Note that constraining an attribute object causes all the attributes of the attribute object to be identical to the attributes of the object to which it is constrained, including its name, transformation and value. If a transformation is added to an attribute object, it is automatically added to all the attribute objects that are constrained to this attribute object in order to maintain the constraints.

Similarly, if the object name is changed, it is automatically changed for all the objects that are constrained to the object. These changes are permanent and remain in effect even after the constraints are removed.

◆ GlgContainsObject()

GlgBoolean GlgContainsObject	(	GlgObject	container,
		GlgObject	object
	)

Checks if object belongs to a container.

Parameters

container	A container object.
object	The object to search for.

Returns: True if the object is found in the container, False otherwise.

◆ GlgCreateChartSelection()

GlgObject GlgCreateChartSelection	(	GlgObject	object,
		GlgObject	plot,
		double	x,
		double	y,
		double	dx,
		double	dy,
		GlgBoolean	screen_coord,
		GlgBoolean	include_invalid,
		GlgBoolean	x_priority
	)

Selects a chart's data sample closest to the specified position and returns a message object containing the selected sample's information.

Parameters

object	A chart object. If the plot parameter is NULL, the function queries data samples in all plots of the chart and selects the sample closest to the specified position.
plot	An optional plot object. If it is not NULL, the function queries only the samples in that plot.
x,y	Specify the position inside the chart: If screen_coord=True, the position is defined in the screen coordinates of the chart's parent viewport. When the mouse position is used, add GLG_COORD_MAPPING_ADJ to the x and y screen coordinates of the mouse for precise mapping. If screen_coord=False, the x position is defined as an X or time value, and the y position is defined in relative coordinates in the range [0; 1] to allow the chart to process selection for plots with different ranges (0 corresponds to the Low range of each plot, and 1 to the High range).
dx,dy	Specify an extent around the point defined by the x and y parameters. The extent is defined in the same coordinates as x and y, depending on the value of the screen_coord parameter. Only the data samples located within the dx and dy distances of the specified position are considered for the selection.
screen_coord	Controls the way the x and y parameters are interpreted: If True, the x and y parameters supply screen coordinates in the chart's parent viewport. If False, x and y supply relative value, see description of the x and y parameters above.
include_invalid	If True, invalid data samples are considered for selection. If False, invalid samples are never selected.
x_priority	If True, the function selects the data sample closest to the specified position in the horizontal direction with no regards to its distance from the specified position in the vertical direction. If False, a data sample with the closest distance from the specified position is selected.

Returns

The information about the selected data sample is returned in the form of a message object described in the Chart Selection Message Object section in the Appendix B of the GLG Programming Reference Manual.

The function returns NULL if no data sample matching the selection criteria was found.

The returned message object must be dereferenced using GlgDropObject when finished.

◆ GlgCreateDataSampleNode()

GlgDataSampleNode* GlgCreateDataSampleNode	(	GlgObject	plot,
		GlgBoolean	extended
	)

Creates a data sample node structure to be used with the GlgAddDataSampleNode function.

The function returns a cached data sample node if available, otherwise it creates a new one and returns it.

A data sample node contains a GlgDataSample structure that may be retrieved from the node using GlgGetNodeDataSample. Fields of the data sample structure must be filled before adding it to the plot using GlgAddDataSampleNode.

Unused data sample nodes that were not added to a chart may be returned to a cache using GlgFreeDataSampleNode.

Parameters

plot

An optional plot the data sample node will be added to. If plot is provided, a new data sample node will be taken from the plot's cache, if possible:

If the plot doesn't use a cache, this parameter may be set to NULL, and a newly created datasample node will be returned.
If the plot uses cache, the method returns a data sample node from the cache, if available. If the plot cache is empty, a newly created datasample node will be returned.

extended

The type of the data sample to be created inside the node:

True to create an extended data sample (GlgDataSampleExt)
False to create a basic data sample (GlgDataSample).

Returns: A new node containing a data sample of the requested type.

◆ GlgCreateInversedMatrix()

GlgObject GlgCreateInversedMatrix ( GlgObject matrix )

Inverts a matrix object.

Parameters

matrix The matrix to be inverted.

Returns: The inverse of the input matrix. The returned matrix must be dereferenced using GlgDropObject when not needed any more.

This function may be used to invert the drawing transformation obtained using GlgGetDrawingMatrix. While the drawing transformation converts world to screen coordinates, the inverse of it may be used to convert the screen coordinates of objects and object bounding boxes back to world coordinates.

◆ GlgCreateMessage()

GlgObject GlgCreateMessage ( GlgObject viewport )

Creates a GLG message object that may be sent by an interaction handler to a parent handler or a parent's Input callback via GlgSendMessageToParent.

Parameters

viewport The handler's viewport.

Returns: New message object.

The message object's Origin resource will be set to the viewport's name, and the Object resource will be set to the viewport's object ID. The handler can add objects containing additional information to the message object.

The message object is usually stored to be reused for the duration of the handler lifetime and has to be dereferenced with GlgDropObject when the handler is cleaned up to prevent memory leaks, as shown in the Sample Implementation.

◆ GlgCreatePointArray()

GlgObject GlgCreatePointArray	(	GlgObject	object,
		GlgControlPointType	type
	)

ADVANCED: Creates and returns an array containing all control points of an object.

Parameters

object	The object to query.
type	The type of points to be returned: GLG_CONTROL_POINTS - control points GLG_CONTROL_AND_ATTACHMENT_POINTS - control and attachment points.

Returns: An array of G data objects used as control points. The returned array must be dereferenced using GlgDropObject when finished.

◆ GlgCreateResourceList()

GlgObject GlgCreateResourceList	(	GlgObject	object,
		GlgBoolean	list_named_res,
		GlgBoolean	list_def_attr,
		GlgBoolean	list_aliases
	)

Returns a list of an object's resources.

Parameters

object	The object whose resources will be listed.
list_named_res	Include named resources if True.
list_def_attr	Include default attributes if True. The resource objects referred to by the default resource names are not actually included in the list. Instead a dummy scalar data object (type D) is included whose name is the same as the default attribute.
list_aliases	Include aliases if True. The resource objects referred to by the aliases are not included in the list. Instead a dummy scalar data object (type D) is included whose name is the same as the alias.

Returns: An array of an object's resources. The returned array must be dereferenced using GlgDropObject when finished.

The list_named_res, list_def_attr and list_aliases parameters let you choose whether the returned array should include named resources, default attributes, aliases or any combination of the above.

The returned array has one entry for each resource. The entries are not sorted and are listed in the order of the occurrence inside their category. The named resources (if any) are listed first, then default resources and finally the aliases.

For named resources, the entries are the object IDs of the resource objects themselves. For default resources and aliases, the entries are dummy scalar data objects named after the default attributes or aliases. For both types of entries, the name of the entry object is the name of the resource listed.

The following code fragment shows how to print the list of an object's resources:

GlgObject list = GlgCreateResourceList( object, True, True, False );
if( list )
{
   int size = GlgGetSize( list );
   for( int i=0; i < size; ++i )
   {
      GlgObject list_element = GlgGetElement( list, i);
      printf( "Resource Name: %s\n", GlgGetObjectName( list_element ) );
    }
    GlgDropObject( list );
 }

The function returns resource list on only one level of the resource hierarchy. To see the resource lists of the returned resources, invoke GlgCreateResourceList recursively using one of the following techniques:

Use GlgCreateResourceList on the resources in the returned list. This will only work for the named resources since the default resources and aliases are represented by dummy objects.
Get the name of a resource in the returned resource list and use the GlgGetResourceObject function to obtain its object ID, then call GlgCreateResourceList with that object ID. This method is slower but will work for both named resources, default attributes and aliases.

◆ GlgCreateSelection()

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

Returns a list of the 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.

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 containing object IDs of all selected objects, or NULL if no objects were selected. The returned array must be dereferenced with GlgDropObject when done.

This function is similar to GlgCreateSelectionNames function, but it returns an array of objects instead of an array of object names. The 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.

While GlgCreateSelectionNames reports both the selected objects on the bottom of the hierarchy and all their parents, this function reports only objects at the bottom and doesn't include their parents. For example, if a polygon in a group is selected, only the polygon is reported and not the group. To get information about the parents of selected objects, use the GlgGetParent function.

◆ GlgCreateTooltipString()

char* GlgCreateTooltipString	(	GlgObject	object,
		double	x,
		double	y,
		double	dx,
		double	dy,
		char *	format
	)

Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates.

Parameters

object	A Chart or Axis object to create the tooltip for.
x,y	Specify a position on top of a chart or an axis in screen coordinates. When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's X and Y screen coordinates for precise mapping.
dx,dy	Specify the maximum extent in screen pixels around the specified position.
format	Provides a custom format for creating a tooltip string and uses the same syntax as the TooltipFormat attributes of the Chart and Axis objects. If it is set to NULL or an empty string, the format provided by the TooltipFormat attribute of the chart or the axis will be used. A special "<single_line>" tag may be prepended to the format string to force the function to remove all line breaks from the returned tooltip string. A "<chart_only>" tag may also be prepended to search only for a chart tooltip and disable search for the axes' tooltips when the function is invoked for a Chart object.

Returns: A Chart or Axis tooltip string containing information about the chart data sample or an axis position at the specified coordinates, or NULL if no tooltip was created. The returned string must be freed using GlgFree.

If the object parameter specifies a Chart, and the specified position is within the chart's data area, the function selects a data sample closest to the specified position and returns a tooltip string containing information about the sample. The dx and dy parameters define the maximum extent for selecting a data sample, and the TooltipMode attribute of the chart defines the data sample selection mode: X or XY. NULL is returned if no data samples were found within the dx and dy distances of the specified position.

If the object parameter specifies an Axis, or if the object is a Chart and the specified position is on top of one of the chart's axes, the returned tooltip string contain information about the axis value corresponding to the selected position.

While the Chart object proves an integrated tooltip functionality that automatically displays the tooltip without any application involvement when a mouse is hovering over the chart, GlgCreateTooltipString can be used to generate a string containing information about the data sample under the current mouse position that is displayed as the mouse continuously moves over the chart. The DEMOS/RealTime_StripChart/stripchart.c file in the GLG installation directory demonstrates the use of the function to create a tooltip string that displays such cursor feedback information at the top of the chart.

◆ GlgDeleteTags()

GlgBoolean GlgDeleteTags	(	GlgObject	object,
		GlgTagType	tag_type_mask
	)

Deletes all object's data tags or all object's public properties.

Parameters

object	The object to delete the tags from.
tag_type_mask	A bitwise mask that defines the type of tags to delete: GLG_DATA_TAG - data tags GLG_EXPORT_TAG - public properties GLG_EXPORT_DYN_TAG - dynamics' public properties.

Returns: Success or failure status.

This function fails if the object has been set up and drawn. The GlgSuspendObject and GlgReleaseObject functions may be used to temporarily suspend an object that has been drawn to perform any modifications that require a hierarchy reset.

◆ GlgEnableAttachmentPoints()

GlgBoolean GlgEnableAttachmentPoints ( GlgBoolean state )

Controls the use of attachment points to determine object extents when the objects are aligned.

Parameters

state Specifies if attachment points should be used in addition to the control points to determine object extents when the objects are aligned using control points.

Returns: The previous state of the setting.

◆ GlgFindObject()

GlgObject GlgFindObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgSearchType	search_type,
		GlgAnyType	reserved
	)

A generic find function that finds an object in a container.

Use GlgContainsObject, GlgGetNamedObject, GlgGetElement or GlgGetIndex convenience functions for specialized tasks.

This function searches for an object based on the specified name, index, or object ID. If the object is found, the function modifies the container's internal position pointer to point to the found object and returns the object; otherwise it leaves the position pointer intact and returns NULL.

Note:The container's position pointer may be affected by another GlgFindObject call, as well as by GlgAddObject, GlgDeleteObject and other functions that search for a container element. Any function using the position pointer (GLG_CURRENT access type) must be called immediately after the GlgFindObject call before any other call which may affect the position pointer.

Parameters

container	A container object.
object	The container element to search for. Depending on the search type, it may be an object ID, object name, or object's index in the container's object list.
search_type	The search type GLG_FIND_OBJECT - Finds an object by the object ID (pass the object ID as the value of the object parameter). GLG_FIND_BY_NAME - Finds an object by its name (pass the name as the value of the object parameter). GLG_FIND_BY_INDEX - Finds an object by its position in the container object list (pass the zero-based position index as the value of the object parameter). GLG_FIND_STRING - Is used to find a string by its content in containers containing string elements. It compares string contents using the strcmp function instead of comparing just the string pointers.
reserved	A reserved parameter for future extensions; must be NULL.

Returns: The found object, or NULL.

◆ GlgFindObjects()

GlgBoolean GlgFindObjects	(	GlgObject	object,
		GlgFindObjectsData *	data
	)

Finds either one or all parents or children of the specified object that match the supplied search criteria.

Parameters

object The object whose parents or children to search.

data

The structure that specifies search criteria and returns search results. For forward compatibility with future releases the structure has to be cleared by writing zeros before assigning values to its fields. This can be done using the GlgInitStruct macro:

GlgFindObjectsData find_data;

GlgInitStruct( &find_data, sizeof( find_data ) );

GlgInitStruct

#define GlgInitStruct(ptr, size)

Initializes structure with 0s.

Definition: GlgApi.h:2710

GlgFindObjectsData

A structure used to pass information to the GlgFindObjects function, and to return the search results...

Definition: GlgApi.h:3571

See GlgFindObjectsData for more information.

Returns: True if at least one matching object was found, False otherwise.

If one or more matches were found, the the found_object field of GlgFindObjectsData structure will contain the search result:

If the result is a single object, found_multiple field will be set to False.
If the result is a group of several matching objects, the found_multiple field will be set to True.

The dont_add_matches field of GlgFindObjectsData structure may be set to True to prevent adding matching objects to the found_object field when the custom_match function processes objects in-place, as shown in the DEMOS/SCADAViewer/HMIPageC.c file in the GLG installation directory.

See GlgFindObjectsData for more information.

◆ GlgFitObject()

GlgBoolean GlgFitObject	(	GlgObject	object,
		GlgCoordType	coord_type,
		GlgCube *	box,
		GlgBoolean	keep_ratio
	)

Fits an object to the specified rectangular area.

Parameters

object	The object to fit.
coord_type	Specifies the coordinate system for interpreting coordinates of the area to fit to: GLG_SCREEN_COORD - the coordinates are interpreted as screen pixels. GLG_OBJECT_COORD - the coordinates are interpreted as the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - the coordinates are interpreted as the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
box	The area to fit the object to. If the Z extent of the box is 0, 2D fitting is performed and the object is not scaled in the Z dimension. If the Z extent is not 0, 3D fitting is performed.
keep_ratio	Controls how the object's X/Y ratio is handled: True to preserve the object's X/Y ratio by using the smallest of the required X and Y scale factors for both directions. False to use different scale factors for X and Y scaling to fit the object to the box more precisely.

Returns: Success or failure status.

This function transforms the object to fit it to the area defined by the box parameter, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgFreeDataSampleNode()

void GlgFreeDataSampleNode	(	GlgObject	plot,
		GlgDataSampleNode *	node
	)

Returns a data sample node to the plot cache for reuse, if possible.

The node and its datasample should not be accessed by the program after the node has been freed.

Parameters

plot	An optional plot the data sample node belongs to. If provided (not NULL), the data sample node will be returned to the plot's cache if it is enabled. Otherwise, the node will be freed.
node	The data sample node to be freed.

◆ GlgGetAction()

GlgObject GlgGetAction	(	GlgObject	object,
		GlgActionType	action_type,
		GlgTriggerType	trigger_type,
		GlgLong	button,
		GlgArmedStateType	armed_state,
		GlgDoubleClickStateType	double_click_state,
		char *	action,
		char *	subaction,
		GlgBoolean	enabled_only
	)

Returns the first found action with the matching parameters attached to the object.

Parameters

object	The object whose actions to query.
action_type	An action type. If zero (0), actions of any type will be considered.
trigger_type	A trigger type. If zero (0), actions with any trigger type will be considered.
button	A mouse button. If zero (0), actions that are activated by any mouse button will be considered.
armed_state	The setting of the action's ProcessArmed attribute, see GlgArmedStateType.
double_click_state	The setting of an action's DoubleClick attribute, see GlgDoubleClickStateType.
action	The input action string for action objects with GLG_INPUT_TRIGGER trigger. If NULL, action objects with any input action string will be considered.
subaction	Specifies input subaction string for action objects with GLG_INPUT_TRIGGER trigger. If NULL, action objects with any input subaction string will be considered.
enabled_only	If True, only actions enabled by the settings of their Enabled attribute will be considered.

Returns: The first matching action object, or NULL if no matching actions were found.

◆ GlgGetAlarmObject()

GlgObject GlgGetAlarmObject	(	GlgObject	object,
		char *	alarm_label,
		GlgBoolean	single_alarm,
		GlgLong	reserved
	)

Returns an alarm object with a specified alarm label, or a list of alarms matching the specified alarm label pattern.

Parameters

object	Specifies a GLG object whose alarms to query.
alarm_label	A string or a pattern for the search (may include ? and wildcards).
single_alarm	Defines a single alarm (True) or multiple alarm (False) mode.
reserved	Reserved for future use, must be 0.

Returns

In the single alarm mode, returns an data object that has an attached alarm with the alarm label matching the search criterion.
In the multiple alarm mode, returns a group containing all data objects that have attached alarms with matching alarm labels. The returned group must be dereferenced using GlgDropObject when it is no longer needed.
NULL if no matching alarms were found.

The GlgGetElement and GlgGetSize functions may be used to handle the returned group object.

◆ GlgGetBoxPtr()

GlgCube* GlgGetBoxPtr ( GlgObject object )

Returns an object's bounding box extent in screen coordinates.

Parameters

object The object whose bounds are to be returned.

Returns: A pointer to the object's 3-D bounding box. The box boundaries are in absolute screen coordinates (pixels) and are valid only after the object has been drawn. (That is, after the hierarchy has been set up.)

The returned pointer points to internal structures which are valid only while the object exists and should not be modified.

The object box may be converted to world coordinates by using the sequence of the GlgGetDrawingMatrix, GlgCreateInversedMatrix and GlgTransformPoint functions.

◆ GlgGetDrawingMatrix()

GlgObject GlgGetDrawingMatrix ( GlgObject object )

ADVANCED: Returns transformation matrix used to draw the object.

Parameters

object The object to query.

Returns: A matrix object that combines matrices of all transformations used to draw the object.

Transformation matrices are only used for geometric transformations, so this function may be called only for graphical objects, like polygons, arcs and text objects. This function must be called after the object has been drawn. (That is, after its hierarchy has been set up.)

The function returns the internal matrix object which is valid only immediately after the function call. The matrix should not be modified or destroyed. To prevent the matrix from being destroyed, you may reference it with GlgReferenceObject (and dereference later with GlgDropObject), or, even better, create a copy of it to prevent the matrix from being modified.

Querying the drawing matrix of a viewport returns the drawing matrix used to position the viewport's control points, and not the matrix used to render the objects inside it. To get the drawing matrix the viewport uses to draw objects inside it, query the drawing list of the viewport (the Array resource of the viewport) and use it as a parameter of the GlgGetDrawingMatrix function.

◆ GlgGetElement()

GlgObject GlgGetElement	(	GlgObject	container,
		GlgLong	index
	)

Returns the object at the specified position in a container.

Parameters

container	A container object.
index	The object's position inside the container.

Returns: The object at the specified position.

If the specified index is invalid, an error message is generated and NULL is returned.

While the function provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by GlgCreateTagList.

◆ GlgGetHandlerData()

void* GlgGetHandlerData ( GlgObject viewport )

Retrieves stored data used by a custom handler instance.

Parameters

viewport The viewport or the light viewport the handler is attached to.

Returns: The stored data.

◆ GlgGetIndex()

GlgLong GlgGetIndex	(	GlgObject	container,
		GlgObject	object
	)

Returns index of the first occurrence of an object in a container.

Parameters

container	A container object.
object	The object to search for.

Returns: Index of the object, or -1 if the object was not found in the container.

◆ GlgGetLegendSelection()

GlgObject GlgGetLegendSelection	(	GlgObject	object,
		double	x,
		double	y
	)

Returns the plot object corresponding to the legend item at the specified position, if any.

Parameters

object	A Legend object.
x,y	Specifies the position in screen coordinates of the viewport containing the legend.

Returns: The plot corresponding to the item at the specified legend position, or NULL if no legend item was found.

◆ GlgGetMatrixData()

void GlgGetMatrixData	(	GlgObject	matrix,
		GlgMatrixData *	matrix_data
	)

ADVANCED: Queries matrix coefficients.

Parameters

matrix	The matrix object to query.
matrix_data	The structure that will receive the returned matrix coefficients.

See GlgMatrixData for details.

◆ GlgGetNamedObject()

GlgObject GlgGetNamedObject	(	GlgObject	container,
		char *	name
	)

Finds an object with the specified name inside the container of GLG objects and returns it.

Parameters

container	A container object.
name	The object's name.

Returns: The object ID, of NULL if the named object was not found.

◆ GlgGetNodeDataSample()

GlgDataSample* GlgGetNodeDataSample ( GlgDataSampleNode * node )

Returns the node's data sample.

Parameters

node	The data sample node to query.

Returns: Depending on the type of the data sample contained in the node, returns either GlgDataSample or GlgDataSampleExt pointer that can be added to a chart after filling up the data sample's fields.

◆ GlgGetObjectData()

void* GlgGetObjectData ( GlgObject object )

Retrieves application data attached to the object via GlgSetObjectData.

Parameters

object An object to retrieve the data from.

Returns: The data attached to the object.

◆ GlgGetObjectViewport()

GlgObject GlgGetObjectViewport	(	GlgObject	object,
		GlgBoolean	heavy_weight,
		GlgBoolean	self
	)

Returns parent viewport of a drawable GLG object.

Parameters

object	A drawable GLG object.
heavy_weight	Controls the type of a parent viewport to be returned. False to return the closest parent viewport regardless of its type: either a heavyweight or light viewport. True to return the closest heavyweight parent viewport. For example, if the object is inside a light viewport, it will return the heavyweight viewport which is a parent of the light viewport.
self	True to return the object itself if the object is a viewport or a light viewport and heavy_weight is False, or if the object is a viewport and heavy_weight is True.

Returns: A viewport of the requested type, or NULL if the object is a top level viewport that has no parent and self=False.

The object's hierarchy must be set up to use this function, otherwise an error message is generated and NULL is returned.

◆ GlgGetParent()

GlgObject GlgGetParent	(	GlgObject	object,
		GlgLong *	num_parents
	)

ADVANCED: Returns an object's parent object, if one exists, or an array of all parents for constrained data objects.

Parameters

object	The object whose parents are to be returned.
num_parents	A pointer used to return the number of parents attached to the object. If it is NULL, an error message will be generated if the object has more than one parent.

Returns

The parent object's ID if object has a single parent.
A group containing all object's parents if object has multiple parents.
NULL if object has no parents or in case of an error.

For constrained data objects, there may be more than one parent object. In this case, the function returns an array of parent object IDs and sets num_parents, which may be used to check whether a data object is constrained.

The returned object ID is a pointer to an internal data structure and it should not be dereferenced with GlgDropObject. To keep it from being destroyed when the parent object is destroyed, you can reference it with GlgReferenceObject (and dereference later).

If the returned value is an array of parents, it points to an internal object which should not be modified and is destroyed when the object's hierarchy is reset. To keep it around, create a copy using GLG_SHALLOW_CLONE, which prevents array's elements from being modified by the GLG internals.

This function must be called after the hierarchy is created.

◆ GlgGetParentViewport()

GlgObject GlgGetParentViewport	(	GlgObject	object,
		GlgBoolean	heavy_weight
	)

Returns parent viewport of a drawable GLG object.

Parameters

object	A drawable GLG object.
heavy_weight	Controls the type of a parent viewport to be returned. False to return the closest parent viewport regardless of its type: either a heavyweight or light viewport. True to return the closest heavyweight parent viewport. For example, if the object is inside a light viewport, it will return the heavyweight viewport which is a parent of the light viewport.

Returns: A parent viewport of the requested type, or NULL if the object is a top level viewport that has no parent.

The object's hierarchy must be set up to use this function, otherwise an error message is generated and NULL is returned.

◆ GlgGetResourceObject()

GlgObject GlgGetResourceObject	(	GlgObject	parent,
		char *	resource_name
	)

Retrieves an object ID of a resource object.

Parameters

parent	The parent object whose resources are queried.
resource_name	A string that specifies a resource path to access the resource object inside the parent. It may use object names or default attribute names.

Returns: The retrieved object ID, or NULL if the resource was not found.

This function finds and returns a named resource of the parent object or an object ID its attribute. It cannot be used to access attributes that are not objects, such as an object's Name.

If the resource is not found, the function returns NULL. No error message is generated in this case, so this function can be used to query if a resource exists.

The returned object ID is not referenced and is valid only immediately after the function call. Reference the returned object using GlgReferenceObject if the resource ID has to be stored for later use to make sure the object is not destroyed.

◆ GlgGetSize()

GlgLong GlgGetSize ( GlgObject container )

Returns size of a container object.

Parameters

container A container object.

Returns: The size of the container.

For a viewport or group object, the size is the number of objects in the viewport or group. For a polygon, the size is the number of vertices.

While the function provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by GlgCreateTagList.

◆ GlgGetStringIndex()

GlgLong GlgGetStringIndex	(	GlgObject	container,
		char *	string
	)

Returns index of the first occurrence of a string in a container of the GLG_STRING type.

Parameters

container	A container object.
string	The string content to search for using strcmp.

Returns: Index of the string, or -1 if the string was not found in the container.

◆ GlgGetTagObject()

GlgObject GlgGetTagObject	(	GlgObject	object,
		char *	search_string,
		GlgBoolean	by_name,
		GlgBoolean	unique_tags,
		GlgBoolean	single_tag,
		GlgTagType	tag_type_mask
	)

Retrieves a tag object with a specified tag name, data tag source, or export tag category, or retrieves a list of tags matching the specified tag name, tag source or category pattern.

Parameters

object	The object whose tags to query.
search_string	A string or a pattern for the search (may include the ? and * wildcards).
by_name	If True, the search is performed by matching the tag names, otherwise the search is done by matching the tag sources for data tags or matching the tag categories for export tags.
unique_tags	Controls if only one tag is included in case there are multiple data tags with the same TagName or TagSource (is ignored in the single tag mode and when searching for export tags): If True, only the first encountered tag of the highest priority will be listed when several data tags with the same tag name or tag source exist in the drawing. Input tags are prioritized over output tags, and enabled tags over disabled tags. If False, all tags matching the search criteria will be included in the returned list.
single_tag	Defines the single tag (True) or multiple tag (False) mode. In the single tag mode, the first found tag object of the highest priority matching the search criteria will be returned. Input tags are prioritized over output tags, and enabled tags over disabled tags.
tag_type_mask	Defines the type of tags to query: data tags or export tags. For export tags, tag type constants may be combined with bitwise OR to query multiple subtypes of export tags.

Returns

In the single tag mode, the function returns the first attribute object that has an attached tag that matches the search criteria.
In the multiple tag mode, the function returns a group containing all attribute objects that have matching tags attached. The returned group must be dereferenced using GlgDropObject when it is no longer needed.
NULL if no matching tags were found.

The GlgGetElement and GlgGetSize functions may be used to handle the returned group object in the multiple tag mode.

◆ GlgHandlerGetNativeEvent()

PlatformDependent GlgHandlerGetNativeEvent ( GlgCallEvent * call_event )

Retrieves a native event that triggered handler invocation.

Parameters

call_event A pointer to the call_event structure the handler was invoked with.

Returns

A pointer to a native event that triggered handler invocation:

GXEvent * on Windows
XEvent * in X11
MSG * on Windows

The returned native event can be used to retrieve the type of the event and the mouse coordinates if the handler needs to handle mouse and keyboard events. The code for handling native events is the same as the code in the Trace callback.

The GLG_NATIVE_EVENT case of the Sample Implementation source code provides an example of handling of mouse events.

◆ GlgHasTag()

GlgBoolean GlgHasTag	(	GlgObject	object,
		char *	tag_name,
		GlgTagType	tag_type_mask
	)

Checks if a data or export tag with a specified tag name exists.

Parameters

object Specifies a GLG object whose tag to query.

tag_name Specifies the TagName to query.

tag_type_mask

Defines the type of tags to query:

For export tags, tag type constants may be combined with bitwise OR to query multiple subtypes of export tags.

Returns: True if a tag with the given TagName exists, otherwise returns False without generating an error message.

◆ GlgInverse()

void GlgInverse ( GlgObject container )

Inverses the order of elements inside a container object.

Parameters

container A container object.

◆ GlgIsAt()

GlgBoolean GlgIsAt	(	GlgObject	container,
		GlgPositionType	position
	)

Checks the position of the iteration pointer (the current element of the container).

Parameters

container	A container object.
position	The position that is being checked.

Returns

True if the container's current position pointer matches the specified position:

for GLG_START, True if the iteration pointer is positioned before the first element of the container, False otherwise
for GLG_END, True if the iteration pointer is positioned past the last element of the container, False otherwise
for GLG_FIRST, True if the iteration pointer is positioned at the first element of the container, False otherwise
for GLG_LAST, True if the iteration pointer is positioned at the last element of the container, False otherwise.

◆ GlgIsDrawable()

GlgBoolean GlgIsDrawable ( GlgObject object )

Checks if an object is drawable.

Parameters

object The object.

Returns: True if the object is drawable.

Drawable objects can be placed directly in a drawing area, have control points and a bounding box, have the Visibility attribute and can contain custom properties, actions and aliases.

For a Chart object, the Chart itself is drawable, but its Plot objects are not.

◆ GlgIterate()

GlgObject GlgIterate ( GlgObject container )

Traverses the container object's elements in the forward direction.

Parameters

container A container object.

Returns: The next element of the container.

GlgIterate advances the iteration pointer and returns the next element of the container.

GlgSetStart must be used to initialize the container for iterating before GlgIterate is invoked the first time. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the GlgCloneObject function with the GLG_SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects IDs, and it can be safely iterated while objects are added or deleted from the original container.

Alternatively, GlgGetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

The following coding example shows how to iterate all objects in a container using GlgIterate:

int size = GlgGetSize( container );
if( size != 0 )
{
  GlgSetStart( container ); // Initialize forward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObject object = GlgIterate( container );
     ... // Code to process the object.
  }
}

◆ GlgIterateBack()

GlgObject GlgIterateBack ( GlgObject container )

Traverses the container object's elements in the backward direction.

Parameters

container A container object.

Returns: The previous element of the container.

GlgIterateBack decrements the iteration pointer and returns the previous element of the container.

GlgSetEnd must be used to initialize the container for backward iteration before GlgIterateBack is invoked the first time. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the GlgCloneObject function with the GLG_SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects IDs, and it can be safely iterated while objects are added or deleted from the original container.

Alternatively, GlgGetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

The following coding example shows how to iterate all objects in a container in the backward direction using GlgIterateBack:

int size = GlgGetSize( container );
if( size != 0 )
{
  GlgSetEnd( container ); // Initialize backward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObject object = GlgIterateBack( container );
     ... // Code to process the object.
  }
}

◆ GlgLayoutObjects()

GlgBoolean GlgLayoutObjects	(	GlgObject	object,
		GlgObject	anchor,
		GlgLayoutType	type,
		double	distance,
		GlgBoolean	use_box,
		GlgBoolean	process_subobjects
	)

Performs operations ranging from setting an object's width and height to aligning and layout of groups of objects.

Parameters

object	The object or the group of objects to perform the requested operations upon.
anchor	The anchor object for alignment operations. If NULL, the first encountered object in the specified alignment direction is used.
type	The type of the layout action to perform: GLG_ALIGN_LEFT - aligns the left edge of elements within the group with the left edge of the anchor element. GLG_ALIGN_RIGHT - aligns the right edge of elements within the group with the right edge of the anchor element. GLG_ALIGN_HCENTER - aligns the center of elements within the group with the center of the anchor element horizontally. GLG_ALIGN_TOP - aligns the top edge of elements within the group with the top edge of the anchor element. GLG_ALIGN_BOTTOM - aligns the bottom edge of elements within the group with the bottom edge of the anchor element. GLG_ALIGN_VCENTER - aligns the center of elements within the group with the center of the anchor element vertically. GLG_SET_EQUAL_VSIZE - sets the height of elements within the group to the height of the anchor. GLG_SET_EQUAL_HSIZE - sets the width of elements within the group to the width of the anchor. GLG_SET_EQUAL_SIZE - sets the width and height of elements within the group to the width and height of the anchor. GLG_SET_EQUAL_VDISTANCE - equally distributes the group's elements in vertical direction as measured by the distance between their centers. GLG_SET_EQUAL_HDISTANCE - equally distributes the group's elements in horizontal direction as measured by the distance between their centers. GLG_SET_EQUAL_VSPACE - equally distributes space gaps between group's elements in vertical direction. GLG_SET_EQUAL_HSPACE - equally distributes space gaps between group's elements in horizontal direction. GLG_SET_VSIZE - sets the height of an object or of all objects in the object group to the value specified by the distance parameter: if process_subobjects=False, sets the object's height if process_subobjects=True, sets the height of all elements within the object group. GLG_SET_HSIZE - sets the width of the object or of all objects in the object group to the value specified by the distance parameter: if process_subobjects=False, sets the object's width if process_subobjects=True, sets the width of all elements within the object group. GLG_SET_VDISTANCE - sets the vertical distance between centers of the group's elements to a value specified by the distance parameter. GLG_SET_HDISTANCE - sets the horizontal distance between centers of the group's elements to a value specified by the distance parameter. GLG_SET_VSPACE - sets the space gaps between group's elements in vertical direction to a value specified by the distance parameter. GLG_SET_HSPACE - sets space gaps between group's elements in horizontal direction to a value specified by the distance parameter.
distance	The distance in screen coordinates for positioning objects, it is interpreted depending on the layout action.
use_box	Controls how the objects extent is determined: True to use the object's real bounding box to align objects False to use the object's control points to determine the object's extent, which could be different from the real bounding box for objects such as a Text object with a single conrol point.
process_subobjects	Controls how to apply the layout action if the object is a group: True to apply the action to all objects contained in the group False the apply the action (such as GLG_SET_HSIZE) to the group itself.

Returns

False if errors were encountered during the requested layout action,
True if the requested action was successfully executed.

The object's hierarchy must be set up to use this function.

◆ GlgMoveObject()

GlgBoolean GlgMoveObject	(	GlgObject	object,
		GlgCoordType	coord_type,
		GlgPoint *	start_point,
		GlgPoint *	end_point
	)

Moves an object by a move vector.

Parameters

object	The object to move.
coord_type	Specifies the coordinate system for interpreting the move vector: GLG_SCREEN_COORD - the move vector is considered to be defined using screen pixels. GLG_OBJECT_COORD - the move vector coordinates are interpreted in the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - the move vector coordinates are interpreted in the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
start_point	The start point of the move vector. If NULL, (0,0,0) is used as the start point.
end_point	The end point of the move vector.

Returns: Success or failure status.

This function moves an object's control points by the distance defined by the move vector, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgMoveObjectBy()

GlgBoolean GlgMoveObjectBy	(	GlgObject	object,
		GlgCoordType	coord_type,
		double	x,
		double	y,
		double	z
	)

Moves an object by the specified distances.

Parameters

object	The object to move.
coord_type	Specifies the coordinate system for interpreting move distances: GLG_SCREEN_COORD - move distances are considered to be in screen pixels. GLG_OBJECT_COORD - move distances are considered to be in the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - move distances are considered to be in the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
x,y,z	The X, Y and Z move distances.

Returns: Success or failure status.

This function moves an object's control points by the specified X, Y and Z distances, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgPositionObject()

GlgBoolean GlgPositionObject	(	GlgObject	object,
		GlgCoordType	coord_type,
		GlgLong	anchoring,
		double	x,
		double	y,
		double	z
	)

Positions an object at the specified location.

Parameters

object	The object to position.
coord_type	Specifies the coordinate system for interpreting postion coordinates: GLG_SCREEN_COORD - the coordinates are interpreted as screen pixels. GLG_OBJECT_COORD - the coordinates are interpreted as the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - the coordinates are interpreted as the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
anchoring	Specifies what part of the object's bounding box will be anchored at the specified position. It is formed as a bitwise OR of the horizontal anchoring constant (GLG_HLEFT, GLG_HCENTER or GLG_HRIGHT) with the vertical anchoring constants (GLG_VTOP, GLG_VCENTER or GLG_VBOTTOM). For example, using ( GLG_VTOP \| GLG_HLEFT ) causes the upper left corner of the object's bounding box to be positioned at the specified location.
x,y,z	The X, Y and Z coordinates of the desired object position.

Returns: Success or failure status.

This function positions the object, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgPositionToValue()

GlgBoolean GlgPositionToValue	(	GlgObject	object,
		char *	resource_name,
		double	x,
		double	y,
		GlgBoolean	outside_x,
		GlgBoolean	outside_y,
		double *	value
	)

Returns a value corresponding to the specified position on top of a Chart or an Axis object.

Parameters

object	If resource_name is NULL, specifies a Chart, a Plot or an Axis object, otherwise it specifies a container object containing a chart, a plot or an axis.
resource_name	Specifies a resource path of a child chart, plot or axis object relative to the container object.
x,y	Specify a position in the screen coordinates of the parent viewport. When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's X and Y coordinates for precise mapping.
outside_x	If True, False will be returned for points outside the X extent of the chart or axis object.
outside_y	If True, False will be returned for points outside the Y extent of the chart or axis object.
value	A pointer to the returned value.

Returns: Success or failure status.

If object is a Plot, the function converts the specified position to a Y value in the Low/High range of the plot and returns the value through the value pointer.

If object is an Axis, the function converts the specified position to the axis value and returns the value.

If object is a Chart, the function converts the specified position to the X or time value of the chart's X axis and returns the value.

◆ GlgQueryTags()

GlgObject GlgQueryTags	(	GlgObject	object,
		GlgTagType	tag_type_mask
	)

Returns a group of all tags of the requested tag type defined in the object.

Parameters

object Specifies a GLG object whose tags to query.

tag_type_mask

Defines the type of tags to query:

For export tags, tag type constants may be combined with bitwise OR to query multiple subtypes of export tags.

Returns: A list of all attribute objects that have tags of the specified type attached. The returned group object must be dereferenced using GlgDropObject when it is no longer needed.

Each element of the returned group is an attribute object that has a tag attached. The GlgGetElement and GlgGetSize functions may be used to handle the returned group object.

◆ GlgReleaseObject()

void GlgReleaseObject	(	GlgObject	object,
		GlgObject	suspend_info
	)

Releases an object that was suspended for editing.

Parameters

object	The suspended object to be released.
suspend_info	Suspension information returned by the previous call to GlgSuspendObject.

This function releases previously suspended object and is intended to be used only in conjunction with the GlgSuspendObject function.

◆ GlgReorderElement()

GlgBoolean GlgReorderElement	(	GlgObject	container,
		GlgLong	old_index,
		GlgLong	new_index
	)

Changes an element's position inside a container.

Parameters

container	A container object.
old_index	The index of an element to be reordered.
new_index	A new element position.

Returns: Success or failure status.

This function moves the element at the old_index to the new_index position inside the container. It generates an error message and returns False if indexes are out of range.

GTK Note: GTK doesn't have a notion of windows' Z order. While the GLG driver tries to maintain the window order as much as possible, windows' Z order may not be correct when a mix of the DrawingArea viewports and native widget viewports (such as a text entry, a combo box, etc.) is displayed in the GTK version of the Toolkit on Linux. This may be the reason why viewports reordered with GlgReorderElement do not appear in the requested Z order.

◆ GlgRootToScreenCoord()

GlgBoolean GlgRootToScreenCoord	(	GlgObject	viewport,
		GlgPoint2 *	point
	)

Converts screen coordinates relative to the root window to the screen coordinates in the specified viewport.

Parameters

viewport	The viewport whose screen coordinate system to convert to.
point	The point to be converted. The result is placed back into the structure pointed by this pointer.

Returns: Success or failure status.

The viewport's hierarchy must be set up to use this function.

◆ GlgRotateObject()

GlgBoolean GlgRotateObject	(	GlgObject	object,
		GlgCoordType	coord_type,
		GlgPoint *	center,
		double	x_angle,
		double	y_angle,
		double	z_angle
	)

Rotates an object.

Parameters

object	The object to rotate.
coord_type	Specifies the coordinate system for interpreting the rotation's center: GLG_SCREEN_COORD - the rotation's center coordinates are interpreted as screen pixels. GLG_OBJECT_COORD - the rotation's center coordinates are interpreted as the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - the rotation's center coordinates are interpreted as the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
center	The center of rotation. If the parameter is NULL, the object is rotated relative to the center of its bounding box.
x_angle,y_angle,z_angle	The X, Y and Z rotation angles in degrees. Only one rotation at a time can be performed (only one angle can have non-zero value).

Returns: Success or failure status.

This function rotates the object's control points by the specified rotation angles and relative to the specified center, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgSaveObject()

GlgBoolean GlgSaveObject	(	GlgObject	object,
		char *	filename
	)

Saves an object to a file.

Parameters

object	The object to be saved; it may be any GLG object.
filename	The file to save the object to.

Returns: False if the file is not accessible for writing, True if the object was successfully saved.

This function saves the specified object and all its subsidiary objects to a file. A GLG object of any type may be saved in this fashion and later loaded using GlgLoadObject. The GlgSaveFormat global configuration resource described the Appendices chapter of the GLG Programming Reference Manual may be used to modify save type.

For applications that load a drawing, modify it and save if back to a file, the drawing should be loaded using GlgLoadObject instead of GlgLoadWidgetFromFile. GlgLoadWidgetFromFile extracts the $Widget viewport from the loaded drawing, discarding the rest of the drawing, while GlgLoadObject returns an object that represents the whole drawing.

Using GlgSaveObject to save a viewport loaded with GlgLoadWidgetFromFile will result in a loss of information contained in the discarded part of the drawing, such as the type of the coordinate system used to display the viewport, which will make it difficult to load and edit the drawing in the Graphics Builder. The following example demonstrates the proper technique:

GlgObject drawing = GlgLoadObject( "drawing.g" );
GlgObject viewport = GlgLoadWidgetFromObject( drawing ); // Extract $Widget viewport.
 
... // Code that modifies the drawing using the <i>viewport</i> object ID.
 
GlgSaveObject( drawing, "new_drawing.g" );

◆ GlgScaleObject()

GlgBoolean GlgScaleObject	(	GlgObject	object,
		GlgCoordType	coord_type,
		GlgPoint *	center,
		double	x_scale,
		double	y_scale,
		double	z_scale
	)

Scales an object.

Parameters

object	The object to scale.
coord_type	Specifies the coordinate system for interpreting the scale center: GLG_SCREEN_COORD - the scale center coordinates are interpreted as screen pixels. GLG_OBJECT_COORD - the scale center coordinates are interpreted as the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - the scale center coordinates are interpreted as the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
center	The center of scaling. If the parameter is NULL, the object is scaled relative to the center of its bounding box.
x_scale,y_scale,z_scale	The X, Y and Z scaling factors. Use the same value for all three factors to scale the object uniformly in all dimensions.

Returns: Success or failure status.

This function scales the object's control points by the specified scale factors and relative to the specified center, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgScreenToWorld()

GlgBoolean GlgScreenToWorld	(	GlgObject	object,
		GlgBoolean	inside_vp,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

Converts a point's screen coordinates to the GLG world coordinate system.

Parameters

object	The object whose world coordinate system to convert to. The world coordinate system of an object includes the effect of all drawing transformations attached to the object and all its parents.
inside_vp	If object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use: True to will use the world coordinate system used to draw objects inside this viewport object. False, to use the world coordinate system used to draw this viewport object inside its parent viewport. The value of this parameter is ignored for objects other than a viewport or light viewport.
in_point	The point to be converted.
out_point	The point structure that will receive converted world coordinates.

Returns: Success or failure status.

The object's hierarchy must be set up to use this function.

When converting the cursor position to world coordinates, add GLG_COORD_MAPPING_ADJ to the cursor's X and Y screen coordinates for precise mapping.

◆ GlgSendMessageToParent()

void GlgSendMessageToParent	(	GlgObject	viewport,
		GlgObject	message_obj,
		char *	action,
		char *	subaction
	)

Sends a message to the Input callback.

This function is used by custom interaction handlers to invoke an application's Input callback.

Parameters

viewport	The handler's viewport.
message_obj	A GLG message object created via GlgCreateMessage.
action	The action to be set as the message's Action resource. If action=NULL, the message will be sent as is without setting its action and sub_action.
subaction	The subaction to be set as the message's SubAction resource.

The message is first sent to the handler of the viewport's parent (if any), which can either process and stop message propagation, or send the message to the Input callback. For example, when a spinner's Increase button is pressed, it sends a message to the spinner's handler, which increments the value and stops message propagation. If a stand-alone Increase button is pressed, the message is sent directly to the Input callback. This logic allows parent input handlers handle messages from their children's handlers.

◆ GlgSerialize()

GlgBoolean GlgSerialize	(	GlgObject	object,
		GlgBoolean()(void data, GlgLong size, void *user_data)	func,
		void *	user_data
	)

Saves a GLG object into a data stream by invoking a custom serialization callback, which can be used to implement custom save methods.

Parameters

object The object to be saved; it may be any GLG object.

func

A custom serialization callback function that will be invoked to save the object. The function will be invoked repeatedly with the data and size parameters supplying the pointer to the data that needs to be saved and the size of the data in bytes. The user_data parameter will supply user_data passed to the GlgSerialize function.

At the end of the serialization process, the function will be invoked with data=NULL and size=-1 to flush any remaining data. The function must return True to continue, or False to abort serialization, in which case GlgSerialize will return False as well.

user_data The user data to be passed to the callback function.

Returns: Success or failure status.

◆ GlgSerializeFull()

void* GlgSerializeFull	(	GlgObject	object,
		GlgLong *	size
	)

Saves a GLG object into a raw memory block.

Parameters

object	The object to be saved; it may be any GLG object.
size	A pointer to a variable that will be set to the size of the returned memory block.

Returns: A pointer to the memory block containing the saved object image, or NULL on error.

The size of the returned memory block is returned via the size parameter. The memory should be freed using GlgFree when it is no longer used.

◆ GlgSetCustomSetupHandler()

void GlgSetCustomSetupHandler ( GlgCustomSetupHandler handler )

Installs a custom setup handler that will be invoked to perform custom processing of objects tagged using the CustomSetup flag in the GLG drawing.

Parameters

handler The custom setup handler function to be invoked.

A custom setup handler is a function which is invoked at different times during the lifetime of objects tagged using the CustomSetup flag. The handler is invoked for each tagged object with the object passed as a parameter. The handler can perform custom processing based on the information stored in the object.

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.

See GlgCustomSetupHandler for more information.

◆ GlgSetEnd()

void GlgSetEnd ( GlgObject container )

Initializes the container object for the backward traversing.

Parameters

container A container object.

The function sets the current position pointer past the last element of the container, preparing the container object for the backward traversing with GlgIterateBack.

◆ GlgSetHandlerData()

void GlgSetHandlerData	(	GlgObject	viewport,
		void *	data
	)

Stores data used by the custom handler instance.

Parameters

viewport	The viewport or the light viewport the handler is attached to.
data	The data to be stored.

A custom handler can store its data on set up using this function, and obtain the stored data using GlgGetHandlerData when the handler is invoked to handle user interaction.

◆ GlgSetMatrixData()

void GlgSetMatrixData	(	GlgObject	matrix,
		GlgMatrixData *	matrix_data
	)

ADVANCED: Sets matrix coefficients.

Parameters

matrix	The matrix object.
matrix_data	The new matrix's coefficients.

See GlgMatrixData for details.

◆ GlgSetObjectData()

void GlgSetObjectData	(	GlgObject	object,
		void *	data
	)

Attaches arbitrary application data to a graphical object.

Parameters

object	An object the data will be attached to.
data	The data that will be attached.

◆ GlgSetStart()

void GlgSetStart ( GlgObject container )

Initializes the container object for the forward traversing.

Parameters

container A container object.

The function sets the current position pointer before the first element of the container, preparing the container object for the forward traversing with GlgIterate.

◆ GlgSuspendObject()

GlgObject GlgSuspendObject ( GlgObject object )

Suspends a drawn object for editing.

Parameters

object An object to be suspended.

Returns: An object which keeps suspension information. This information should be passed to the GlgReleaseObject function when the object is released.

Some operations, such as attaching a transformation to an object, constraining an object's attribute and some others, may be carried out only before the object has been drawn. If the object has been drawn and you still need to perform these operations, the GlgSuspendObject function must be used to suspend the object for editing. If GlgSuspendObject is not used, any attempt to perform these modifications will fail, producing an error message.

GlgSuspendObject may be called only for the graphical objects, such as a viewport, group, polygon, text, etc.

The GlgReleaseObject function must be called after the editing operations have been completed. If an object is suspended, it is not allowed to call GlgUpdate until the object has been released.

◆ GlgTransformObject()

GlgBoolean GlgTransformObject	(	GlgObject	object,
		GlgObject	xform,
		GlgCoordType	coord_type,
		GlgObject	parent
	)

ADVANCED: Transforms all control points of an object with an arbitrary transformation.

Parameters

object	The object to transform: a drawable object or a G data object representing a control point.
xform	The transformation (a GLG_XFORM object) to be applied to the object's points.
coord_type	The coordinate system to interpret the transformation in: GLG_SCREEN_COORD - parameters of the transformation are considered to be in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. The start and end coordinates of the mouse move can be supplied using the GLG_TRANSLATE_XF transformation as the xform parameter. GLG_OBJECT_COORD - transformation parameters are interpreted in the GLG world coordinates of the object, which includes all transformations applied to the object. GLG_PARENT_COORD - transformation parameters are interpreted in the GLG world coordinates of the parent object, which includes all transformations applied to the parent, but excludes transformations attached to the object.
parent	The object's parent. It is required if coord_type=GLG_PARENT_COORD, or if the object is a G data object representing a control point. NULL may be passed in all other cases.

Returns: Success or failure status.

This function applies the given transformation to an object's control points, calculating new control point values. The object's hierarchy must be set up to use this function.

◆ GlgTransformPoint()

void GlgTransformPoint	(	GlgObject	matrix,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

Transforms a single point.

Parameters

matrix	The matrix to be applied to the input point.
in_point	The input point to be transformed.
out_point	The transformed point.

This function applies the given transformation matrix to the in_point parameter, and returns the result in out_point.

◆ GlgTranslatePointOrigin()

GlgBoolean GlgTranslatePointOrigin	(	GlgObject	from_viewport,
		GlgObject	to_viewport,
		GlgPoint *	point
	)

Converts screen coordinates of a point in one viewport to the screen coordinates of another viewport.

Parameters

from_viewport	The viewport in which the point's screen coordinates are defined.
to_viewport	The viewport whose screen coordinate system to convert to.
point	The point to be converted. The result is placed back into the structure pointed by this pointer.

Returns: Success or failure status. In the GTK version on Linux, the conversion will fail if the viewports belong to different top level windows, in which case the function will return False.

The objects's hierarchy must be set up to use this function.

◆ GlgTraverseObjects()

void GlgTraverseObjects	(	GlgObject	object,
		GlgBoolean()(GlgObject object, void data)	func,
		void *	data
	)

Traverses the object hierarchy of the object and invokes the supplied function on the object itself and all its subobjects, including object attributes.

◆ GlgTraverseObjectsExt()

void GlgTraverseObjectsExt	(	GlgObject	object,
		GlgBoolean()(GlgObject object, void data)	enter_func,
		GlgBoolean()(GlgObject object, void data)	exit_func,
		void *	data
	)

Traverses the object hierarchy of the object and invokes the supplied functions on the object itself and all its subobjects, including object attributes.

One function is invoked when entering an object and another when exiting it.

Parameters

object	The object to traverse.
enter_func	A custom traversal function that will be invoked for each traversed object to perform a custom action before traversing its subobjects. The function's return result is used to modify the traversal: if the function returns False for a subobject, traversal of objects inside the subobject will not be performed.
exit_func	An optional function that will be invoked for each traversed object to perform a custom action after traversing its subobjects. The function should return True. If NULL is supplied as the value of the exit_func parameter, the exit function is not used and GlgTraverseObjectsExt behaves the same way as GlgTraverseObjects.
data	Custom data that will be passed to the traversal functions. If a pointer to a structure is passed, the structure's fields may be used to pass data to the function, as well as to store data to track the state of the traversal process.

◆ GlgUnconstrainObject()

GlgBoolean GlgUnconstrainObject ( GlgObject attribute )

Unconstrains a object's attribute or an object's point.

Parameters

attribute The attribute or point object to be unconstrained.

Returns: Success or failure status.

This function removes any constraints applied to an attribute object. Any changes made to the object while it was constrained to another object are permanent and will be in effect even after the constraints are removed. The removal of the constraints only means that changes to this object are no longer copied to the other objects to which it was once constrained.

If any of the objects which are using this attribute object (or any objects with attributes constrained to it) have already been drawn, an error message will be generated. You should either unconstrain object attributes before drawing the object or use the GlgSuspendObject and GlgReleaseObject functions to temporarily suspend a drawn object for editing.

◆ GlgWorldToScreen()

GlgBoolean GlgWorldToScreen	(	GlgObject	object,
		GlgBoolean	inside_vp,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

Converts a point's coordinates from the GLG world coordinate system to the screen coordinate system.

Parameters

object	The object whose world coordinate system to convert from. The world coordinate system of an object includes the effect of all drawing transformations attached to the object and all its parents.
inside_vp	If object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use: True to will use the world coordinate system used to draw objects inside this viewport object. False, to use the world coordinate system used to draw this viewport object inside its parent viewport. The value of this parameter is ignored for objects other than a viewport or light viewport.
in_point	The point to be converted.
out_point	The point structure that will receive converted screen coordinates.

Returns: Success or failure status.

The object's hierarchy must be set up to use this function.