3. Extended API Methods

Detailed Description

This group contains GLG Extended API methods of the GlgObject class.

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

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

Functions
GlgObject	AddAttachmentPoint (double dx, double dy, double dz)
	Adds an attachment point to the reference object and returns the added point. More...
boolean	AddObject (Object object, GlgAccessType access_type, GlgPositionModifier pos_modifier)
	A generic method for adding an object to the container. More...
boolean	AddObjectAt (Object object, int index)
	Adds an object at the specified position inside the container. More...
boolean	AddObjectToBottom (Object object)
	Adds an object at the end of the container. More...
boolean	AddObjectToTop (Object object)
	Adds an object at the beginning of the container. More...
GlgObject	CloneObject (GlgCloneType clone_type)
	Creates a specialized copy (clone) of an object. More...
static GlgObject	ConvertViewportType (GlgObject object)
	Converts a viewport to a light viewport, or a light viewport to a viewport. More...
GlgObject	CopyObject ()
	Creates a copy of the object. More...
boolean	DeleteBottomObject ()
	Deletes an object from the bottom of the container. More...
boolean	DeleteObject (GlgAccessType access_type, GlgPositionModifier pos_modifier, boolean replace_element, Object replace_obj)
	A generic method for deleting an object from the container. More...
boolean	DeleteObject (Object object)
	Finds and deletes an object from the container. More...
boolean	DeleteObjectAt (int index)
	Deletes an object from the specified position in the container. More...
boolean	DeleteTopObject ()
	Deletes an object from the beginning of the container. More...
void	Flush (int size)
	Set the size of the container object. More...
static boolean	SetAttachmentMoveMode (boolean state)
	Changes the global attachment point move mode and returns the previous mode state. More...
boolean	SetElement (int index, Object new_object)
	Replaces the object at the specified position in the container. More...
boolean	SetResourceObject (String resource_name, GlgObject value)
	Replaces a resource object inside the object the method is invoked on. More...
boolean	SetXform (GlgObject xform)
	Adds or deletes transformations attached to the object. 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.

AddObject()

boolean AddObject	(	Object	object,
		GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier
	)

A generic method for adding an object to the container.

Parameters

object	The object to be added.
access_type	The position at which the object is inserted: TOP adds the object at the beginning of the object list BOTTOM adds the object at the end of the object list CURRENT adds the object at the current position.
pos_modifier	Is used only with the CURRENT access type to control where the object is added (use 0 for other access types): BEFORE - adds object before the object defined by the current position. 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 method that accesses an element, such as GetElement, GetIndex, GetNamedObject, GetStringIndex or ContainsObject.

For a call to AddObject immediately following the call to one of the element access methods, 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 BEFORE, the current position is left unchanged
• for AFTER, the current position is incremented by 1.
  

This allows you to call AddObject repeatedly after an initial call to one of the element access methods.

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

if( container.GetIndex( target_object ) != -1 )
{
   container.GlgAddObject( object_1, GlgObject.CURRENT, GlgObject.BEFORE );
   container.GlgAddObject( object_2, GlgObject.CURRENT, GlgObject.BEFORE );
   container.GlgAddObject( object_3, GlgObject.CURRENT, GlgObject.BEFORE );
}

The following sequence adds three objects after the target_object:

if( container.GetIndex( target_object ) != -1 )
{
   container.GlgAddObject( object_1, GlgObject.CURRENT, GlgObject.AFTER );
   container.GlgAddObject( object_2, GlgObject.CURRENT, GlgObject.AFTER );
   container.GlgAddObject( object_3, GlgObject.CURRENT, GlgObject.AFTER );
}

Note: Any method 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 method call that accesses a container's element.

AddObjectAt()

boolean AddObjectAt	(	Object	object,
		int	index
	)

Adds an object at the specified position inside the container.

Parameters

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

Returns

Success or failure status.

This method can be used to add objects to the drawing at run time. If the method is invoked on 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 method can be invoked on a polygon object to add points to it. 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.

The method can also be invoked on a GIS Object object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

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

AddObjectToBottom()

boolean AddObjectToBottom

(

Object

object

)

Adds an object at the end of the container.

Parameters

object

The object to be added.

Returns

Success or failure status.

This method can be used to add objects to the drawing at run time. If the method is invoked on 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 method can be invoked on a polygon object to add points to it. 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.

