Editing Objects

Detailed Description

This group contains methods for manipulating objects at run time.

Functions
GlgObject	AddAttachmentPoint (double dx, double dy, double dz)
	Adds an attachment point to the reference object and returns the added point. More...
static GlgObject	ConvertViewportType (GlgObject object)
	Converts a viewport to a light viewport, or a light viewport to a viewport. More...
static bool	SetAttachmentMoveMode (bool state)
	Changes the global attachment point move mode and returns the previous mode state. More...
bool	SetResourceObject (String resource_name, GlgObject value)
	Replaces a resource object inside the object the method is invoked on. More...
bool	SetXform (GlgObject xform)
	Adds or deletes transformations attached to the object. More...
static bool	TraceObject (GlgObject object, bool state, bool is_widget, GlgObject top_parent, GlgObjectActionInterface action)
	Highlights all objects in the drawing that depend on the tag or resource object that is being traced. More...

Function Documentation

AddAttachmentPoint()

GlgObject AddAttachmentPoint	(	double	dx,
		double	dy,
		double	dz
	)

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

This method can be invoked on a reference objects other than a subwindow.

Parameters

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.

ConvertViewportType()

static GlgObject ConvertViewportType ( GlgObject  object )

static

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

Parameters

object

The viewport or light viewport object to be converted.

Returns

A newly created object on success or null on error.

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.

SetAttachmentMoveMode()

static bool SetAttachmentMoveMode ( bool  state )

static

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.

SetResourceObject()

bool SetResourceObject	(	String	resource_name,
		GlgObject	value
	)

Replaces a resource object inside the object the method is invoked on.

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

Parameters

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 method 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 SuspendObject before invoking SetResourceObject and released with ReleaseObject when finished.

The method 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 value to attach a list of properties or other objects.

The method 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 SetXform method to set the object's transformation using the "Xform" resource name. However, SetResourceObject provides direct manipulation capabilities and doesn't do any error checking, making the user responsible for the proper handling of objects.

While this method provides the Extended API functionality, it may also be used without the Extended API for setting global configuration resources.

SetXform()

bool SetXform

(

GlgObject

xform

)

Adds or deletes transformations attached to the object.

Parameters

xform

A new transformation object to be attached to the object the method is invoked on, or null to delete the currently attached transformation.

Returns

Success or failure status.

This method replaces the current object's transformation with a new one. null 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 GetResourceObject method).

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, SetXform 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 SuspendObject, then use ReleaseObject when done. Adding a transformation without using the SuspendObject method after the object has been drawn generates an error message.

TraceObject()

static bool TraceObject ( GlgObject  object, bool  state, bool  is_widget, GlgObject  top_parent, GlgObjectActionInterface  action  )

static

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.
action	An optional interface that provides a custom condition. The Action method of the interface will be invoked for every parent of the traced object. If the method returns true, the parent will be highlighed or unhighlighted depending on the value of the state parameter.

Returns

true if any parents were highlighted or unhighlighted, false otherwise.

TraceObject 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 action interface ) 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 SetDResource method to highlight or unhighlight individual objects of interest.