Creating and Copying Objects

Detailed Description

This group contains functions for creating objects at run time, as well as creating copies of an object.

Functions
GlgObject	GlgCloneObject (GlgObject object, GlgCloneType clone_type)
	Creates a specialized copy (clone) of an object. More...
GlgObject	GlgCopyObject (GlgObject object)
	Creates a copy of an object. More...
GlgObject	GlgCreateObject (GlgObjectType type, char *name, GlgAnyType param1, GlgAnyType param2, GlgAnyType param3, GlgAnyType param4)
	Creates a GLG object of a specified type. More...

Function Documentation

GlgCloneObject()

GlgObject GlgCloneObject	(	GlgObject	object,
		GlgCloneType	clone_type
	)

Creates a specialized copy (clone) of an object.

Parameters

object	The object to be cloned.
clone_type	The type of cloning to perform, as described below.

Returns

A clone of the object.

This function creates a copy of the object according to the specified clone type. There are four different kinds of clones available. The difference between them depends on their treatment of the original object's attributes according to the setting of the Global flag of each attribute. There is also a special shallow clone type which can be applied only to the container objects such as groups and lists.

The following clone types are available:

• GLG_FULL_CLONE - A full clone is a copy of the original object. No attributes of the copy are constrained to the attributes of the original.
  
  
• GLG_CONSTRAINED_CLONE - A constrained clone is a copy of the original object all of whose attributes are constrained to the corresponding attributes of the original.
  Exception: The constrained clone does not constrain the attributes that have their Global flag set to GLG_UNCONSTRAINED (NONE in the Graphics Builder). This includes the constrained points of the parallelogram, frame and connector objects, the Buffer attribute of the Transfer transformation and some other special attributes.
  
  
• GLG_STRONG_CLONE A strong clone is a copy of the original object. Any of the object's attributes that are global or semi-global (have their Global flags set to GLG_GLOBAL or GLG_SEMI_GLOBAL) will be constrained to the corresponding attribute of the original.
  
  
• GLG_WEAK_CLONE - A weak clone interprets GLG_SEMI_GLOBAL to mean the same as GLG_LOCAL. It is similar to a strong clone, but only the global attributes are constrained.
  
  
• GLG_SHALLOW_CLONE A shallow clone is a special clone type that can be applied only to the container objects such as a group (GLG_ARRAY) or a list (GLG_LIST). When a shallow copy of a group is created, the copy will contain the same object IDs as the original group, as opposed to the other clone types which clone elements of the group, creating new objects with new object IDs. The shallow clone may be used by a program to create a list of objects in the original group, for example for safe traversing of the list while deleting objects from the original group.

GlgCopyObject()

GlgObject GlgCopyObject

(

GlgObject

object

)

Creates a copy of an object.

Parameters

object

The object to be copied.

Returns

A copy of the object.

This function creates and returns a copy of an object. The reference count of the created copy is set to 1. The created copy must be explicitly dereferenced using GlgDropObject after it has been used to avoid memory leaks. See GlgReferenceObject for details on reference counting.

GlgCopyObject is equivalent to using GlgCloneObject with the GLG_FULL_CLONE cloning type. Refer to GlgCloneObject for more information on cloning types.

GlgCopyObject may be used to create multiple instances of an object after the object has been created and its attributes have been set to the desired values, which saves repeated calls to the resource-setting functions.

GlgCreateObject()

GlgObject GlgCreateObject	(	GlgObjectType	type,
		char *	name,
		GlgAnyType	param1,
		GlgAnyType	param2,
		GlgAnyType	param3,
		GlgAnyType	param4
	)

Creates a GLG object of a specified type.

Parameters

type	The type of a GLG object to be created.
name	An optional argument specifying a name to be assigned to the object. This name can be used later for accessing the object and its attributes without keeping the object ID returned by GlgCreateObject. Use NULL as the value of this parameter to create an object without a name. The object's name is an editable attribute of the object, so the name can be assigned or changed later using GlgSetSResource. Using the object ID is the fastest method for accessing the object, but it requires keeping the object ID and referencing the object with to make sure it is not destroyed while the ID is being used. Using the object name to access the object via the resource mechanism is slightly slower, but it is fast enough for most applications and it ensures the proper use of the object ID.
param1,param2,param3,param4	Parameters which depend on the type of the object to be created, see the table below.

Returns

New object.

This function creates and returns an object of the specified type. The reference count of the created object is set to 1. Any created object has to be explicitly dereferenced with GlgDropObject when it is not needed any more or has been referenced by some other object (for example, adding an object to a container references the object). Refer to the description of the GlgReferenceObject function for the details on reference counting and object usage.

