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

static GlgObject	CreateObject (GlgObjectType type, Object param1, Object param2, Object param3, Object param4)
	Creates a GLG object of a specified type. 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	DeleteObjectAt (int index)
	Deletes an object from the specified position in the container. More...

boolean	DeleteThisObject (Object object)
	Finds and deletes an object from 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, GlgAccessType.CURRENT, GlgPositionModifier.BEFORE );
   container.GlgAddObject( object_2, GlgAccessType.CURRENT, GlgPositionModifier.BEFORE );
   container.GlgAddObject( object_3, GlgAccessType.CURRENT, GlgPositionModifier.BEFORE );
}

The following sequence adds three objects after the target_object:

if( container.GetIndex( target_object ) != -1 )
{
   container.GlgAddObject( object_1, GlgAccessType.CURRENT, GlgPositionModifier.AFTER );
   container.GlgAddObject( object_2, GlgAccessType.CURRENT, GlgPositionModifier.AFTER );
   container.GlgAddObject( object_3, GlgAccessType.CURRENT, GlgPositionModifier.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.

◆ CreateObject()

static GlgObject CreateObject	(	GlgObjectType	type,
		Object	param1,
		Object	param2,
		Object	param3,
		Object	param4
	)

static

Creates a GLG object of a specified type.

Parameters

type	The type of a GLG object to be created, see GlgObjectType. ""
param1,param2,param3,param4	Parameters which depend on the type of the object to be created, see the table below. Trailing parameters with null values can be omitted.

Returns: New object.

Most of the entities in the GLG Toolkit, such as graphical objects, container objects, transformations and even attributes, are objects. The CreateObject method can be used to create any of these objects and is probably the most complex method 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 CreateObject.

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 CreateObject

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
POLYGON	optional number of vertices, int, 2	null	null	null
SPLINE	optional number of vertices, int, 3	null	null	null
PARALLELOGRAM	mandatory subtype, GlgParallType	null	null	null
TEXT	optional string, String, empty string	optional text subtype, GlgTextType, FIXED_TEXT	null	null
IMAGE	image filename, String, null	optional image subtype, GlgImageType, FIXED_IMAGE	null	null
GROUP ARRAY	optional element type, GlgContainerType, GLG_OBJECT	optional initial size, int, 0	null	null
LIST	optional element type, GlgContainerType, GLG_OBJECT	null	null	null
VECTOR	optional element type, GlgContainerType, GLG_OBJECT	mandatory size, int	null	null
REFERENCE	mandatory template object (null for file references), GlgObject	optional referencing type, GlgReferenceType, SUBDRAWING_REF	null	null
SERIES	mandatory template object, GlgObject	optional path transformation of any type, GlgObject, translate xform	null	null
SQUARE_SERIES	mandatory template object, GlgObject	null	null	null
CONNECTOR	mandatory connector subtype (POLYGON or ARC), GlgObjectType	optional number of points for recta-linear path or 0, int, 2	null	null
FRAME	mandatory frame subtype, GlgFrameType	mandatory frame factor, int	null	null
GIS	optional dataset file, String, null	null	null	null
DATA	mandatory data type (D, S or G), GlgDataType	optional string value (for S data only), String, null	null	null
ATTRIBUTE	mandatory data type (D, S or G), GlgDataType	mandatory attribute role, GlgRole	null	null
TAG	optional tag name, String, null	optional tag source, String, null	optional tag comment, String, null	null
XFORM	mandatory xform role, GlgRole	mandatory xform subtype, GlgXformType	Xform1 object for CONCATENATE_XF xforms or null, GlgObject, null	Xform2 object for CONCATENATE_XF xforms or null, GlgObject, null
ALIAS	optional alias name, String, null	optional resource path, String, null	null	null
HISTORY	optional resource name mask, String, null	null	optional entry point data type (D, S or G), GlgDataType, null	null
FONTTABLE	optional number of font types, int, Toolkit default	optional number of font sizes, int, Toolkit default	null	null
LINE_ATTR	optional line attributes subtype, GlgLineAttrType, LINE_NO_FILL	null	null	null

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

◆ DeleteObject()

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, GlgAccessType.CURRENT, GlgPositionModifier.AFTER, false, null );
   container.DeleteObject( null, GlgAccessType.CURRENT, GlgPositionModifier.AFTER, false, null );
   container.DeleteObject( null, GlgAccessType.CURRENT, GlgPositionModifier.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, GlgAccessType.CURRENT, GlgPositionModifier.BEFORE, false, null );
   container.DeleteObject( null, GlgAccessType.CURRENT, GlgPositionModifier.BEFORE, false, null );
   container.DeleteObject( null, GlgAccessType.CURRENT, GlgPositionModifier.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.

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

◆ DeleteThisObject()

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

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

Detailed Description

Functions

Function Documentation

◆ AddAttachmentPoint()

◆ AddObject()

◆ AddObjectAt()

◆ AddObjectToBottom()

◆ AddObjectToTop()

◆ CloneObject()

◆ ConvertViewportType()

◆ CopyObject()

◆ CreateObject()

◆ DeleteBottomObject()

◆ DeleteObject()

◆ DeleteObjectAt()

◆ DeleteThisObject()

◆ DeleteTopObject()

◆ Flush()

◆ SetAttachmentMoveMode()

◆ SetElement()

◆ SetResourceObject()

◆ SetXform()