Creating and Copying Objects

Detailed Description

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

Functions
GlgObject	CloneObject (GlgCloneType clone_type)
	Creates a specialized copy (clone) of an object. More...
GlgObject	CopyObject ()
	Creates a copy of the object. More...
static GlgObject	CreateObject (GlgObjectType type, Object param1, Object param2, Object param3, Object param4)
	Creates a GLG object of a specified type. More...

Function Documentation

CloneObject()

GlgObject CloneObject

(

GlgCloneType

clone_type

)

Creates a specialized copy (clone) of an object.

Parameters

clone_type

The type of cloning to perform, as described below.

Returns

An object's clone.

This method 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:

• 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.
  
  
• 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 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.
  
  
• 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 GLOBAL or SEMI_GLOBAL) will be constrained to the corresponding attribute of the original.
  
  
• WEAK_CLONE - A weak clone interprets SEMI_GLOBAL to mean the same as LOCAL. It is similar to a strong clone, but only the global attributes are constrained.
  
  
• SHALLOW_CLONE A shallow clone is a special clone type that can be applied only to the container objects such as a group (ARRAY) or a list (LIST). When a shallow copy of a group is created, the copy will contain the same objects as the original group, as opposed to the other clone types which clone elements of the group, creating new objects. 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.

CopyObject()

GlgObject CopyObject

(

)

Creates a copy of the object.

Returns

An object's copy.

This method creates and returns a copy of an object. CopyObject is equivalent to using CloneObject with the FULL_CLONE cloning type. Refer to CloneObject for more information on cloning types.

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

CreateObject()

static GlgObject CreateObject ( GlgObjectType  type, Object  param1, Object  param2, Object  param3, Object  param4  )

static

Creates a GLG object of a specified type.

Parameters

type	The type of a GLG object to be created, see GlgObjectType. ""
param1,param2,param3,param4	Parameters which depend on the type of the object to be created, see the table below. Trailing parameters with null values can be omitted.

Returns

New object.

Most of the entities in the GLG Toolkit, such as graphical objects, container objects, transformations and even attributes, are objects. The CreateObject method can be used to create any of these objects and is probably the most complex method 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 CreateObject.

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 CreateObject

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
POLYGON	optional number of vertices, int, 2	null	null	null
SPLINE	optional number of vertices, int, 3	null	null	null
PARALLELOGRAM	mandatory subtype, GlgParallType	null	null	null
TEXT	optional string, String, empty string	optional text subtype, GlgTextType, FIXED_TEXT	null	null
IMAGE	image filename, String, null	optional image subtype, GlgImageType, FIXED_IMAGE	null	null
GROUP ARRAY	optional element type, GlgContainerType, GLG_OBJECT	optional initial size, int, 0	null	null
LIST	optional element type, GlgContainerType, GLG_OBJECT	null	null	null
VECTOR	optional element type, GlgContainerType, GLG_OBJECT	mandatory size, int	null	null
REFERENCE	mandatory template object (null for file references), GlgObject	optional referencing type, GlgReferenceType, SUBDRAWING_REF	null	null
SERIES	mandatory template object, GlgObject	optional path transformation of any type, GlgObject, translate xform	null	null
SQUARE_SERIES	mandatory template object, GlgObject	null	null	null
CONNECTOR	mandatory connector subtype (POLYGON or ARC), GlgObjectType	optional number of points for recta-linear path or 0, int, 2	null	null
FRAME	mandatory frame subtype, GlgFrameType	mandatory frame factor, int	null	null
GIS	optional dataset file, String, null	null	null	null
DATA	mandatory data type (D, S or G), GlgDataType	optional string value (for S data only), String, null	null	null
ATTRIBUTE	mandatory data type (D, S or G), GlgDataType	mandatory attribute role, GlgRole	null	null
TAG	optional tag name, String, null	optional tag source, String, null	optional tag comment, String, null	null
XFORM	mandatory xform role, GlgRole	mandatory xform subtype, GlgXformType	Xform1 object for CONCATENATE_XF xforms or null, GlgObject, null	Xform2 object for CONCATENATE_XF xforms or null, GlgObject, null
ALIAS	optional alias name, String, null	optional resource path, String, null	null	null
HISTORY	optional resource name mask, String, null	null	optional entry point data type (D, S or G), GlgDataType, null	null
FONTTABLE	optional number of font types, int, Toolkit default	optional number of font sizes, int, Toolkit default	null	null
LINE_ATTR	optional line attributes subtype, GlgLineAttrType, LINE_NO_FILL	null	null	null