Detailed Description

This group contains functions for adding and deleting objects from a Container.

These functions may be used to add objects or popup dialogs to the drawing at run time, well as adding points to a polygon.

The Container Functions of the Intermediate API may be used to access elements of a container.

The following files in the GLG installation directory provide examples of using container methods of the Extended API:

DEMOS/airtraffic/airtraffic.c provides an example of adding dynamic aircraft icons to the drawing at run time.
DEMOS/diagram/diagramG.c provides an example of adding objects from a palette using a point-and-click interface.
DEMOS/satellite/satellite.c provides an example of adding points to a polygon at run time.

Functions
GlgBoolean	GlgAddObject (GlgObject container, GlgAnyType object, GlgAccessType access_type, GlgPositionModifier pos_modifier)
	A generic function for adding an object to a container. More...

GlgBoolean	GlgAddObjectAt (GlgObject container, GlgObject object, GlgLong index)
	Adds an object at the specified position inside the container. More...

GlgBoolean	GlgAddObjectToBottom (GlgObject container, GlgObject object)
	Adds an object at the end of the container. More...

GlgBoolean	GlgAddObjectToTop (GlgObject container, GlgObject object)
	Adds an object at the beginning of the container. More...

GlgBoolean	GlgDeleteBottomObject (GlgObject container)
	Deletes an object from the bottom of the container. More...

GlgBoolean	GlgDeleteObject (GlgObject container, GlgAnyType object, GlgAccessType access_type, GlgPositionModifier pos_modifier)
	A generic function for deleting an object from a container. More...

GlgBoolean	GlgDeleteObjectAt (GlgObject container, GlgLong index)
	Deletes an object from the specified position in the container. More...

GlgBoolean	GlgDeleteThisObject (GlgObject container, GlgObject object)
	Finds and deletes an object from a container. More...

GlgBoolean	GlgDeleteTopObject (GlgObject container)
	Deletes an object from the beginning of the container. More...

void	GlgFlush (GlgObject container, GlgLong size)
	Set the size of the container object. More...

GlgBoolean	GlgSetElement (GlgObject container, GlgLong index, GlgObject new_object)
	Replaces the object at the specified position in a container. More...

Function Documentation

◆ GlgAddObject()

GlgBoolean GlgAddObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier
	)

A generic function for adding an object to a container.

Parameters

container	The Container object.
object	The object to be added.
access_type	The position at which the object is inserted: GLG_TOP adds the object at the beginning of the object list GLG_BOTTOM adds the object at the end of the object list GLG_CURRENT adds the object at the current position.
pos_modifier	Is used only with the GLG_CURRENT access type to control where the object is added (use 0 for other access types): GLG_BEFORE - adds the object before the object defined by the current position. GLG_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 function that accesses an element, such as GlgGetElement, GlgGetIndex, GlgGetNamedObject, GlgGetStringIndex, GlgContainsObject or GlgFindObject.

For a call to GlgAddObject immediately following the call to one of the element access functions, 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 GLG_BEFORE, the current position is left unchanged
for GLG_AFTER, the current position is incremented by 1.
This allows you to call GlgAddObject repeatedly after an initial call to one of the element access functions.

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

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgAddObject( container, object_1, GLG_CURRENT, GLG_BEFORE );
   GlgAddObject( container, object_2, GLG_CURRENT, GLG_BEFORE );
   GlgAddObject( container, object_3, GLG_CURRENT, GLG_BEFORE );
}

The following sequence adds three objects after the target_object:

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgAddObject( container, object_1, GLG_CURRENT, GLG_AFTER );
   GlgAddObject( container, object_2, GLG_CURRENT, GLG_AFTER );
   GlgAddObject( container, object_3, GLG_CURRENT, GLG_AFTER );
}

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

Follow this link for details on how added container elements are managed.

◆ GlgAddObjectAt()

GlgBoolean GlgAddObjectAt	(	GlgObject	container,
		GlgObject	object,
		GlgLong	index
	)

Adds an object at the specified position inside the container.

