Detailed Description

This group contains functions of the GLG Extended API.

These functions provide methods for adding and deleting objects from the drawing at runtime, as well as for creating the drawing programmatically.

It also contains a function for tracing an object's parents by highlighting them in the drawing.

Include file: GlgApi.h

GlgObject	GlgCreateObject (GlgObjectType type, char *name, GlgAnyType param1, GlgAnyType param2, GlgAnyType param3, GlgAnyType param4)
	Creates a GLG object of a specified type. More...

GlgObject	GlgCopyObject (GlgObject object)
	Creates a copy of an object. More...

GlgObject	GlgCloneObject (GlgObject object, GlgCloneType clone_type)
	Creates a specialized copy (clone) of an object. More...

GlgObject	GlgConvertViewportType (GlgObject object)
	Converts a viewport to a light viewport, or a light viewport to a viewport. More...

GlgBoolean	GlgSetXform (GlgObject object, GlgObject xform)
	Adds or deletes transformations attached to an object. More...

GlgBoolean	GlgSetResourceObject (GlgObject object, char *resource_name, GlgObject value)
	Replaces a resource object. More...

GlgObject	GlgAddAttachmentPoint (GlgObject object, double dx, double dy, double dz)
	Adds an attachment point to a reference object and returns the added point. More...

GlgBoolean	GlgSetAttachmentMoveMode (GlgBoolean state)
	Changes the global attachment point move mode and returns the previous mode state. More...

GlgBoolean	GlgTraceObject (GlgObject object, GlgBoolean state, GlgBoolean is_widget, GlgObject top_parent, GlgBoolean(func)(GlgObject object, void data), void *data)
	Highlights all objects in the drawing that depend on the tag or resource object that is being traced. More...

GlgBoolean	GlgAddObjectToTop (GlgObject container, GlgObject object)
	Adds an object at the beginning of the container. More...

GlgBoolean	GlgAddObjectToBottom (GlgObject container, GlgObject object)
	Adds an object at the end of the container. More...

GlgBoolean	GlgAddObjectAt (GlgObject container, GlgObject object, GlgLong index)
	Adds an object at the specified position inside the container. More...

GlgBoolean	GlgAddObject (GlgObject container, GlgAnyType object, GlgAccessType access_type, GlgPositionModifier pos_modifier)
	A generic function for adding an object to a container. More...

GlgBoolean	GlgDeleteTopObject (GlgObject container)
	Deletes an object from the beginning of the container. More...

GlgBoolean	GlgDeleteBottomObject (GlgObject container)
	Deletes an object from the bottom of the container. More...

GlgBoolean	GlgDeleteThisObject (GlgObject container, GlgObject object)
	Finds and deletes an object from a container. More...

GlgBoolean	GlgDeleteObjectAt (GlgObject container, GlgLong index)
	Deletes an object from the specified position in the container. More...

GlgBoolean	GlgDeleteObject (GlgObject container, GlgAnyType object, GlgAccessType access_type, GlgPositionModifier pos_modifier)
	A generic function for deleting an object from a container. More...

void	GlgFlush (GlgObject container, GlgLong size)
	Set the size of the container object. More...

GlgBoolean	GlgSetElement (GlgObject container, GlgLong index, GlgObject new_object)
	Replaces the object at the specified position in a container. More...

Function Documentation

◆ GlgAddAttachmentPoint()

GlgObject GlgAddAttachmentPoint	(	GlgObject	object,
		double	dx,
		double	dy,
		double	dz
	)

Adds an attachment point to a reference object and returns the added point.

Parameters

object	A reference object (other than a subwindow) to add an attachment point to.
dx,dy,dz	Specify world coordinate offsets for initial position of the attachment point relatively to the reference's single control point. When the reference object is resized, the offsets will be automatically adjusted to maintain the point's position relatively to the object.

Returns: Success or failure status.

◆ GlgAddObject()

GlgBoolean GlgAddObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier
	)

A generic function for adding an object to a container.

Parameters

container	The Container object.
object	The object to be added.
access_type	The position at which the object is inserted: GLG_TOP adds the object at the beginning of the object list GLG_BOTTOM adds the object at the end of the object list GLG_CURRENT adds the object at the current position.
pos_modifier	Is used only with the GLG_CURRENT access type to control where the object is added (use 0 for other access types): GLG_BEFORE - adds the object before the object defined by the current position. GLG_AFTER adds the object after the object defined by the current position.