The method can also be invoked on a GIS Object object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

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

AddObjectToTop()

boolean AddObjectToTop

(

Object

object

)

Adds an object at the beginning of the container.

Parameters

object

The object to be added.

Returns

Success or failure status.

This method can be used to add objects to the drawing at run time. If the method is invoked on 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 method can be invoked on a polygon object to add points to it. 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.

The method can also be invoked on a GIS Object 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.

CloneObject()

GlgObject CloneObject

(

GlgCloneType

clone_type

)

Creates a specialized copy (clone) of an object.

Parameters

clone_type

The type of cloning to perform, as described below.

Returns

An object's clone.

This method 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:

• 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.
  
  
• 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 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.
  
  
• 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 GLOBAL or SEMI_GLOBAL) will be constrained to the corresponding attribute of the original.
  
  
• WEAK_CLONE - A weak clone interprets SEMI_GLOBAL to mean the same as LOCAL. It is similar to a strong clone, but only the global attributes are constrained.
  
  
• SHALLOW_CLONE A shallow clone is a special clone type that can be applied only to the container objects such as a group (ARRAY) or a list (LIST). When a shallow copy of a group is created, the copy will contain the same objects as the original group, as opposed to the other clone types which clone elements of the group, creating new objects. 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.

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.

CopyObject()

GlgObject CopyObject

(

)

Creates a copy of the object.

Returns

An object's copy.

This method creates and returns a copy of an object. CopyObject is equivalent to using CloneObject with the FULL_CLONE cloning type. Refer to CloneObject for more information on cloning types.

CopyObject 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 methods.

DeleteBottomObject()

boolean DeleteBottomObject

(

)

Deletes an object from the bottom of the container.

Returns

Success or failure status.

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 DeleteObject to avoid interfering with the viewport's integrated scrollbars.

DeleteObject() [1/2]

boolean DeleteObject	(	GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier,
		boolean	replace_element,
		Object	replace_obj
	)

A generic method for deleting an object from the container.

Parameters

access_type	The position of the object to be deleted: TOP deletes the object at the beginning of the object list BOTTOM deletes the object at the end of the object list CURRENT deletes the object at the current position.
pos_modifier	Is used only with the 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 method repeatedly to delete several objects before or after the object defined by the current position: BEFORE moves the current position pointer to the previous object in the list AFTER moves the current position pointer to the next object in the list.
replace_element	If true, the targeted element will be replaced with the value of the replace_obj parameter. If false, the targeted element will be deleted.
replace_obj	The object to replace the targeted element with if replace_element=true.

Returns

Success or failure status.

A container object keeps an internal current position pointer, which is set by a successful call to a method that accesses an element, such as GetElement, GetIndex, GetNamedObject, GetStringIndex or ContainsObject.

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

if( container.GetIndex( target_object ) != -1 )
{
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.AFTER, false, null );
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.AFTER, false, null );
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.AFTER, false, null );
}

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

if( container.GetIndex( target_object ) != -1 )
{
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.BEFORE, false, null );
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.BEFORE, false, null );
   container.DeleteObject( null, GlgObject.CURRENT, GlgObject.BEFORE, false, null );
}

Note: Any method 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 method call that accesses a container's element.

DeleteObject() [2/2]

boolean DeleteObject

(

Object

object

)

Finds and deletes an object from the container.

Parameters

object

An object to be deleted.

Returns

true if the object was successfully deleted. If the object was not found, the method returns false without generating an error message.

DeleteObjectAt()

boolean DeleteObjectAt

(

int

index

)

Deletes an object from the specified position in the container.

Parameters

index

An index of the object to be deleted.

Returns

Success or failure status.

DeleteTopObject()

boolean DeleteTopObject

(

)

Deletes an object from the beginning of the container.

Returns

Success or failure status.

Flush()

void Flush

(

int

size

)

Set the size of the container object.

Parameters

size	The new size.

This method 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 method adds elements by making a copy of the last element in the container.

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

SetAttachmentMoveMode()

static boolean SetAttachmentMoveMode ( boolean  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.

SetElement()

boolean SetElement	(	int	index,
		Object	new_object
	)

Replaces the object at the specified position in the container.

Parameters

index	An index of the element to be modified.
new_object	A new element value.

Returns

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

SetResourceObject()

boolean 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()

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