Container Functions

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

Detailed Description

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

Container Functions 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	GlgContainsObject (GlgObject container, GlgObject object)
	Checks if object belongs to a container. More...
GlgObject	GlgFindObject (GlgObject container, GlgAnyType object, GlgSearchType search_type, GlgAnyType reserved)
	A generic find function that finds an object in a container. More...
GlgObject	GlgGetElement (GlgObject container, GlgLong index)
	Returns the object at the specified position in a container. More...
GlgLong	GlgGetIndex (GlgObject container, GlgObject object)
	Returns index of the first occurrence of an object in a container. More...
GlgObject	GlgGetNamedObject (GlgObject container, char *name)
	Finds an object with the specified name inside the container of GLG objects and returns it. More...
GlgLong	GlgGetSize (GlgObject container)
	Returns size of a container object. More...
GlgLong	GlgGetStringIndex (GlgObject container, char *string)
	Returns index of the first occurrence of a string in a container of the GLG_STRING type. More...
void	GlgInverse (GlgObject container)
	Inverses the order of elements inside a container object. More...
GlgBoolean	GlgIsAt (GlgObject container, GlgPositionType position)
	Checks the position of the iteration pointer (the current element of the container). More...
GlgObject	GlgIterate (GlgObject container)
	Traverses the container object's elements in the forward direction. More...
GlgObject	GlgIterateBack (GlgObject container)
	Traverses the container object's elements in the backward direction. More...
GlgBoolean	GlgReorderElement (GlgObject container, GlgLong old_index, GlgLong new_index)
	Changes an element's position inside a container. More...
void	GlgSetEnd (GlgObject container)
	Initializes the container object for the backward traversing. More...
void	GlgSetStart (GlgObject container)
	Initializes the container object for the forward traversing. More...

Function Documentation

GlgContainsObject()

GlgBoolean GlgContainsObject	(	GlgObject	container,
		GlgObject	object
	)

Checks if object belongs to a container.

Parameters

container	A container object.
object	The object to search for.

Returns

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

GlgFindObject()

GlgObject GlgFindObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgSearchType	search_type,
		GlgAnyType	reserved
	)

A generic find function that finds an object in a container.

Use GlgContainsObject, GlgGetNamedObject, GlgGetElement or GlgGetIndex convenience functions for specialized tasks.

This function searches for an object based on the specified name, index, or object ID. If the object is found, the function modifies the container's internal position pointer to point to the found object and returns the object; otherwise it leaves the position pointer intact and returns NULL.

Note:The container's position pointer may be affected by another GlgFindObject call, as well as by GlgAddObject, GlgDeleteObject and other functions that search for a container element. Any function using the position pointer (GLG_CURRENT access type) must be called immediately after the GlgFindObject call before any other call which may affect the position pointer.

Parameters

container	A container object.
object	The container element to search for. Depending on the search type, it may be an object ID, object name, or object's index in the container's object list.
search_type	The search type GLG_FIND_OBJECT - Finds an object by the object ID (pass the object ID as the value of the object parameter). GLG_FIND_BY_NAME - Finds an object by its name (pass the name as the value of the object parameter). GLG_FIND_BY_INDEX - Finds an object by its position in the container object list (pass the zero-based position index as the value of the object parameter). GLG_FIND_STRING - Is used to find a string by its content in containers containing string elements. It compares string contents using the strcmp function instead of comparing just the string pointers.
reserved	A reserved parameter for future extensions; must be NULL.

Returns

The found object, or NULL.

GlgGetElement()

GlgObject GlgGetElement	(	GlgObject	container,
		GlgLong	index
	)

Returns the object at the specified position in a container.

Parameters

container	A container object.
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 function provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by GlgCreateTagList.

GlgGetIndex()

GlgLong GlgGetIndex	(	GlgObject	container,
		GlgObject	object
	)

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

Parameters

container	A container object.
object	The object to search for.

Returns

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

GlgGetNamedObject()

GlgObject GlgGetNamedObject	(	GlgObject	container,
		char *	name
	)

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

Parameters

container	A container object.
name	The object's name.

Returns

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

GlgGetSize()

GlgLong GlgGetSize

(

GlgObject

container

)

Returns size of a container object.

Parameters

container

A 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 function provides the Intermediate API functionality, it is also available in the Standard API when used with a group object returned by GlgCreateTagList.

GlgGetStringIndex()

GlgLong GlgGetStringIndex	(	GlgObject	container,
		char *	string
	)

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

Parameters

container	A container object.
string	The string content to search for using strcmp.

Returns

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

GlgInverse()

void GlgInverse

(

GlgObject

container

)

Inverses the order of elements inside a container object.

Parameters

container

A container object.

GlgIsAt()

GlgBoolean GlgIsAt	(	GlgObject	container,
		GlgPositionType	position
	)

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

Parameters

container	A container object.
position	The position that is being checked.

Returns

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

• for GLG_START, True if the iteration pointer is positioned before the first element of the container, False otherwise
• for GLG_END, True if the iteration pointer is positioned past the last element of the container, False otherwise
• for GLG_FIRST, True if the iteration pointer is positioned at the first element of the container, False otherwise
• for GLG_LAST, True if the iteration pointer is positioned at the last element of the container, False otherwise.

GlgIterate()

GlgObject GlgIterate

(

GlgObject

container

)

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

Parameters

container

A container object.

Returns

The next element of the container.

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

GlgSetStart must be used to initialize the container for iterating before GlgIterate 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 GlgCloneObject function 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, GlgGetElement 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 GlgIterate:

int size = GlgGetSize( container );
if( size != 0 )
{
  GlgSetStart( container ); // Initialize forward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObject object = GlgIterate( container );
     ... // Code to process the object.
  }
}

GlgIterateBack()

GlgObject GlgIterateBack

(

GlgObject

container

)

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

Parameters

container

A container object.

Returns

The previous element of the container.

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

GlgSetEnd must be used to initialize the container for backward iteration before GlgIterateBack 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 GlgCloneObject function 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, GlgGetElement 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 GlgIterateBack:

int size = GlgGetSize( container );
if( size != 0 )
{
  GlgSetEnd( container ); // Initialize backward traversing.
  for( int i=0; i<size; ++i )
  {
     GlgObject object = GlgIterateBack( container );
     ... // Code to process the object.
  }
}

GlgReorderElement()

GlgBoolean GlgReorderElement	(	GlgObject	container,
		GlgLong	old_index,
		GlgLong	new_index
	)

Changes an element's position inside a container.

Parameters

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

Returns

Success or failure status.

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

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 GlgReorderElement do not appear in the requested Z order.

GlgSetEnd()

void GlgSetEnd

(

GlgObject

container

)

Initializes the container object for the backward traversing.

Parameters

container

A container object.

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

GlgSetStart()

void GlgSetStart

(

GlgObject

container

)

Initializes the container object for the forward traversing.

Parameters

container

A container object.

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