Returns: Success or failure status.

A container object keeps an internal current position pointer, which is set by a successful call to a function that accesses an element, such as GlgGetElement, GlgGetIndex, GlgGetNamedObject, GlgGetStringIndex, GlgContainsObject or GlgFindObject.

For a call to GlgAddObject immediately following the call to one of the element access functions, the pos_modifier parameter defines where to add the new object: right before or right after the object pointed to by the current position.

The position modifier also defines how the insert position defined by the current position pointer is adjusted after the insertion:

for GLG_BEFORE, the current position is left unchanged
for GLG_AFTER, the current position is incremented by 1.
This allows you to call GlgAddObject repeatedly after an initial call to one of the element access functions.

For example, the following sequence of calls adds three objects before the target_object:

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgAddObject( container, object_1, GLG_CURRENT, GLG_BEFORE );
   GlgAddObject( container, object_2, GLG_CURRENT, GLG_BEFORE );
   GlgAddObject( container, object_3, GLG_CURRENT, GLG_BEFORE );
}

The following sequence adds three objects after the target_object:

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgAddObject( container, object_1, GLG_CURRENT, GLG_AFTER );
   GlgAddObject( container, object_2, GLG_CURRENT, GLG_AFTER );
   GlgAddObject( container, object_3, GLG_CURRENT, GLG_AFTER );
}

Note: Any function calls that access, add or delete elements of the container may affect its current position pointer. The current position pointer must be used immediately after the function call that accesses a container's element.

Follow this link for details on how added container elements are managed.

◆ GlgAddObjectAt()

GlgBoolean GlgAddObjectAt	(	GlgObject	container,
		GlgObject	object,
		GlgLong	index
	)

Adds an object at the specified position inside the container.

Parameters

container	The Container object.
object	The object to be added.
index	The position in a container.

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is a viewport or a group inside a viewport, you may add any graphical object to it. An attempt to add a non-graphical object to a viewport or a group inside a viewport will generate an error message.

The function can also be used to add points to a polygon object by passing the polygon as a container parameter. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

A GIS Object can also be passed as a container object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

Follow this link for details on how added container elements are managed.

Objects at the end (the bottom) of the container are drawn last and will appear in front of other objects.

Note: For viewports with integrated scrolling enabled by the viewport's Pan attribute, child viewport objects added to the bottom of the viewport object list will appear in front of the integrated scrollbars until the viewport is reset. Other graphical objects added to the bottom of the container will also appear on top of the integrated scrollbars that use light viewports. Resetting the viewport reorders the scrollbars to be the last in the object list. To achieve proper rendering without resetting the viewport, use GlgAddObjectAt to add the child viewport at a proper position before the integrated scrollbars. If a single X or Y scrollbar is used, the position index will be list_size - 1, where list_size is the number of objects in the viewport. If both X and Y scrollbars are active, list_size - 3 position should be used.

◆ GlgAddObjectToBottom()

GlgBoolean GlgAddObjectToBottom	(	GlgObject	container,
		GlgObject	object
	)

Adds an object at the end of the container.

Parameters

container	The Container object.
object	The object to be added.

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is a viewport or a group inside a viewport, you may add any graphical object to it. An attempt to add a non-graphical object to a viewport or a group inside a viewport will generate an error message.

The function can also be used to add points to a polygon object by passing the polygon as a container parameter. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

A GIS Object can also be passed as a container object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

Follow this link for details on how added container elements are managed.

Objects at the end (the bottom) of the container are drawn last and will appear in front of other objects.

Note: For viewports with integrated scrolling enabled by the viewport's Pan attribute, child viewport objects added to the bottom of the viewport object list will appear in front of the integrated scrollbars until the viewport is reset. Other graphical objects added to the bottom of the container will also appear on top of the integrated scrollbars that use light viewports. Resetting the viewport reorders the scrollbars to be the last in the object list. To achieve proper rendering without resetting the viewport, use GlgAddObjectAt to add the child viewport at a proper position before the integrated scrollbars. If a single X or Y scrollbar is used, the position index will be list_size - 1, where list_size is the number of objects in the viewport. If both X and Y scrollbars are active, list_size - 3 position should be used.

◆ GlgAddObjectToTop()

GlgBoolean GlgAddObjectToTop	(	GlgObject	container,
		GlgObject	object
	)

Adds an object at the beginning of the container.

Parameters

