Object Queries

This group contains functions for querying objects, their properties and relations to other objects. More...

Detailed Description

This group contains functions for querying objects, their properties and relations to other objects.

Functions
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	GlgFindObjects (GlgObject object, GlgFindObjectsData *data)
	Finds either one or all parents or children of the specified object that match the supplied search criteria. 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...
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...
GlgCube *	GlgGetBoxPtr (GlgObject object)
	Returns an object's bounding box extent in screen coordinates. More...
GlgObject	GlgGetObjectViewport (GlgObject object, GlgBoolean heavy_weight, GlgBoolean self)
	Returns parent viewport of a drawable GLG object. 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...
GlgObject	GlgGetParentViewport (GlgObject object, GlgBoolean heavy_weight)
	Returns parent viewport of a drawable GLG 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...
GlgBoolean	GlgIsDrawable (GlgObject object)
	Checks if an object is drawable. 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...
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...

Function Documentation

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.

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 ) ); 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.

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.

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.

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.

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: GLG_DATA_TAG GLG_EXPORT_TAG GLG_EXPORT_DYN_TAG. 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.

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.

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: GLG_DATA_TAG GLG_EXPORT_TAG GLG_EXPORT_DYN_TAG. 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.

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.

See also GlgTraverseObjectsExt.

Parameters

object	The object to traverse.
func	A custom traversal function that will be invoked for each traversed object. The function is invoked before traversing the object's 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.
data	Custom data that will be passed to the traversal function. 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.

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.