Detailed Description

This group lists GLG Intermediate API methods of the GlgObjectC class.

These methods 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:

Methods to modify objects in the drawing and save the modified drawing, as well as to perform various object queries.
Specialized Chart methods to handle used interaction with the chart.

The C Intermediate API contains additional C Intermediate API functions that can be used in the C++ code.

See GlgObjectC for a complete list of methods in all APIs.

Include file: GlgClass.h

Functions
	GlgObjectC (GlgObjectC &parent, char *resource_name)
	Constructor, Intermediate API: associates this object with a named resource object inside another object. More...

GlgBoolean	ConstrainObject (GlgObjectC &to_attribute)
	Constrains an attribute or a point of an object to an attribute or a point of another object. More...

GlgBoolean	ContainsObject (GlgObjectC &object)
	Checks if object belongs to this container. More...

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

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

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

char *	CreateTooltipString (double x, double y, double dx, double dy, char *format)
	Creates and returns a chart or axis tooltip string based on the mouse position. More...

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

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

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

GlgObject	GetDrawingMatrix (void)
	Returns the transformation matrix used to draw the object. More...

GlgObject	GetElement (GlgLong index)
	Returns the object at the specified position in this container. More...

GlgLong	GetIndex (GlgObjectC &object)
	Returns the index of the first occurrence of an object in this container. More...

void	GetMatrixData (GlgMatrixData *matrix_data)
	Queries coefficients of this matrix. More...

GlgObject	GetNamedObject (char *name)
	Find and returns an object ID of the object with the specified name inside this container. More...

GlgObject	GetParent (GlgLong *num_parents)
	Returns an object's parent object, if one exists. More...

GlgObject	GetResourceObject (char *resource_name)
	Find a resource object. More...

GlgLong	GetSize (void)
	Returns size of this container object. More...

GlgLong	GetStringIndex (char *string)
	Returns the index of the first occurrence of a string in this container of the GLG_STRING type. More...