container	The Container object.
object	The object to be added.

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is a viewport or a group inside a viewport, you may add any graphical object to it. An attempt to add a non-graphical object to a viewport or a group inside a viewport will generate an error message.

The function can also be used to add points to a polygon object by passing the polygon as a container parameter. An attempt to add an object different from a point ( an Attribute object of a G (geometrical) data type) to a polygon will generate an error message.

A GIS Object can also be passed as a container object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

Objects at the beginning (the top) of the container are drawn first and will appear behind of other objects.

Follow this link for details on how added container elements are managed.

◆ GlgCloneObject()

GlgObject GlgCloneObject	(	GlgObject	object,
		GlgCloneType	clone_type
	)

Creates a specialized copy (clone) of an object.

Parameters

object	The object to be cloned.
clone_type	The type of cloning to perform, as described below.

Returns: A clone of the object.

This function creates a copy of the object according to the specified clone type. There are four different kinds of clones available. The difference between them depends on their treatment of the original object's attributes according to the setting of the Global flag of each attribute. There is also a special shallow clone type which can be applied only to the container objects such as groups and lists.

The following clone types are available:

GLG_FULL_CLONE - A full clone is a copy of the original object. No attributes of the copy are constrained to the attributes of the original.
GLG_CONSTRAINED_CLONE - A constrained clone is a copy of the original object all of whose attributes are constrained to the corresponding attributes of the original.
Exception: The constrained clone does not constrain the attributes that have their Global flag set to GLG_UNCONSTRAINED (NONE in the Graphics Builder). This includes the constrained points of the parallelogram, frame and connector objects, the Buffer attribute of the Transfer transformation and some other special attributes.
GLG_STRONG_CLONE A strong clone is a copy of the original object. Any of the object's attributes that are global or semi-global (have their Global flags set to GLG_GLOBAL or GLG_SEMI_GLOBAL) will be constrained to the corresponding attribute of the original.
GLG_WEAK_CLONE - A weak clone interprets GLG_SEMI_GLOBAL to mean the same as GLG_LOCAL. It is similar to a strong clone, but only the global attributes are constrained.
GLG_SHALLOW_CLONE A shallow clone is a special clone type that can be applied only to the container objects such as a group (GLG_ARRAY) or a list (GLG_LIST). When a shallow copy of a group is created, the copy will contain the same object IDs as the original group, as opposed to the other clone types which clone elements of the group, creating new objects with new object IDs. The shallow clone may be used by a program to create a list of objects in the original group, for example for safe traversing of the list while deleting objects from the original group.

◆ GlgConvertViewportType()

GlgObject GlgConvertViewportType ( GlgObject object )

Converts a viewport to a light viewport, or a light viewport to a viewport.

Parameters

object A viewport or a light viewport to be converted.

Returns: A newly created object on success or NULL on error. The returned object may be dereferenced with GlgDropObject after it has been added to the drawing.

If a converted object is added to the drawing, the original object must be deleted, since both objects reuse the graphical objects inside the viewport and cannot be both displayed at the same time.

◆ GlgCopyObject()

GlgObject GlgCopyObject ( GlgObject object )

Creates a copy of an object.

Parameters

object The object to be copied.

Returns: A copy of the object.

This function creates and returns a copy of an object. The reference count of the created copy is set to 1. The created copy must be explicitly dereferenced using GlgDropObject after it has been used to avoid memory leaks. See GlgReferenceObject for details on reference counting.

GlgCopyObject is equivalent to using GlgCloneObject with the GLG_FULL_CLONE cloning type. Refer to GlgCloneObject for more information on cloning types.

GlgCopyObject may be used to create multiple instances of an object after the object has been created and its attributes have been set to the desired values, which saves repeated calls to the resource-setting functions.

◆ GlgCreateObject()

GlgObject GlgCreateObject	(	GlgObjectType	type,
		char *	name,
		GlgAnyType	param1,
		GlgAnyType	param2,
		GlgAnyType	param3,
		GlgAnyType	param4
	)

Creates a GLG object of a specified type.

Parameters

type The type of a GLG object to be created.

name

An optional argument specifying a name to be assigned to the object. This name can be used later for accessing the object and its attributes without keeping the object ID returned by GlgCreateObject. Use NULL as the value of this parameter to create an object without a name.

The object's name is an editable attribute of the object, so the name can be assigned or changed later using GlgSetSResource.

