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
	GlgObjectC (GlgObjectC &parent, char *resource_name)
	Constructor, Intermediate API: associates this object with a named resource object inside another object. 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...
GlgCube *	GetBoxPtr (void)
	Returns an object's bounding box extent in screen coordinates. 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...
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...
GlgBoolean	Load (GlgObjectC &parent, char *resource_name=NULL)
	Finds a resource. More...
GlgObject	QueryTags (GlgTagType tag_type_mask)
	Returns a group of all tags of the requested tag type defined in the object. 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.

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.

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.

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.

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.

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.

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.