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

Detailed Description

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

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

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

static String	CreateResourcePath (GlgObject object, GlgObject parent)
	Returns a relative resource path that can be used to access the object as a resource of the parent object. More...

bool	FindObjects (GlgFindObjectsData data)
	Finds either one or all parents or children of the object that match the supplied search criteria. More...

GlgObject	GetAction (GlgActionType action_type, GlgTriggerType trigger_type, int button, GlgArmedStateType armed_state, GlgDoubleClickStateType double_click_state, String action, String subaction, bool enabled_only)
	Returns the first found action with the matching parameters attached to the object. More...

GlgObject	GetAlarmObject (String alarm_label, bool single_alarm)
	Retrieves an alarm object with a specified alarm label inside the object the method is invoked on. More...

GlgCube	GetBox ()
	Returns the object's bounding box extent in screen coordinates. More...

int	GetNumParents ()
	ADVANCED: Returns number of the object's parents. More...

GlgObject	GetObjectViewport (bool heavy_weight, bool self)
	Returns parent viewport of the drawable object. More...

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

GlgObject	GetParentViewport (bool heavy_weight)
	Returns parent viewport of the drawable object. More...

Object	GetResource (String resource_name)
	Deprecated, use GetNativeComponent: Returns an ID of a native resource. More...

GlgObject	GetResourceObject (String resource_name)
	Finds and returns a named resource or an attribute of the object. More...

GlgObject	GetTagObject (String search_string, bool by_name, bool unique_tags, bool single_tag, GlgTagType tag_type_mask)
	Retrieves a tag object with a specified tag name, data tag source, or export tag category inside the object the method is invoked on. More...

bool	HasTag (String tag_name, GlgTagType tag_type_mask)
	Checks if a data or export tag with a specified tag name exists inside the object the method is invoked on. More...

bool	IsDrawable ()
	Checks if the object is drawable. More...

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

void	TraverseObjects (GlgObjectActionInterface action)
	Traverses the object hierarchy of the object and and performs the specified actions on the object itself and all its subobjects, including object attributes. More...

bool	UnconstrainObject ()
	Unconstrains the object's attribute or the object's point. More...

Function Documentation

◆ CreatePointArray()

GlgObject CreatePointArray ( GlgControlPointType type )

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

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 "G" data objects used as control points.

◆ CreateResourceList()

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

Returns a list of the object's resources.

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 the object's resources.

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 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 = object.CreateResourceList( true, true, false );
if( list != null )
{
   int size = list.GetSize();
   for( int i=0; i < size; ++i )
   {
      GlgObject list_element = list.GetElement( i);
      System.Console.WriteLine( "Resource Name: " + list_element.GetObjectName() );
    }
 }

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

◆ CreateResourcePath()

static String CreateResourcePath	(	GlgObject	object,
		GlgObject	parent
	)

static

Returns a relative resource path that can be used to access the object as a resource of the parent object.

Parameters

object	The object whose resource path is being queried. The object must be named.
parent	The parent object relative to which the resource path is evaluated. It must have its HasResources flag set.

Returns: The resource path, or null if the resource path can't be determined.

◆ FindObjects()

bool FindObjects ( GlgFindObjectsData data )

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

Parameters

data	The GlgFindObjectsData object that specifies search criteria and returns the search results.

Returns: true if at least one matching object was found, false otherwise.

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

If the result is a single object, found_multiple property will be set to false.
If the result is a group of several matching objects, the found_multiple property will be set to true.

The dont_add_matches property of GlgFindObjectsData may be set to true to prevent adding matching objects to the found_object property when the custom_match interface processes objects in-place, as shown in the DEMOS_C#/SCADAViewer/HMIPageC.cs file in the GLG installation directory.

See GlgFindObjectsData for more information.

◆ GetAction()

GlgObject GetAction	(	GlgActionType	action_type,
		GlgTriggerType	trigger_type,
		int	button,
		GlgArmedStateType	armed_state,
		GlgDoubleClickStateType	double_click_state,
		String	action,
		String	subaction,
		bool	enabled_only
	)

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

Parameters

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 INPUT_TRIGGER trigger. If null, action objects with any input action string will be considered.
subaction	Specifies input subaction string for action objects with 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.

◆ GetAlarmObject()

GlgObject GetAlarmObject	(	String	alarm_label,
		bool	single_alarm
	)

Retrieves an alarm object with a specified alarm label inside the object the method is invoked on.

The search string can contain wildcards to retrieve a list of alarms matching the specified alarm label pattern.