Using the object ID is the fastest method for accessing the object, but it requires keeping the object ID and referencing the object with to make sure it is not destroyed while the ID is being used. Using the object name to access the object via the resource mechanism is slightly slower, but it is fast enough for most applications and it ensures the proper use of the object ID.

param1,param2,param3,param4 Parameters which depend on the type of the object to be created, see the table below.

Returns: New object.

This function creates and returns an object of the specified type. The reference count of the created object is set to 1. Any created object has to be explicitly dereferenced with GlgDropObject when it is not needed any more or has been referenced by some other object (for example, adding an object to a container references the object). Refer to the description of the GlgReferenceObject function for the details on reference counting and object usage.

When an object is created, it is created with default values for its attributes. After the object has been created, the attributes may be assigned values different from the default ones using the resource access functions in the Standard API.

Most of the entities in the GLG Toolkit, such as graphical objects, container objects, transformations and even attributes, are objects. The GlgCreateObject function can be used to create any of these objects and is probably the most complex function of the API.

In practice, the GLG Graphics Builder editor provides the most convenient and fast way to create graphical objects, edit their attributes and define their dynamic and interactive behavior. Even applications that need to create objects in the drawing on the fly at run time use prebuilt graphical components instead of creating them from scratch programmatically using GlgCreateObject.

The GLG Graphics Builder is used to create graphical components that will be used as building blocks and saves them, using ether a separate drawing for each component, or a single drawing (used as a component palette) containing all of them. At run time, the application loads the components' drawings and populates the drawing by adding copies of components to the drawing at specified positions.

The GLG Air Traffic and GLG Diagram demos add dynamic objects to the drawing at run time and provide examples of this approach.

Using GlgCreateObject

The type parameter specifies the kind of object to be created. Its possible values and the usage of the accompanying data parameters are outlined in the table below.

The following table summarizes the usage of the data parameters, with a comma-separated list providing parameter description, its type and default value (if any):

Object Type	data1	data2	data3	data4
Any object type not listed below	NULL	NULL	NULL	NULL
GLG_POLYGON	optional number of vertices, int, 2	NULL	NULL	NULL
GLG_SPLINE	optional number of vertices, int, 3	NULL	NULL	NULL
GLG_PARALLELOGRAM	mandatory subtype, GlgParallType	NULL	NULL	NULL
GLG_TEXT	optional string, char *, empty string	optional text subtype, GlgTextType, GLG_FIXED_TEXT	NULL	NULL
GLG_IMAGE	image filename, char *, NULL	optional image subtype, GlgImageType, GLG_FIXED_IMAGE	NULL	NULL
GLG_GROUP GLG_ARRAY	optional element type, GlgContainerType, GLG_OBJECT	optional initial size, int, 0	NULL	NULL
GLG_LIST	optional element type, GlgContainerType, GLG_OBJECT	NULL	NULL	NULL
GLG_VECTOR	optional element type, GlgContainerType, GLG_OBJECT	mandatory size, int	NULL	NULL
GLG_REFERENCE	mandatory template object (NULL for file references), GlgObject	optional referencing type, GlgRefType, GLG_SUBDRAWING_REF	NULL	NULL
GLG_SERIES	mandatory template object, GlgObject	optional path transformation of any type, GlgObject, translate xform	NULL	NULL
GLG_SQUARE_SERIES	mandatory template object, GlgObject	NULL	NULL	NULL
GLG_CONNECTOR	mandatory connector subtype (GLG_POLYGON or GLG_ARC), GlgObjectType	optional number of points for recta-linear path or 0, int, 2	NULL	NULL
GLG_FRAME	mandatory frame subtype, GlgFrameType	mandatory frame factor, int	NULL	NULL
GLG_GIS	optional dataset file, char *, NULL	NULL	NULL	NULL
GLG_DATA	mandatory data type (GLG_D, GLG_S or GLG_G), GlgDataType	optional string value (for GLG_S data only), char *, NULL	NULL	NULL
GLG_ATTRIBUTE	mandatory data type (GLG_D, GLG_S or GLG_G), GlgDataType	mandatory attribute role, GlgXformRole	NULL	NULL
GLG_TAG	optional tag name, char *, NULL	optional tag source, char *, NULL	optional tag comment, char *, NULL	NULL
GLG_XFORM	mandatory xform role, GlgXformRole	mandatory xform subtype, GlgXformType	Xform1 object for GLG_CONCATENATE_XF xforms or NULL, GlgObject, NULL	Xform2 object for GLG_CONCATENATE_XF xforms or NULL, GlgObject, NULL
GLG_ALIAS	optional alias name, char *, NULL	optional resource path, char *, NULL	NULL	NULL
GLG_HISTORY	optional resource name mask, char *, NULL	NULL	optional entry point data type (GLG_D, GLG_S or GLG_G), GlgDataType, NULL	NULL
GLG_FONTTABLE	optional number of font types, int, Toolkit default	optional number of font sizes, int, Toolkit default	NULL	NULL
GLG_LINE_ATTR	optional line attributes subtype, GlgLineAttrType, GLG_LINE_NO_FILL	NULL	NULL	NULL

