Detailed Description

This group lists GLG Extended API methods of the GlgObjectC class.

These methods provide methods for adding and deleting objects from the drawing at runtime, as well as for creating the drawing programmatically.

The C Extended API contains additional C Extended API functions that can be used in the C++ code.

See GlgObjectC for a complete list of methods in all APIs.

Include file: GlgClass.h

Functions
	GlgObjectC (GlgObjectC &object, GlgCloneType clone_type=GLG_FULL_CLONE)
	Copy constructor, Extended API: Creates a copy of the object. More...

	GlgObjectC (GlgObjectType type, char *name=NULL, GlgAnyType data1=NULL, GlgAnyType data2=NULL, GlgAnyType data3=NULL, GlgAnyType data4=NULL)
	Constructor, Extended API: Creates a new object of the specified type. More...

GlgBoolean	Add (GlgObjectC &object, GlgAccessType access_type=GLG_BOTTOM, GlgPositionModifier pos_modifier=GLG_AFTER)
	A generic method for adding an object to this container. More...

GlgBoolean	AddAt (GlgObjectC &object, GlgLong index)
	Adds an object at the specified position inside this container. More...

GlgBoolean	AddToBottom (GlgObjectC &object)
	Adds an object at the end of this container. More...

GlgBoolean	AddToTop (GlgObjectC &object)
	Adds an object at the beginning of this container. More...

void	Copy (GlgCloneType clone_type=GLG_FULL_CLONE)
	Creates a copy of an object. More...

void	Create (GlgObjectType type, char *name=NULL, GlgAnyType data1=NULL, GlgAnyType data2=NULL, GlgAnyType data3=NULL, GlgAnyType data4=NULL)
	Creates a new GLG object of the specified type. More...

GlgBoolean	Delete (GlgObjectC *object=NULL, GlgAccessType access_type=GLG_BOTTOM, GlgPositionModifier pos_modifier=GLG_AFTER)
	A generic method for deleting an object from this container. More...

GlgBoolean	DeleteBottomObject (void)
	Deletes an object from the bottom of this container. More...

GlgBoolean	DeleteObject (GlgObjectC &object)
	Finds and deletes an object from this container. More...

GlgBoolean	DeleteObjectAt (GlgLong index)
	Deletes an object from the specified position in this container. More...

GlgBoolean	DeleteTopObject (void)
	Deletes an object from the beginning of this container. More...

GlgBoolean	SetResourceObject (char resource_name, GlgObjectC value)
	Replaces a resource object. More...

GlgBoolean	SetXform (GlgObjectC *xform)
	Adds or deletes transformations attached to an object. More...

Function Documentation

◆ GlgObjectC() [1/2]

GlgObjectC	(	GlgObjectC &	object,
		GlgCloneType	clone_type = `GLG_FULL_CLONE`
	)

Copy constructor, Extended API: Creates a copy of the object.

Parameters

object	The object to be cloned.
clone_type	The type of cloning to perform, GLG_FULL_CLONE by default.

This is a wrapper for GlgCloneObject, see GlgCloneObject for more information.

◆ GlgObjectC() [2/2]

GlgObjectC	(	GlgObjectType	type,
		char *	name = `NULL`,
		GlgAnyType	data1 = `NULL`,
		GlgAnyType	data2 = `NULL`,
		GlgAnyType	data3 = `NULL`,
		GlgAnyType	data4 = `NULL`
	)

Constructor, Extended API: Creates a new object of the specified type.

This is a wrapper for GlgCreateObject, which receives the method's parameters. See GlgCreateObject for parameter descriptions.

Parameters

type	See GlgCreateObject for parameter description.
name	See GlgCreateObject for parameter description.
data1	See GlgCreateObject for parameter description.
data2	See GlgCreateObject for parameter description.
data3	See GlgCreateObject for parameter description.
data4	See GlgCreateObject for parameter description.

◆ Add()

GlgBoolean Add	(	GlgObjectC &	object,
		GlgAccessType	access_type = `GLG_BOTTOM`,
		GlgPositionModifier	pos_modifier = `GLG_AFTER`
	)

A generic method for adding an object to this container.

This is a wrapper for GlgAddObject.

Parameters

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

For a call to Add 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 GLG_BEFORE, the current position is left unchanged
for GLG_AFTER the current position is incremented by 1.
This allows you to call Add repeatedly after an initial call to GetElement or GetIndex.

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

GlgObjectC container = ...;
if( container.GetIndex( target_object ) != -1 )
{
   container.Add( object_1, GLG_CURRENT, GLG_BEFORE );
   container.Add( object_2, GLG_CURRENT, GLG_BEFORE );
   container.Add( object_3, GLG_CURRENT, GLG_BEFORE );
}

The following sequence adds three objects after the target_object:

