Object Queries

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 (boolean list_named_res, boolean list_def_attr, boolean 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...
Object	FindObjects (GlgObjectMatchType match_type, boolean find_parents, boolean include_top_object, boolean find_first_match, boolean search_inside, boolean search_drawable_only, GlgObjectType object_type, String object_name, String resource_name, GlgObject object_id, Function custom_match, boolean search_templates, boolean dont_add_matches)
	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, boolean enabled_only)
	Returns the first found action with the matching parameters attached to the object. More...
GlgObject	GetAlarmObject (String alarm_label, boolean 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 (boolean heavy_weight, boolean 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 (boolean 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, boolean by_name, boolean unique_tags, boolean 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...
boolean	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...
boolean	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 (Function enter_func, Function exit_func)
	Traverses the object hierarchy of the object and invokes the supplied functions on the object itself and all its subobjects, including object attributes. More...
boolean	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	(	boolean	list_named_res,
		boolean	list_def_attr,
		boolean	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:

let list = object.GlgCreateResourceList( true, true, false );
if( list != null )
{
   let size = list.GetSize();
   for( let i=0; i < size; ++i )
   {
      let list_element = list.GetElement( i);
      console.log( "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()

Object FindObjects	(	GlgObjectMatchType	match_type,
		boolean	find_parents,
		boolean	include_top_object,
		boolean	find_first_match,
		boolean	search_inside,
		boolean	search_drawable_only,
		GlgObjectType	object_type,
		String	object_name,
		String	resource_name,
		GlgObject	object_id,
		Function	custom_match,
		boolean	search_templates,
		boolean	dont_add_matches
	)

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

Parameters

match_type	Specifies a bitwise mask of the object matching criteria. The following criteria are supported: OBJECT_TYPE_MATCH finds objects with an object type matching the type specified by the object_type parameter. OBJECT_NAME_MATCH finds objects with a name matching the name specified by the object_name parameter. RESOURCE_MATCH finds objects that have the resource specified by the resource_name parameter. OBJECT_ID_MATCH finds an object specified by the object_id parameter. This can be used to find out if the object the method is invoked on is a child or a parent of the object provided by object_id. CUSTOM_MATCH finds objects that match a custom matching criterion implemented by a function supplied as the custom_match parameter. All of the criteria in the mask must be true in order for an object to match.
find_parents	Controls search direction: If true, the object's ancestors (parents, grandparents and so on) are searched. If false, the object's descendants (children, grandchildren and so on) are searched.
include_top_object	If true, the top object the method is invoked on will be included in the search results if it matches the search criteria. If false, the top object will not be included.
find_first_match	If true, the search is stopped after the first match and the first matching object is returned. If false, all matching objects are returned.
search_inside	If false, an object's children or parents are not searched if the object itself matches. If true, the search proceeds to process an object's children or parents even if the object matches.
search_drawable_only	If true when searching descendants (find_parents=false), only drawable objects are searched. For example, when this flag is set, a polygon object's attributes such as FillColor and EdgeColor, will not be searched, which can be used to speed up the search. See IsDrawable for more information. If false, all objects will be searched.
object_type	Object type for the object type search. Only objects of this type will be matched.
object_name	Object name for the object name search. Only objects with this name will be matched.
resource_name	Resource name for the RESOURCE_MATCH. "resource search". Only objects that have a resource at the resource path specified by resource_name will be matched. The resource pointed to by the resource path must be an object.
object_id	An object to be matched for the OBJECT_ID_MATCH "object ID match". Only the specified object will be matched. This type of search can be used to find out if the specified object is either a child or a parent of the object the method is invoked on.
custom_match	A function that will be invoked for each object to provide custom matching logic. The function must have the following type signature: boolean custom_match( GlgObject object ); where: object is the object to check. The function should return true if a match was detected,
search_templates	If false when searching descendants (find_parents=false), the templates of series, subdrawings and subwindows will be excluded from the search, and only the rendered instances inside these objects will be included. This is a default setting, since the template objects are not drawn and therefore do not need to be processed. If true, both the instances and the templates will be searched. This flag is ignored when the search is performed before hierarchy setup, when the instances have not yet been loaded, and only the templates are available.
dont_add_matches	If false, FindObjects returns matching objects in the found_object field. If multiple objects are found, the found_object field will contain a GLG group that is created to hold matching objects. If the custom_match function processes objects in-place, the returned group containing matching object is not used. In this case, dont_add_matches may be set to true to prevent storing matching objects at all. The DEMOS_HTML5/SCADAViewer/GlgViewer.js file in the GLG installation directory provides an example of using this setting when processing objects in-place. This setting can be used only with match_type=CUSTOM_MATCH. If dont_add_matches=true, the returned found_object field will always be null.

Returns

• null if there were no matches.
• An object containing found_object and found_multiple properties if one or more matches were found:
  • For a single match, found_object will contain the matching object and found_multiple will be set to false.
  • If several matches were found, found_object will contain a group of matching objects, and found_multiple will be set to true.

GetAction()

GlgObject GetAction	(	GlgActionType	action_type,
		GlgTriggerType	trigger_type,
		int	button,
		GlgArmedStateType	armed_state,
		GlgDoubleClickStateType	double_click_state,
		String	action,
		String	subaction,
		boolean	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,
		boolean	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.)

For efficiency, if the returned object is not null, it can be returned to the internal cache via the object's x ReleaseToCache method.

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	(	boolean	heavy_weight,
		boolean	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

(

boolean

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,
		boolean	by_name,
		boolean	unique_tags,
		boolean	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()

boolean 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: DATA_TAG EXPORT_TAG 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.

IsDrawable()

boolean 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: DATA_TAG EXPORT_TAG 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.

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	(	Function	enter_func,
		Function	exit_func
	)

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

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 must have the following type signature: boolean enter_action( GlgObject object ); where: object is the object to act upon. 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. If null is supplied as the value of the exit_func parameter, the exit function will not be used. The function must have the same type signature as enter_action and must always return true.

UnconstrainObject()

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