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 Dynamic Array, List and Vector objects.

The following composite objects are also containers and may be used as the container parameter of the Container Functions:

• 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: GLG_OBJECT, GLG_STRING, GLG_LONG, GLG_ALLOCATED_POINTER or GLG_NON_DRAWABLE_OBJECT (see GlgContainerType for more information).

Container objects that contain GLG_OBJECT, GLG_STRING and GLG_ALLOCATED_POINTER elements manage them when the elements are added or deleted:

• GLG_OBJECT and GLG_NON_DRAWABLE_OBJECT containers reference added elements using GlgReferenceObject, and dereference them with GlgDropObject when the elements are deleted or the container itself is destroyed.
• GLG_STRING containers clone strings using GlgStrClone when they area added to the container, and free them with GlgFree when the string elements are deleted or the container itself is destroyed.
• GLG_ALLOCATED_POINTER containers free their elements with GlgFree when the elements are deleted or the container itself is destroyed.
• GLG_LONG containers may be used to store string or pointer elements without managing them: the added strings will not be cloned, and the elements will not be freed when deleted. It is then the application's responsibility to free elements of the container when they are deleted or the container is destroyed.

When element values for the GLG_STRING, GLG_LONG and GLG_ALLOCATED_POINTER containers are passed as the object parameter of the Container Functions, they can be cast to the GlgObject type to avoid compiler warnings.

There are three types of containers:

• 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 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 is a fixed size container mostly used by the Toolkit's internals.

There are two flavors of container functions:

• Functions that use indexing to access container's elements provide convenient access to elements of the dynamic array containers. These function still work on both arrays and lists, but are less efficient when they are used for list objects because they require traversing list elements.
  
  
• Functions 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 functions for adding and deleting elements of a container.

The Simple Array functions of the Standard API may be used to utilize a dynamic array functionality without the Intermediate and Extended APIs.

---

Functions
GlgBoolean	ContainsObject (GlgObjectC &object)
	Checks if object belongs to this container. More...
GlgObject	GetElement (GlgLong index)
	Returns the object at the specified position in this container. More...
GlgLong	GetIndex (GlgObjectC &object)
	Returns the index of the first occurrence of an object in this container. More...
GlgObject	GetNamedObject (char *name)
	Find and returns an object ID of the object with the specified name inside this container. More...
GlgLong	GetSize (void)
	Returns size of this container object. More...
GlgLong	GetStringIndex (char *string)
	Returns the index of the first occurrence of a string in this container of the GLG_STRING type. More...
void	Inverse ()
	Inverses the order of elements inside this container object. More...
GlgBoolean	IsContainer (void)
GlgObject	Iterate (void)
	Traverses elements of this container object in the forward direction. More...
GlgObject	IterateBack (void)
	Traverses elements of this container object in the backward direction. More...
GlgBoolean	ReorderElement (GlgLong old_index, GlgLong new_index)
	Changes an object's position inside this container. More...
void	SetEnd (void)
	Initializes this container object for the backward traversing. More...
void	SetStart (void)
	Initializes this container object for the forward traversing. More...

Function Documentation

ContainsObject()

GlgBoolean ContainsObject

(

GlgObjectC &

object

)

Checks if object belongs to this container.

Parameters

object

The object to search for.

Returns

True if the object is found in the container, False otherwise.

GetElement()

GlgObject GetElement

(

GlgLong

index

)

Returns the object at the specified position in this container.

This is a wrapper for GlgGetElement.

Parameters

index

The object's position inside the container.

Returns

The object 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()

GlgLong GetIndex

(

GlgObjectC &

object

)

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

This is a wrapper for GlgGetIndex.

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

(

char *

name

)

Find and returns an object ID of the object with the specified name inside this container.

This is a wrapper for GlgGetNamedObject.

Parameters

name	The object's name.

Returns

The object ID, of NULL if the named object was not found.

GetSize()

GlgLong GetSize

(

void

)

Returns size of this container object.

This is a wrapper for GlgGetSize.

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

GlgLong GetStringIndex

(

char *

string

)

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

Parameters

string

The string to search for.

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 this container object.

This is a wrapper for GlgInverse.

IsContainer()

GlgBoolean IsContainer

(

void

)

Returns

True if the associated GLG object is a GLG container.

Iterate()

GlgObject Iterate

(

void

)

Traverses elements of this container object in the forward direction.

This is a wrapper for GlgIterate.

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 Copy method with the GLG_SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects IDs, and it 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:

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

IterateBack()

GlgObject IterateBack

(

void

)

Traverses elements of this container object in the backward direction.

This is a wrapper for GlgIterateBack.

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 Copy method with the GLG_SHALLOW_CLONE clone type. The shallow copy will return a new container with a list of objects IDs, and it 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:

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

ReorderElement()

GlgBoolean ReorderElement	(	GlgLong	old_index,
		GlgLong	new_index
	)

Changes an object's position inside this container.

This is a wrapper for GlgReorderElement.

Parameters

old_index	The index of an object to be reordered.
new_index	A new object position.

Returns

Success or failure status.

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

GTK Note: GTK doesn't have a notion of windows' Z order. While the GLG driver tries to maintain the window order as much as possible, windows' Z order may not be correct when a mix of the DrawingArea viewports and native widget viewports (such as a text entry, a combo box, etc.) is displayed in the GTK version of the Toolkit on Linux. This may be the reason why viewports reordered with ReorderElement do not appear in the requested Z order.

SetEnd()

void SetEnd

(

void

)

Initializes this container object for the backward traversing.

This is a wrapper for GlgSetEnd.

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

(

void

)

Initializes this container object for the forward traversing.

This is a wrapper for GlgSetStart.

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