Parameters

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

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is 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 function can also be used to add points to a polygon object by passing the polygon as a container parameter. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

A GIS Object can also be passed as a container object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

Follow this link for details on how added container elements are managed.

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

◆ GlgAddObjectToBottom()

GlgBoolean GlgAddObjectToBottom	(	GlgObject	container,
		GlgObject	object
	)

Adds an object at the end of the container.

Parameters

container	The Container object.
object	The object to be added.

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is 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 function can also be used to add points to a polygon object by passing the polygon as a container parameter. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

A GIS Object can also be passed as a container object to add dynamic icons to be displayed on top of the map in lat/lon coordinates.

Follow this link for details on how added container elements are managed.

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

◆ GlgAddObjectToTop()

GlgBoolean GlgAddObjectToTop	(	GlgObject	container,
		GlgObject	object
	)

Adds an object at the beginning of the container.

Parameters

container	The Container object.
object	The object to be added.

Returns: Success or failure status.

This function can be used to add objects to the drawing at run time. If the container object is 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 function can also be used to add points to a polygon object by passing the polygon as a container parameter. 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.

A GIS Object can also be passed as a container 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.

Follow this link for details on how added container elements are managed.

◆ GlgDeleteBottomObject()

GlgBoolean GlgDeleteBottomObject ( GlgObject container )

Deletes an object from the bottom of the container.

Parameters

container The Container object.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

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

◆ GlgDeleteObject()

GlgBoolean GlgDeleteObject	(	GlgObject	container,
		GlgAnyType	object,
		GlgAccessType	access_type,
		GlgPositionModifier	pos_modifier
	)

A generic function for deleting an object from a container.

Parameters

container	The Container object.
object	An object to replace the deleted element with, or NULL to delete an element without replacing.
access_type	The position of the object to be deleted: GLG_TOP deletes the object at the beginning of the object list GLG_BOTTOM - deletes the object at the bottom of the object list GLG_CURRENT deletes the object at the current position.
pos_modifier	Is used only with the GLG_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 function repeatedly to delete several objects before or after the object defined by the current position: GLG_BEFORE moves the current position pointer to the previous object in the list GLG_AFTER moves the current position pointer to the next object in the list.

Returns: Success or failure status.

A container object keeps an internal current position pointer, which is set by a successful call to a function that accesses an element, such as GlgGetElement, GlgGetIndex, GlgGetNamedObject, GlgGetStringIndex, GlgContainsObject or GlgFindObject.

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

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER );
}

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

if( GlgGetIndex( container, target_object ) != -1 )
{
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
   GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );
}

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

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteObjectAt()

GlgBoolean GlgDeleteObjectAt	(	GlgObject	container,
		GlgLong	index
	)

Deletes an object from the specified position in the container.

Parameters

container	The Container object.
index	An index of the object to be deleted.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteThisObject()

GlgBoolean GlgDeleteThisObject	(	GlgObject	container,
		GlgObject	object
	)

Finds and deletes an object from a container.

Parameters

container	The Container object.
object	An object to be deleted.

Returns: True if the object was successfully deleted. If the object was not found, the function returns False without generating an error message.

Follow this link for details on how deleted container elements are managed.

◆ GlgDeleteTopObject()

GlgBoolean GlgDeleteTopObject ( GlgObject container )

Deletes an object from the beginning of the container.

Parameters

container The Container object.

Returns: Success or failure status.

Follow this link for details on how deleted container elements are managed.

◆ GlgFlush()

void GlgFlush	(	GlgObject	container,
		GlgLong	size
	)

Set the size of the container object.

Parameters

container	The Container object.
size	The new size.

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

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

Follow this link for details on how added or deleted elements are managed.

◆ GlgSetElement()

GlgBoolean GlgSetElement	(	GlgObject	container,
		GlgLong	index,
		GlgObject	new_object
	)

Replaces the object at the specified position in a container.

Parameters

container	The Container object.
index	An index of the element to be modified.
new_object	The new element value.

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

Follow this link for details on how replaced container elements are managed.