Editing Objects

Detailed Description

This group contains functions for manipulating objects at run time.

Functions
GlgObject	GlgAddAttachmentPoint (GlgObject object, double dx, double dy, double dz)
	Adds an attachment point to a reference object and returns the added point. More...
GlgObject	GlgConvertViewportType (GlgObject object)
	Converts a viewport to a light viewport, or a light viewport to a viewport. More...
GlgBoolean	GlgSetAttachmentMoveMode (GlgBoolean state)
	Changes the global attachment point move mode and returns the previous mode state. More...
GlgBoolean	GlgSetResourceObject (GlgObject object, char *resource_name, GlgObject value)
	Replaces a resource object. More...
GlgBoolean	GlgSetXform (GlgObject object, GlgObject xform)
	Adds or deletes transformations attached to an object. 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...

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.

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.

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.

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.