Container Methods

This group contains methods for accessing elements inside GLG container objects. More...

Detailed Description

This group contains methods for accessing elements inside GLG container objects.

Container Methods of the Extended API can be used to add or delete objects from the container at run time.

GLG Container objects include ARRAY (Dynamic Array), LIST and VECTOR objects.
The following composite objects are also containers and may be used with Container Methods:

• Viewport is a container of objects rendered inside it, which can be accessed as elements of the viewport.
• Group is a container used to group objects in a drawing.
• GIS Object is a container of GIS icons displayed on top of the map in lat/lon coordinates.
• Polygon, Spline and Connector objects are containers of their control points, which can also be accessed as their elements.

When a container object is created, one of the creation parameters is the type of elements it will contain (see GlgContainerType for more information):

• GLG_OBJECT
• STRING
• INT_VALUE
• DBL_VALUE
• NATIVE_OBJECT
• GLG_NON_DRAWABLE_OBJECT

There are three types of containers:

• ARRAY "Dynamic Array" grows its size as needed when new elements are added. It is used by objects, such as groups and viewports, that need to hold their subobjects, as well as by polygons that use it to contain their control points.
• LIST "List" provides an efficient handling in cases when elements need to be frequently added and removed. It is used by chart plots to keep their data samples.
• VECTOR "Vector" is a fixed size container mostly used by the Toolkit's internals.

There are two flavors of container methods:

• Methods that use indexing to access container's elements provide convenient access to elements of the dynamic array containers. These method still work on both arrays and lists, but are less efficient when they are used for list objects because they require traversing list elements.
  
  
• Methods that iterate a container or use its current position may be used with both dynamic array and list containers, and provide more efficient handling of list containers.

The Extended API provides additional methods for adding and deleting elements of a container.

---

Functions
boolean	ContainsObject (Object object)
	Checks if object belongs to the container. More...
Object	GetElement (int index)
	Returns element at the specified position in the container. More...
int	GetIndex (Object object)
	Returns index of the first occurrence of an object in the container. More...
GlgObject	GetNamedObject (String name)
	Finds an object with the specified name inside the container of GLG objects and returns it. More...
int	GetSize ()
	Returns size of the container object. More...
int	GetStringIndex (String search_string)
	Returns index of the first occurrence of a string in the container of the STRING type. More...
void	Inverse ()
	Inverses the order of elements inside the container object. More...
boolean	IsAt (GlgPositionType position)
	Checks the position of the iteration pointer (the current element of the container). More...
Object	Iterate ()
	Traverses the container object's elements in the forward direction. More...
Object	IterateBack ()
	Traverses the container object's elements in the backward direction. More...
boolean	ReorderElement (int current_index, int new_index)
	Changes an element's position inside the container. More...
void	SetEnd ()
	Initializes the container object for the backward traversing. More...
void	SetStart ()
	Initializes the container object for the forward traversing. More...

Function Documentation

ContainsObject()

boolean ContainsObject

(

Object

object

)

Checks if object belongs to the container.

Parameters

object

The object to search for.

Returns

true if the object is found in the container, false otherwise.

GetElement()

Object GetElement

(

int

index

)

Returns element at the specified position in the container.

Parameters

index

The element's position inside the container.

Returns

The element at the specified position.

If the specified index is invalid, an error message is generated and null is returned.

While the method provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by CreateTagList.

GetIndex()

int GetIndex

(

Object

object

)

Returns index of the first occurrence of an object in the container.

Parameters

object

The object to search for.

Returns

Index of the object, or -1 if the object was not found in the container.

GetNamedObject()

GlgObject GetNamedObject

(

String

name

)

Finds an object with the specified name inside the container of GLG objects and returns it.

Parameters

name	The object's name.

Returns

The retrieved object, of null if the named object was not found.

GetSize()

int GetSize

(

)

Returns size of the container object.

Returns

The size of the container.

For a viewport or group object, the size is the number of objects in the viewport or group. For a polygon, the size is the number of vertices.

While the method provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by CreateTagList.

GetStringIndex()

int GetStringIndex

(

String

search_string

)

Returns index of the first occurrence of a string in the container of the STRING type.

Parameters

search_string

Specifies the string content to search for using an exact match.

Returns

Index of the string, or -1 if the string was not found in the container.

Inverse()

void Inverse

(

)

Inverses the order of elements inside the container object.

IsAt()

boolean IsAt

(

GlgPositionType

position

)

Checks the position of the iteration pointer (the current element of the container).

Parameters

position

The position that is being checked.

Returns

true if the container's current position pointer matches the specified position:

• for START, true if the iteration pointer is positioned before the first element of the container, false otherwise
• for END, true if the iteration pointer is positioned past the last element of the container, false otherwise
• for FIRST, true if the iteration pointer is positioned at the first element of the container, false otherwise
• for LAST, true if the iteration pointer is positioned at the last element of the container, false otherwise.

Iterate()

Object Iterate

(

)

Traverses the container object's elements in the forward direction.

Returns

The next element of the container.

Iterate advances the iteration pointer and returns the next element of the container.

SetStart must be used to initialize the container for iterating before Iterate is invoked the first time. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the CloneObject method with the SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects that can be safely iterated while objects are added or deleted from the original container.

Alternatively, GetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

The following coding example shows how to iterate all objects in a container using Iterate:

let size = GlgGetSize( container );
if( size != 0 )
{
  container.SetStart(); // Initialize forward traversing.
  for( let i=0; i<size; ++i )
  {
     let object = container.Iterate();
     ... // Code to process the object.
  }
}

IterateBack()

Object IterateBack

(

)

Traverses the container object's elements in the backward direction.

Returns

The previous element of the container.

IterateBack decrements the iteration pointer and returns the previous element of the container.

SetEnd must be used to initialize the container for backward iteration before IterateBack is invoked the first time. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the CloneObject method with the SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects that can be safely iterated while objects are added or deleted from the original container.

Alternatively, GetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

The following coding example shows how to iterate all objects in a container in the backward direction using IterateBack:

let size = GlgGetSize( container );
if( size != 0 )
{
  container.SetEnd(); // Initialize backward traversing.
  for( let i=0; i<size; ++i )
  {
     let object = container.IterateBack();
     ... // Code to process the object.
  }
}

ReorderElement()

boolean ReorderElement	(	int	current_index,
		int	new_index
	)

Changes an element's position inside the container.

Parameters

current_index	The index of an element to be reordered.
new_index	A new element position.

Returns

Success or failure status.

This method moves the element at the old_index to the new_index position inside the container. It generates an error message and returns false if indexes are out of range.

SetEnd()

void SetEnd

(

)

Initializes the container object for the backward traversing.

The method sets the current position pointer past the last element of the container, preparing the container object for the backward traversing with IterateBack.

SetStart()

void SetStart

(

)

Initializes the container object for the forward traversing.

The method sets the current position pointer before the first element of the container, preparing the container object for the forward traversing with Iterate.