Refer to the description of the GlgCreateObject function in the GLG Programming Reference Manual for examples of creating objects of various object types.

◆ GlgDeleteBottomObject()

GlgBoolean GlgDeleteBottomObject ( GlgObject container )

Deletes an object from the bottom of the container.

Parameters

container The Container object.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

Note: For viewports with integrated scrolling enabled by the viewport's Pan attribute, the last object in the viewport is one of the integrated scrollbars. Use GlgDeleteThisObject to avoid interfering with the viewport's integrated scrollbars.

◆ GlgDeleteObject()

GlgBoolean GlgDeleteObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier
	)

A generic function for deleting an object from a container.

Parameters

container	The Container object.
object	An object to replace the deleted element with, or NULL to delete an element without replacing.
access_type	The position of the object to be deleted: GLG_TOP deletes the object at the beginning of the object list GLG_BOTTOM - deletes the object at the bottom of the object list GLG_CURRENT deletes the object at the current position.
pos_modifier	Is used only with the GLG_CURRENT access type to define how to adjust the current position after the delete operation, use 0 for other access types. This parameter allows to use the function repeatedly to delete several objects before or after the object defined by the current position: GLG_BEFORE moves the current position pointer to the previous object in the list GLG_AFTER moves the current position pointer to the next object in the list.

Returns: Success or failure status.

A container object keeps an internal current position pointer, which is set by a successful call to a function that accesses an element, such as GlgGetElement, GlgGetIndex, GlgGetNamedObject, GlgGetStringIndex, GlgContainsObject or GlgFindObject.

For example, the following sequence of calls deletes target_object and the two objects after it:

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
}

The following sequence deletes the target_object and the two objects before it:

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
}

Note: Any function calls that access, add or delete elements of the container may affect its current position pointer. The current position pointer must be used immediately after the function call that accesses a container's element.

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteObjectAt()

GlgBoolean GlgDeleteObjectAt	(	GlgObject	container,
		GlgLong	index
	)

Deletes an object from the specified position in the container.

Parameters

container	The Container object.
index	An index of the object to be deleted.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteThisObject()

GlgBoolean GlgDeleteThisObject	(	GlgObject	container,
		GlgObject	object
	)

Finds and deletes an object from a container.

Parameters

container	The Container object.
object	An object to be deleted.

Returns: True if the object was successfully deleted. If the object was not found, the function returns False without generating an error message.

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteTopObject()

GlgBoolean GlgDeleteTopObject ( GlgObject container )

Deletes an object from the beginning of the container.

Parameters

container The Container object.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

◆ GlgFlush()

void GlgFlush	(	GlgObject	container,
		GlgLong	size
	)

Set the size of the container object.

Parameters

container	The Container object.
size	The new size.

This function sets the container size to the requested size. If the new size is less than the current container size, extra elements are removed. If the new size is greater than the current size, the function adds elements by making a copy of the last element in the container.

The function can only be invoked if the container has not been set up. If the container has been set up (drawn), the function must be surrounded by the GlgSuspendObject and GlgReleaseObject calls.

Follow this link for details on how added or deleted elements are managed.

◆ GlgSetAttachmentMoveMode()

GlgBoolean GlgSetAttachmentMoveMode ( GlgBoolean state )

Changes the global attachment point move mode and returns the previous mode state.

Parameters

state The state of the attachment point move mode. By default, the attachment point move mode is off (False), and moving the attachment point will move the reference object it is attached to. If the mode is on (True), moving the attachment point will change its position relatively to the reference object.

Returns: The previous state of the attachment point move mode.

◆ GlgSetElement()

GlgBoolean GlgSetElement	(	GlgObject	container,
		GlgLong	index,
		GlgObject	new_object
	)

Replaces the object at the specified position in a container.

Parameters

container	The Container object.
index	An index of the element to be modified.
new_object	The new element value.