GlgObjectC container = ...;
if( container.GetIndex( target_object ) != -1 )
{
   container.Add( object_1, GLG_CURRENT, GLG_AFTER );
   container.Add( object_2, GLG_CURRENT, GLG_AFTER );
   container.Add( object_3, GLG_CURRENT, GLG_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 a call to a method that accesses a container's element.

◆ AddAt()

GlgBoolean AddAt	(	GlgObjectC &	object,
		GlgLong	index
	)

Adds an object at the specified position inside this container.

This is a wrapper for GlgAddObjectAt.

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

If this object is a polygon, the method can be used to add points to the polygon. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

If this object is a GIS Object, the method can also be used to add dynamic icons that will 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 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.

◆ AddToBottom()

GlgBoolean AddToBottom ( GlgObjectC & object )

Adds an object at the end of this container.

This is a wrapper for GlgAddObjectToBottom.

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

If this object is a polygon, the method can be used to add points to the polygon. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

If this object is a GIS Object, the method can also be used to add dynamic icons that will 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 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.

◆ AddToTop()

GlgBoolean AddToTop ( GlgObjectC & object )

Adds an object at the beginning of this container.

This is a wrapper for GlgAddObjectToTop.

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

If this object is a polygon, the method can be used to add points to the polygon. An attempt to add an object different from an Attribute object of a G (geometrical) data type to polygon will generate an error message.

If this object is a GIS Object, the method can also be used to add dynamic icons that will 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.

◆ Copy()

void Copy ( GlgCloneType clone_type = GLG_FULL_CLONE )

Creates a copy of an object.

Replaces the currently stored object with a copy of it.

Parameters

clone_type The type of cloning to perform, GLG_FULL_CLONE by default.

This is a wrapper for GlgCloneObject, see GlgCloneObject for more information.

◆ Create()

void Create	(	GlgObjectType	type,
		char *	name = `NULL`,
		GlgAnyType	data1 = `NULL`,
		GlgAnyType	data2 = `NULL`,
		GlgAnyType	data3 = `NULL`,
		GlgAnyType	data4 = `NULL`
	)

Creates a new GLG object of the specified type.

Replaces the previously stored object with a newly created object of the specified type. This is a wrapper for GlgCreateObject, which receives the method's parameters. See GlgCreateObject for parameter descriptions.

Parameters

type	See GlgCreateObject for parameter description.
name	See GlgCreateObject for parameter description.
data1	See GlgCreateObject for parameter description.
data2	See GlgCreateObject for parameter description.
data3	See GlgCreateObject for parameter description.
data4	See GlgCreateObject for parameter description.

◆ Delete()

GlgBoolean Delete	(	GlgObjectC *	object = `NULL`,
		GlgAccessType	access_type = `GLG_BOTTOM`,
		GlgPositionModifier	pos_modifier = `GLG_AFTER`
	)

A generic method for deleting an object from this container.

This is a wrapper for GlgDeleteObject.

Parameters

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 method 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 method that accesses an element, such as GetElement or GetIndex.

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

GlgObjectC container = ...;
if( container.GetIndex( target_object ) != -1 )
{
   container.Delete( NULL, GLG_CURRENT, GLG_AFTER );
   container.Delete( NULL, GLG_CURRENT, GLG_AFTER );
   container.Delete( NULL, GLG_CURRENT, GLG_AFTER );
}

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

GlgObjectC container = ...;
if( container.GetIndex( target_object ) != -1 )
{
   container.Delete( NULL, GLG_CURRENT, GLG_BEFORE );
   container.Delete( NULL, GLG_CURRENT, GLG_BEFORE );
   container.Delete( NULL, GLG_CURRENT, GLG_BEFORE );
}

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 a call to a method that accesses a container's element.

◆ DeleteBottomObject()

GlgBoolean DeleteBottomObject ( void )

Deletes an object from the bottom of this container.

This is a wrapper for GlgDeleteBottomObject.

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

◆ DeleteObject()

GlgBoolean DeleteObject ( GlgObjectC & object )

Finds and deletes an object from this container.

This is a wrapper for GlgDeleteThisObject.

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.

◆ DeleteObjectAt()

GlgBoolean DeleteObjectAt ( GlgLong index )

Deletes an object from the specified position in this container.

This is a wrapper for GlgDeleteObjectAt.

Parameters

index An index of the object to be deleted.

Returns: Success or failure status.

◆ DeleteTopObject()

GlgBoolean DeleteTopObject ( void )

Deletes an object from the beginning of this container.

This is a wrapper for GlgDeleteTopObject.

Returns: Success or failure status.

◆ SetResourceObject()

GlgBoolean SetResourceObject	(	char *	resource_name,
		GlgObjectC *	value
	)

Replaces a resource object.

This is a wrapper for GlgSetResourceObject.

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.

This method sets or replaces the resource object specified by the resource name. It may be used to attach custom properties (CustomData resource), history (History resource) and aliases (Aliases resource) to this object, or to replace them with new values. A container object may be used as o_value to attach a list of properties or other objects. If objects have been drawn, they must be suspended with SuspendObject before using SetResourceObject and released with ReleaseObject when finished.

This method may also be used to set or replace values of other resources. 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 with the Intermediate API for setting global configuration resources.

◆ SetXform()

GlgBoolean SetXform ( GlgObjectC * xform )

Adds or deletes transformations attached to an object.

This is a wrapper for GlgSetXform.

Parameters

xform A new transformation object to be attached to this object, 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. A NULL pointer 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

◆ GlgObjectC() [1/2]

◆ GlgObjectC() [2/2]

◆ Add()

◆ AddAt()

◆ AddToBottom()

◆ AddToTop()

◆ Copy()

◆ Create()

◆ Delete()

◆ DeleteBottomObject()

◆ DeleteObject()

◆ DeleteObjectAt()

◆ DeleteTopObject()

◆ SetResourceObject()

◆ SetXform()