GlgObject	GetTagObject (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	HasTag (char *tag_name, GlgTagType tag_type_mask)
	Checks if a data or export tag with a specified tag name exists. More...

void	Inverse ()
	Inverses the order of elements inside this container object. More...

GlgObject	InverseMatrix (void)
	Inverts this matrix object. More...

GlgBoolean	IsContainer (void)

GlgObject	Iterate (void)
	Traverses elements of this container object in the forward direction. More...

GlgObject	IterateBack (void)
	Traverses elements of this container object in the backward direction. More...

GlgBoolean	LayoutObjects (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	Load (GlgObjectC &parent, char *resource_name=NULL)
	Finds a resource. More...

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

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

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

GlgBoolean	PositionToValue (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 this Chart or Axis object. More...

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

void	ReleaseObject (void)
	Releases an object that was suspended for editing. More...

GlgBoolean	ReorderElement (GlgLong old_index, GlgLong new_index)
	Changes an object's position inside this container. More...

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

GlgBoolean	Save (char *filename)
	Saves this object to a file. More...

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

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

void	SetEnd (void)
	Initializes this container object for the backward traversing. More...

void	SetMatrixData (GlgMatrixData *matrix_data)
	Sets coefficients of this matrix. More...

void	SetStart (void)
	Initializes this container object for the forward traversing. More...

void	SuspendObject (void)
	Suspends a drawn object for editing. More...

GlgBoolean	TransformObject (GlgObjectC &xform, GlgCoordType coord_type, GlgObjectC *parent=NULL)
	ADVANCED: Transforms all control points of an object with an arbitrary transformation. More...

void	TransformPoint (GlgPoint in_point, GlgPoint out_point)
	Transforms a single point using this matrix. More...

GlgBoolean	UnconstrainObject (void)
	Unconstrains an attribute or point object stored in this object. More...

GlgBoolean	WorldToScreen (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...

Function Documentation

◆ GlgObjectC()

GlgObjectC	(	GlgObjectC &	parent,
		char *	resource_name
	)

Constructor, Intermediate API: associates this object with a named resource object inside another 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. If NULL, the parent object itself is used.

This is a wrapper for GlgGetResourceObject, see GlgGetResourceObject for more information.

◆ ConstrainObject()

GlgBoolean ConstrainObject ( GlgObjectC & to_attribute )

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

This is a wrapper for GlgConstrainObject.

This method constrains attribute or point object stored in this object. To obtain the object ID of the attribute or point object to be constrained, the GetResourceObject method 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 GetElement or Iterate method to get its 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.

The method constrains the attribute or the point stored in this object 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 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 SuspendObject and ReleaseObject methods to temporarily suspend a drawn object for editing.

You cannot constrain any objects beside attribute objects (a control point is an attribute object as well). The objects being constrained must 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 method fails and returns False. If constraining is successful, the method 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.

◆ ContainsObject()

GlgBoolean ContainsObject ( GlgObjectC & object )

Checks if object belongs to this container.

Parameters

object The object to search for.

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

◆ CreateChartSelection()

GlgObject CreateChartSelection	(	GlgObjectC *	plot,
		double	x,
		double	y,
		double	dx,
		double	dy,
		GlgBoolean	screen_coord,
		GlgBoolean	include_invalid,
		GlgBoolean	x_priority
	)

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

This is a wrapper for GlgCreateChartSelection.

Parameters

plot	An optional plot object. If it is not NULL, the method queries only the samples in that plot, otherwise the method queries data samples in all plots of the chart and selects the sample closest to the specified position.
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 method 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 method returns NULL if no data sample matching the selection criteria was found.

The returned message is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned message.

◆ CreatePointArray()

GlgObject CreatePointArray ( GlgControlPointType type )

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

This is a wrapper for GlgCreatePointArray.

Parameters

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 group is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group.

◆ CreateResourceList()

GlgObject CreateResourceList	(	GlgBoolean	list_named_res,
		GlgBoolean	list_def_attr,
		GlgBoolean	list_aliases
	)

Returns a list of an object's resources.

This is a wrapper for GlgCreateResourceList.

Parameters

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 group is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group as shown in the example below.

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:

GlgObjectC list = object.CreateResourceList( True, True, False );
list.Drop();
 
if( !list.IsNull() )
{
   int size = list.GetSize();
   for( int i=0; i < size; ++i )
   {
      GlgObject list_element = list.GetElement( i);
      printf( "Resource Name: %s\n", GlgGetObjectName( list_element ) );
    }
 }

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

Use CreateResourceList 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 GetResourceObject method to obtain its object ID, then call CreateResourceList with that object ID. This method is slower but will work for both named resources, default attributes and aliases.

◆ CreateTooltipString()

char* CreateTooltipString	(	double	x,
		double	y,
		double	dx,
		double	dy,
		char *	format
	)

Creates and returns a chart or axis tooltip string based on the mouse position.

Creates and returns a tooltip string corresponding to the specified position in screen coordinates inside of this Chart or Axis object. This is a wrapper for GlgCreateTooltipString.

Parameters

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 method 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 method is invoked for a Chart object.

Returns: A Chart or Axis tooltip corresponding to the specified position, or NULL if no tooltip was created. The returned string must be freed using GlgFree.

If the this object is a Chart, and the specified position is within the chart's data area, the method 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 this object is an Axis, or if the this 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, CreateTooltipString 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 corresponding C function to create a tooltip string that displays such cursor feedback information at the top of the chart.

◆ FitObject()

GlgBoolean FitObject	(	GlgCoordType	coord_type,
		GlgCube *	box,
		GlgBoolean	keep_ratio
	)

Fits an object to the specified rectangular area.

This is a wrapper for GlgFitObject.

Parameters

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

◆ GetAlarmObject()

GlgObject GetAlarmObject	(	char *	alarm_label,
		GlgBoolean	single_alarm
	)

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

This is a wrapper for GlgGetAlarmObject.

Parameters

alarm_label	A string or a pattern for the search, supporting wildcards: ? (matches any single character) and * (matches any sequence of characters).
single_alarm	Defines a single alarm (True) or multiple alarm (False) mode.

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 is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group.

The GetElement and GetSize methods may be used to handle the returned group object.

◆ GetBoxPtr()

GlgCube* GetBoxPtr ( void )

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

This is a wrapper for GlgGetBoxPtr.

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 GetDrawingMatrix, InverseMatrix and TransformPoint methods.

◆ GetDrawingMatrix()

GlgObject GetDrawingMatrix ( void )

Returns the transformation matrix used to draw the object.

This is a wrapper for GlgGetDrawingMatrix.

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

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

The method returns the internal matrix object which is valid only immediately after the method is called. The matrix should not be modified or destroyed. To prevent the matrix from being destroyed, the returned matrix may be assigned to a GlgObjectC instance that will reference it. Even better, a copy of of the matrix may be stored 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 GetDrawingMatrix method.

◆ GetElement()

GlgObject GetElement ( GlgLong index )

Returns the object at the specified position in this container.

This is a wrapper for GlgGetElement.

Parameters

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 method provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by CreateTagList.

◆ GetIndex()

GlgLong GetIndex ( GlgObjectC & object )

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

This is a wrapper for GlgGetIndex.

Parameters

object The object to search for.

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

◆ GetMatrixData()

void GetMatrixData ( GlgMatrixData * matrix_data )

Queries coefficients of this matrix.

This is a wrapper for GlgGetMatrixData.

Parameters

matrix_data The structure that will receive the returned matrix coefficients.

See GlgMatrixData for details.

◆ GetNamedObject()

GlgObject GetNamedObject ( char * name )

Find and returns an object ID of the object with the specified name inside this container.

This is a wrapper for GlgGetNamedObject.

Parameters

name	The object's name.

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

◆ GetParent()

GlgObject GetParent ( GlgLong * num_parents )

Returns an object's parent object, if one exists.

or an array of all parents for constrained data objects. This is a wrapper for GlgGetParent.

Parameters

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 method 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. To keep it from being destroyed when the parent object is destroyed, you can reference it with Reference (and dereference later). If the return value is an array of parents and you want to keep it around, the safer method to keep it is to create a copy using GLG_SHALLOW_CLONE. This prevents the array's elements from being modified by the GLG internals.

This method must be called after the hierarchy is created.

◆ GetResourceObject()

GlgObject GetResourceObject ( char * resource_name )

Find a resource object.

Retrieves an object ID of a resource object inside this object. This is a wrapper for GlgGetResourceObject.

Parameters

resource_name A string that specifies a resource path to access the resource object inside this.

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

This method finds and returns a named resource of the this 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 method returns NULL. No error message is generated in this case, so this method can be used to query an object's existence.

The returned object ID can be assigned to a GlgObjectC instance that will store and reference it.

◆ GetSize()

GlgLong GetSize ( void )

Returns size of this container object.

This is a wrapper for GlgGetSize.

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 method provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by CreateTagList.

◆ GetStringIndex()

GlgLong GetStringIndex ( char * string )

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

Parameters

string The string to search for.

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

◆ GetTagObject()

GlgObject GetTagObject	(	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.

This is a wrapper for GlgGetTagObject.

Parameters

search_string	A string or a pattern for the search, supporting wildcards: ? (matches any single character) and * (matches any sequence of characters).
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 method returns the first attribute object that has an attached tag that matches the search criteria.
In the multiple tag mode, the method returns a group containing all attribute objects that have matching tags attached. The returned group is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group.
NULL if no matching tags were found.

The GetElement and GetSize methods may be used to handle the returned group object in the multiple tag mode.

◆ HasTag()

GlgBoolean HasTag	(	char *	tag_name,
		GlgTagType	tag_type_mask
	)

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

This is a wrapper for GlgHasTag.

Parameters

tag_name	Specifies the TagName to query, supporting wildcards: ? (matches any single character) and * (matches any sequence of characters).
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: True if a tag with the given TagName exists, otherwise it returns False without generating an error message.

◆ Inverse()

void Inverse ( )

Inverses the order of elements inside this container object.

This is a wrapper for GlgInverse.

◆ InverseMatrix()

GlgObject InverseMatrix ( void )

Inverts this matrix object.

This is a wrapper for GlgCreateInversedMatrix.

Returns: The inverse of the input matrix. The returned matrix is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned matrix.

This method may be used to invert the drawing transformation obtained using GetDrawingMatrix. 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.

◆ IsContainer()

GlgBoolean IsContainer ( void )

Returns: True if the associated GLG object is a GLG container.

◆ Iterate()

GlgObject Iterate ( void )

Traverses elements of this container object in the forward direction.

This is a wrapper for GlgIterate.

Returns: The next element of the container.

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

SetStart must be used to initialize the container for iterating before Iterate 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 Copy method 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, GetElement 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 Iterate:

int size = container.GetSize();
if( size != 0 )
{
  container.SetStart(); // Initialize forward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObjectC object = container.Iterate();
     ... // Code to process the object.
  }
}

◆ IterateBack()

GlgObject IterateBack ( void )

Traverses elements of this container object in the backward direction.

This is a wrapper for GlgIterateBack.

Returns: The previous element of the container.

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

SetEnd must be used to initialize the container for backward iteration before IterateBack 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 Copy method 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, GetElement 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 IterateBack:

int size = container.GetSize();
if( size != 0 )
{
  container.SetEnd(); // Initialize backward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObjectC object = container.IterateBack();
     ... // Code to process the object.
  }
}

◆ LayoutObjects()

GlgBoolean LayoutObjects	(	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.

This is a wrapper for GlgLayoutObjects.

Parameters

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. See GlgLayoutObjects for a list of possible values.
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 control 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 method.

◆ Load()

GlgBoolean Load	(	GlgObjectC &	parent,
		char *	resource_name = `NULL`
	)

Finds a resource.

Replaces the stored object with a resource object of the parent 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. If NULL, the parent object itself is used.

Returns: Success or failure status.

This is a wrapper for GlgGetResourceObject, see GlgGetResourceObject for more information. The C++ version automatically references the stored resource object.

◆ MoveObject()

GlgBoolean MoveObject	(	GlgCoordType	coord_type,
		GlgPoint *	start_point,
		GlgPoint *	end_point
	)

Moves an object by a move vector.

This is a wrapper for GlgMoveObject.

Parameters

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

◆ MoveObjectBy()

GlgBoolean MoveObjectBy	(	GlgCoordType	coord_type,
		double	x,
		double	y,
		double	z
	)

Moves an object by the specified distances.

This is a wrapper for GlgMoveObjectBy.

Parameters

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

◆ PositionObject()

GlgBoolean PositionObject	(	GlgCoordType	coord_type,
		GlgLong	anchoring,
		double	x,
		double	y,
		double	z
	)

Positions an object at the specified location.

This is a wrapper for GlgPositionObject.

Parameters

coord_type

Specifies the coordinate system for interpreting position 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_BOTTOM).

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 method positions the object, calculating new control point values. The object's hierarchy must be set up to use this method.

◆ PositionToValue()

GlgBoolean PositionToValue	(	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 this Chart or Axis object.

This is a wrapper for GlgPositionToValue.

Parameters

resource_name	Specifies a resource path for accessing a child chart, plot or axis object inside this object. NULL may be used if this object is a Chart, Plot or Axis 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.

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

For an Axis object, the method converts the specified position to the axis value and returns the value.

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

◆ QueryTags()

GlgObject QueryTags ( GlgTagType tag_type_mask )

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

This is a wrapper for GlgQueryTags.

Parameters

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: A list of all attribute objects that have tags of the specified type attached. The returned group is a GlgObject object that must be explicitly dereferenced. If it is assigned to a GlgObjectC instance, use the instance's Drop method to dereference the returned group.

Each element of the returned group is an attribute object that has a tag attached. The GetElement and GetSize methods may be used to handle the returned group object.

◆ ReleaseObject()

void ReleaseObject ( void )

Releases an object that was suspended for editing.

This is a wrapper for GlgReleaseObject.

This method releases a previously suspended object and is intended to be used only in conjunction with the SuspendObject method.

◆ ReorderElement()

GlgBoolean ReorderElement	(	GlgLong	old_index,
		GlgLong	new_index
	)

Changes an object's position inside this container.

This is a wrapper for GlgReorderElement.

Parameters

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

Returns: Success or failure status.

This method moves the object at the old_index to the new_index position inside the container. It generates an error message 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 ReorderElement do not appear in the requested Z order.

◆ RotateObject()

GlgBoolean RotateObject	(	GlgCoordType	coord_type,
		GlgPoint *	center,
		double	x_angle,
		double	y_angle,
		double	z_angle
	)

Rotates an object.

This is a wrapper for GlgRotateObject.

Parameters

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.

Returns: Success or failure status.

This method rotates the object's control points by the specified rotation angles and relative to the specified center, calculating new control point values. If more than one rotation angle is specified, X rotation is applied the first, then Y and Z. The object's hierarchy must be set up to use this method.

◆ Save()

GlgBoolean Save ( char * filename )

Saves this object to a file.

Parameters

filename The file to save the object to.

Returns: Success or failure status.

This is a wrapper for GlgSaveObject. See GlgSaveObject for more information.

◆ ScaleObject()

GlgBoolean ScaleObject	(	GlgCoordType	coord_type,
		GlgPoint *	center,
		double	x_scale,
		double	y_scale,
		double	z_scale
	)

Scales an object.

This is a wrapper for GlgScaleObject.

Parameters

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

◆ ScreenToWorld()

GlgBoolean ScreenToWorld	(	GlgBoolean	inside_vp,
		GlgPoint *	in_point,
		GlgPoint *	out_point
	)

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

This is a wrapper for GlgScreenToWorld.

The method uses the world coordinate system of the object it is invoked on, which includes the effect of all drawing transformations attached to the object and all its parents.

Parameters

inside_vp	If this 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 method.

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.

◆ SetEnd()

void SetEnd ( void )

Initializes this container object for the backward traversing.

This is a wrapper for GlgSetEnd.

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

◆ SetMatrixData()

void SetMatrixData ( GlgMatrixData * matrix_data )

Sets coefficients of this matrix.

Parameters

matrix_data The new matrix's coefficients.

See GlgMatrixData for details.

◆ SetStart()

void SetStart ( void )

Initializes this container object for the forward traversing.

This is a wrapper for GlgSetStart.

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

◆ SuspendObject()

void SuspendObject ( void )

Suspends a drawn object for editing.

This is a wrapper for GlgSuspendObject.

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 SuspendObject method must be used to suspend the object for editing. If SuspendObject is not used, any attempt to perform these modifications will fail, producing an error message.

SuspendObject may be called only for the graphical objects, such as a viewport, group, polygon, or others.

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

◆ TransformObject()

GlgBoolean TransformObject	(	GlgObjectC &	xform,
		GlgCoordType	coord_type,
		GlgObjectC *	parent = `NULL`
	)

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

This is a wrapper for GlgTransformObject.

Parameters

xform	The transformation to be applied to the object's points.
coord_type	The coordinate system to interpret the transformation in: GLG_SCREEN_COORD - the 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 this object is a G data object representing a control point. NULL may be passed in all other cases.

Returns: Success or failure status.

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

◆ TransformPoint()

void TransformPoint	(	GlgPoint *	in_point,
		GlgPoint *	out_point
	)

Transforms a single point using this matrix.

This is a wrapper for GlgTransformPoint.

Parameters

in_point	The input point to be transformed.
out_point	The transformed point.

This method applies this transformation matrix to the in_point parameter, and returns the result in out_point.

◆ UnconstrainObject()

GlgBoolean UnconstrainObject ( void )

Unconstrains an attribute or point object stored in this object.

This is a wrapper for GlgUnconstrainObject.

Returns: Success or failure status.

This method 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 SuspendObject and ReleaseObject methods to temporarily suspend a drawn object for editing.

◆ WorldToScreen()

GlgBoolean WorldToScreen	(	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.

This is a wrapper for GlgWorldToScreen.

The method uses the world coordinate system of the object it is invoked on, which includes the effect of all drawing transformations attached to the object and all its parents.

Parameters

inside_vp	If this 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 method.

Detailed Description

Functions

Function Documentation

◆ GlgObjectC()

◆ ConstrainObject()

◆ ContainsObject()

◆ CreateChartSelection()

◆ CreatePointArray()

◆ CreateResourceList()

◆ CreateTooltipString()

◆ FitObject()

◆ GetAlarmObject()

◆ GetBoxPtr()

◆ GetDrawingMatrix()

◆ GetElement()

◆ GetIndex()

◆ GetMatrixData()

◆ GetNamedObject()

◆ GetParent()

◆ GetResourceObject()

◆ GetSize()

◆ GetStringIndex()

◆ GetTagObject()

◆ HasTag()

◆ Inverse()

◆ InverseMatrix()

◆ IsContainer()

◆ Iterate()

◆ IterateBack()

◆ LayoutObjects()

◆ Load()

◆ MoveObject()

◆ MoveObjectBy()

◆ PositionObject()

◆ PositionToValue()

◆ QueryTags()

◆ ReleaseObject()

◆ ReorderElement()

◆ RotateObject()

◆ Save()

◆ ScaleObject()

◆ ScreenToWorld()

◆ SetEnd()

◆ SetMatrixData()

◆ SetStart()

◆ SuspendObject()

◆ TransformObject()

◆ TransformPoint()

◆ UnconstrainObject()

◆ WorldToScreen()