When an object is created, it is created with default values for its attributes. After the object has been created, the attributes may be assigned values different from the default ones using the resource access functions in the Standard API.

Most of the entities in the GLG Toolkit, such as graphical objects, container objects, transformations and even attributes, are objects. The GlgCreateObject function can be used to create any of these objects and is probably the most complex function of the API.

In practice, the GLG Graphics Builder editor provides the most convenient and fast way to create graphical objects, edit their attributes and define their dynamic and interactive behavior. Even applications that need to create objects in the drawing on the fly at run time use prebuilt graphical components instead of creating them from scratch programmatically using GlgCreateObject.

The GLG Graphics Builder is used to create graphical components that will be used as building blocks and saves them, using ether a separate drawing for each component, or a single drawing (used as a component palette) containing all of them. At run time, the application loads the components' drawings and populates the drawing by adding copies of components to the drawing at specified positions.

The GLG Air Traffic and GLG Diagram demos add dynamic objects to the drawing at run time and provide examples of this approach.

Using GlgCreateObject

The type parameter specifies the kind of object to be created. Its possible values and the usage of the accompanying data parameters are outlined in the table below.

The following table summarizes the usage of the data parameters, with a comma-separated list providing parameter description, its type and default value (if any):

Object Type	data1	data2	data3	data4
Any object type not listed below	NULL	NULL	NULL	NULL
GLG_POLYGON	optional number of vertices, int, 2	NULL	NULL	NULL
GLG_SPLINE	optional number of vertices, int, 3	NULL	NULL	NULL
GLG_PARALLELOGRAM	mandatory subtype, GlgParallType	NULL	NULL	NULL
GLG_TEXT	optional string, char *, empty string	optional text subtype, GlgTextType, GLG_FIXED_TEXT	NULL	NULL
GLG_IMAGE	image filename, char *, NULL	optional image subtype, GlgImageType, GLG_FIXED_IMAGE	NULL	NULL
GLG_GROUP GLG_ARRAY	optional element type, GlgContainerType, GLG_OBJECT	optional initial size, int, 0	NULL	NULL
GLG_LIST	optional element type, GlgContainerType, GLG_OBJECT	NULL	NULL	NULL
GLG_VECTOR	optional element type, GlgContainerType, GLG_OBJECT	mandatory size, int	NULL	NULL
GLG_REFERENCE	mandatory template object (NULL for file references), GlgObject	optional referencing type, GlgRefType, GLG_SUBDRAWING_REF	NULL	NULL
GLG_SERIES	mandatory template object, GlgObject	optional path transformation of any type, GlgObject, translate xform	NULL	NULL
GLG_SQUARE_SERIES	mandatory template object, GlgObject	NULL	NULL	NULL
GLG_CONNECTOR	mandatory connector subtype (GLG_POLYGON or GLG_ARC), GlgObjectType	optional number of points for recta-linear path or 0, int, 2	NULL	NULL
GLG_FRAME	mandatory frame subtype, GlgFrameType	mandatory frame factor, int	NULL	NULL
GLG_GIS	optional dataset file, char *, NULL	NULL	NULL	NULL
GLG_DATA	mandatory data type (GLG_D, GLG_S or GLG_G), GlgDataType	optional string value (for GLG_S data only), char *, NULL	NULL	NULL
GLG_ATTRIBUTE	mandatory data type (GLG_D, GLG_S or GLG_G), GlgDataType	mandatory attribute role, GlgXformRole	NULL	NULL
GLG_TAG	optional tag name, char *, NULL	optional tag source, char *, NULL	optional tag comment, char *, NULL	NULL
GLG_XFORM	mandatory xform role, GlgXformRole	mandatory xform subtype, GlgXformType	Xform1 object for GLG_CONCATENATE_XF xforms or NULL, GlgObject, NULL	Xform2 object for GLG_CONCATENATE_XF xforms or NULL, GlgObject, NULL
GLG_ALIAS	optional alias name, char *, NULL	optional resource path, char *, NULL	NULL	NULL
GLG_HISTORY	optional resource name mask, char *, NULL	NULL	optional entry point data type (GLG_D, GLG_S or GLG_G), GlgDataType, NULL	NULL
GLG_FONTTABLE	optional number of font types, int, Toolkit default	optional number of font sizes, int, Toolkit default	NULL	NULL
GLG_LINE_ATTR	optional line attributes subtype, GlgLineAttrType, GLG_LINE_NO_FILL	NULL	NULL	NULL

Refer to the description of the GlgCreateObject function in the GLG Programming Reference Manual for examples of creating objects of various object types.