Returns: Success or failure status. If the specified index is invalid, an error message is generated and False is returned.

Follow this link for details on how replaced container elements are managed.

◆ GlgSetResourceObject()

GlgBoolean GlgSetResourceObject	(	GlgObject	object,
		char *	resource_name,
		GlgObject	value
	)

Replaces a resource object.

This function sets or replaces the resource object specified by the resource name.

Parameters

object	The object whose resource is being set or replaced.
resource_name	A default attribute name of a resource that is being set or replaced.
value	A new resource object.

Returns: Success or failure status.

With the exception of adding or deleting data tags, this function should be used only when the object whose resource is being replaced has not been drawn yet and its object hierarchy has not been set up. If an object has been drawn, it must be suspended with GlgSuspendObject before invoking GlgSetResourceObject and released with GlgReleaseObject when finished.

The function may be used to attach custom properties (CustomData resource), history (History resource) and aliases (Aliases resource) to the object, or to replace them with new values. A container object may be used as the value to attach a list of properties or other objects.

The function may also be used to set or replace values of various resources, such as a transformation attached to an object. For example, it may be used instead of the GlgSetXform function to set the object's transformation using the "Xform" resource name. However, GlgSetResourceObject provides direct manipulation capabilities and doesn't do any error checking, making the user responsible for the proper handling of objects.

While this function provides the Extended API functionality, it may also be used with the Intermediate API for setting global configuration resources.

◆ GlgSetXform()

GlgBoolean GlgSetXform	(	GlgObject	object,
		GlgObject	xform
	)

Adds or deletes transformations attached to an object.

Parameters

object	The object to which a transformation is to be attached.
xform	A new transformation object to be attached to the object, or NULL to delete the currently attached transformation.

Returns: Success or failure status.

This function replaces the current object's transformation with a new one. A NULL pointer may be used as the value of the transformation parameter to just delete the existing transformation (use the "Xform" resource name to query the existence of the transformation with the GlgGetResourceObject function).

A transformation may be added only to a drawable object (such as a viewport, group, polygon, etc.) or to the object's attributes. Any attempt to add a transformation to a non-drawable object generates an error message.

The attributes of an object differ by their data type. It is important not to try to attach a transformation of an inappropriate type to these objects. For example, GlgSetXform fails if you try to attach a string transformation to a geometrical object.

A transformation may be added to an object only before it has been drawn. To add a transformation after the object has been drawn, use GlgSuspendObject, then use GlgReleaseObject when done. Adding a transformation without using the GlgSuspendObject function after the object has been drawn generates an error message.

◆ GlgTraceObject()

GlgBoolean GlgTraceObject	(	GlgObject	object,
		GlgBoolean	state,
		GlgBoolean	is_widget,
		GlgObject	top_parent,
		GlgBoolean()(GlgObject object, void data)	func,
		void *	data
	)

Highlights all objects in the drawing that depend on the tag or resource object that is being traced.

Parameters

object	The object to trace. The object must be set up in order to trace its dependencies.
state	True to highlight the objects in the drawing that depend on the traced object False to unhighlight them.
is_widget	True to highlight or unhighlight (depending on the state parameter) only the object's parent objects that have resource named IsWidget. False to highlight or unhighlight all parent objects.
top_parent	Non-NULL to highlight or unhighlight only the parent objects that are direct children of top_parent. NULL to highlight or unhighlight all parent objects.
func	An optional function that provides a custom condition. The function will be invoked for each parent of a traced object to check if a custom condition is satisfied. If the function returns True, the parent will be highlighted or unhighlighted depending on the value of the state parameter. Use NULL to use the default behavior.
data	Custom data passed to the func function.

Returns: True if any parents were highlighted or unhighlighted, False otherwise.

GlgTraceObject searches all parents of the traced object and highlights or unhighlights them (as directed by the state parameter) based on the specified conditions. The parent search is performed until any of the specified conditions (is_widget, top_parent or a custom criteria evaluated by the supplied function) are satisfied. If no conditions are specified, all immediate drawable parents of the traced object will be highlighted or unhighlighted.

The dependent parent objects are highlighted with an outline. The attributes of the outline are defined by the GlgHighlightPolygon global configuration resource.

Internally, object highlighting is done setting an object's HighlightFlag attribute to True. An application can also set and reset this attribute of drawable objects via the GlgSetDResource function to highlight or unhighlight individual objects of interest.