Object Referencing

Detailed Description

Functions
void	GlgDropObject (GlgObject object)
	Decrements an object's reference count. More...
GlgLong	GlgGetRefCount (GlgObject object)
	Returns an object's reference count. More...
GlgObject	GlgReferenceObject (GlgObject object)
	Increments an object's reference count. More...

Function Documentation

GlgDropObject()

void GlgDropObject

(

GlgObject

object

)

Decrements an object's reference count.

Parameters

object

The object to be dereferenced.

This function decreases the object's reference count by 1. If the reference count goes to 0, the object is destroyed. Destroying an object dereferences all its subsidiary objects and may destroy them as well if their reference counts become zero.

GlgDropObject should be used to dereference the object after creating, copying, loading or referencing the object, as was shown in the first coding example for the GlgReferenceObject function.

GlgGetRefCount()

GlgLong GlgGetRefCount

(

GlgObject

object

)

Returns an object's reference count.

Parameters

object

An object to query.

Returns

The object's reference count.

GlgReferenceObject()

GlgObject GlgReferenceObject

(

GlgObject

object

)

Increments an object's reference count.

Parameters

object

The object to be referenced.

Returns

The object.

This function increases the reference count of an object by 1 and returns the object's ID. The GlgDropObject function may be used to dereference the object when it is not needed any more.

When an object is created, its reference count is set to 1. Any object you create programmatically has to be explicitly dereferenced using the GlgDropObject function after the object has been used, otherwise memory leaks will occur. It is a good practice to dereference objects immediately after they have been added to a group or used as a part of other objects; this guarantees that you will not forget to dereference the object later. The following example illustrates this:

{
   // Create a polygon object with default values of the attributes.
   GlgObject polygon = GlgCreateObject( GLG_POLYGON, NULL, NULL, NULL, NULL,NULL );
 
   // Add the polygon to a group.
   GlgAddObjectToBottom( group, polygon );
 
   // Adding polygon to a group references it; we may dereference it now to let the group manage it.
   GlgDropObject( polygon );
}

Dereferencing an object does not necessarily destroy the object. The object may still be referenced by groups it was added to or by other objects that use it. An object may also be referenced programmatically to make sure it is kept around and is not destroyed automatically by the Toolkit.

The object is actually destroyed only when the last reference to it is dropped. The GlgReferenceObject function may be used to keep objects around, and to make sure that an object ID is still valid. Simply use the function to increment the reference count of the object, and then decrement the count with GlgDropObject when the object is no longer needed.

GlgReferenceObject may also be used to keep an object while it is being deleted from one group and added to another group. Deleting the object from a group decrements its reference count and may destroy the object if it is not referenced by anything else. Referencing the object using GlgReferenceObject prevents the object from being destroyed. GlgDropObject is used after the operation is completed to return the object's reference count to its initial state, as shown in the following code:

GlgReferenceObject( object ); // Keeping the object around.
 
// Deleting the object from group1 automatically dereferences the object and may destroy it if it's not referenced.
if( GlgContainsObject( group1, object ) )
  GlgDeleteThisObject( group1, object );
 
// Adding the object to the group2 automatically references it, so that it is safe to dereference it now.
GlgAddObjectToBottom( group2, object );
 
GlgDropObject( object ); // We may drop it now.

In general, it is good practice to increment the reference count of an object before performing any operation on it and then dereference the object when the operation is complete. This provides a guarantee that the object will not be inadvertently destroyed during the operation.