Parameters

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.

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 alarms with matching alarm labels attached to the objects.
null if no matching alarms were found.

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

◆ GetBox()

GlgCube GetBox ( )

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

Returns: The GlgCube object representing the object's 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 method returns an internal object which is valid only immediately after the method call and should not be modified.

The object box may be converted to world coordinates by using the sequence of the GetDrawingMatrix, CreateInversedMatrix and TransformPoint methods.

◆ GetNumParents()

int GetNumParents ( )

ADVANCED: Returns number of the object's parents.

This method is used to determine the type of the return value of the GetParent method and must be called after the hierarchy is created.

For constrained objects, the method returns a number greater than 1.

Returns: The number of the object's parents.

◆ GetObjectViewport()

GlgObject GetObjectViewport	(	bool	heavy_weight,
		bool	self
	)

Returns parent viewport of the drawable object.

Parameters

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 method, otherwise an error message is generated and null is returned.

◆ GetParent()

GlgObject GetParent ( )

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

Returns

The parent object if the object has a single parent.
A group containing all object's parents if the object has multiple parents.
null if the 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 objects. GetNumParents may be used to determine the type of the return value.

The returned array of parents is 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 SHALLOW_CLONE, which prevents array's elements from being modified by the GLG internals.

This method must be called after the hierarchy is created.

◆ GetParentViewport()

GlgObject GetParentViewport ( bool heavy_weight )

Returns parent viewport of the drawable object.

Parameters

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 method, otherwise an error message is generated and null is returned.

◆ GetResource()

Object GetResource ( String resource_name )

Deprecated, use GetNativeComponent:
Returns an ID of a native resource.

Parameters

resource_name Specifies the resource path of a native resource.

Returns: Native resource object.

This method was used in previous releases to get IDs of native objects used to render the viewport's drawing.

The method is deprecated, use GetNativeComponent.

◆ GetResourceObject()

GlgObject GetResourceObject ( String resource_name )

Finds and returns a named resource or an attribute of the object.

Parameters

resource_name A resource path to access the resource object inside the object the method is invoked on. It may use object names or default attribute names.

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

This method finds and returns a named resource or an attribute of the object. 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 if a resource exists.

◆ GetTagObject()

GlgObject GetTagObject	(	String	search_string,
		bool	by_name,
		bool	unique_tags,
		bool	single_tag,
		GlgTagType	tag_type_mask
	)

Retrieves a tag object with a specified tag name, data tag source, or export tag category inside the object the method is invoked on.

The search string can contain wildcards to retrieve a list of tags matching the specified tag name, tag source or category pattern.

Parameters

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

bool HasTag	(	String	tag_name,
		GlgTagType	tag_type_mask
	)

Checks if a data or export tag with a specified tag name exists inside the object the method is invoked on.

Parameters

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.

◆ IsDrawable()

bool IsDrawable ( )

Checks if the object is drawable.

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.

◆ QueryTags()

GlgObject QueryTags ( GlgTagType tag_type_mask )

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

Parameters

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.

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.

◆ TraverseObjects()

void TraverseObjects ( GlgObjectActionInterface action )

Traverses the object hierarchy of the object and and performs the specified actions on the object itself and all its subobjects, including object attributes.

Parameters

action

GlgObjectActionInterface or GlgObjectActionInterfaceExt interface that provides custom actions to be performed on each traversed object.

If action implements the GlgObjectActionInterfaceExt interface, the interface's methods will be invoked twice for each traversed object: the Action method will be invoked before traversing the object's subobjects, and ActionExt will be invoked after traversing the object's subobjects.

If action implements the GlgObjectActionInterface interface, the interface's Action method will be invoked just once before traversing each object's subobjects.

The return result of the Action interface method (invoked before traversing the object's subobjects) is used to modify the traversal: if the method returns false for a subobject, traversal of objects inside the subobject will not be performed.

◆ UnconstrainObject()

bool UnconstrainObject ( )

Unconstrains the object's attribute or the object's point.

Parameters

attribute The attribute or point object to be unconstrained.

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.

Detailed Description

Functions

Function Documentation

◆ CreatePointArray()

◆ CreateResourceList()

◆ CreateResourcePath()

◆ FindObjects()

◆ GetAction()

◆ GetAlarmObject()

◆ GetBox()

◆ GetNumParents()

◆ GetObjectViewport()

◆ GetParent()

◆ GetParentViewport()

◆ GetResource()

◆ GetResourceObject()

◆ GetTagObject()

◆ HasTag()

◆ IsDrawable()

◆ QueryTags()

◆ TraverseObjects()

◆ UnconstrainObject()