The GLG API Library enables an application to display a GLG drawing, and animate that drawing by querying and setting resources. The GLG Extended API Library allows an application program to edit the drawing as well, creating GLG objects and object hierarchies, adding and removing constraints as well as parametric transformations. The GLG Extended API Library may be used to modify GLG drawings created using the GLG Graphics Builder. It may also be used to create new drawings from scratch. The Java version of the Toolkit uses a similar Java version of the Extended API provided by the GlgBean and GlgObject classes described in the Java Programming chapter.
Refer to the demos directory for a coding example of using the Extended API Library's functions.
Because of the abstract approach of the GLG architecture, the Extended API is small and simple, with very few functions to worry about, while still providing all the tools you need to create highly elaborate drawings. The power of the library comes from the symmetry of the architecture, where everything in a drawing is represented as a data object. This lets you use the same functions in several different combinations to obtain different effects, using the resource notation to control their actions.
In order to minimize the size of the API, all GLG functions are generic in the sense that some of their arguments are of the GlgAnyType type. The actual type of these parameters is determined dynamically at run time by their context (as defined by the values of the other parameters).
The GLG Extended API consists of the following functions:
GlgCreateObject creates a GLG object of any type.
GlgCopyObject creates a copy of an object.
GlgCloneObject creates a specialized copy (clone) of an object.
GlgLoadObject loads a GLG object from a file.
GlgLoadObjectFromImage loads a GLG object from a memory image created by the GLG Code Generation Utility.
GlgSaveObject saves a GLG object into a file.
GlgReferenceObject references an object.
GlgDropObject dereferences an object.
GlgAddObjectToTop, GlgAddObjectToBottom, GlgAddObjectAt and GlgAddObject add an object to some container object. This can be used to add an object to a group or viewport as well as to add a point to a polygon.
GlgDeleteTopObject, GlgDeleteBottomObject, GlgDeleteObjectAt, GlgDeleteThisObject and GlgDeleteObject delete an object from a container object.
GlgReorderElement changes the object's position inside a container.
GlgContainsObject finds if the object belongs to a container.
GlgGetNamedObject finds a named object in a container.
GlgGetElement returns the object at the specified index in a container.
GlgSetElement replaces the object at the specified index in a container.
GlgGetIndex returns the index of the first occurrence of the object in a container.
GlgGetStringIndex returns the index of the first occurrence of the string in a string container.
GlgFindObject finds an object in a container.
GlgGetSize queries the size of a container object.
GlgSetStart initializes a container object for traversing.
GlgIterate traverses a container object.
GlgSetXform attaches a transformation to an object or object hierarchy.
GlgGetResourceObject gets the object ID of a resource object.
GlgSetResourceObject replaces the resource with a new object.
GlgCreateResourceList returns a list of an object's resources.
GlgGetTagObject returns a tag object with a specified tag name or tag source, or a list of tags matching the specified tag name or tag source pattern.
GlgConstrainObject adds constraints.
GlgUnconstrainObject removes constraints.
GlgSuspendObject suspends the object for editing.
GlgReleaseObject releases the object after editing.
GlgGetParent returns an object's parent object, if one exists.
GlgGetBoxPtr returns an object's bounding box.
GlgCreateSelectionNames returns the names of all the objects intersecting a given rectangle.
GlgCreateSelectionMessage finds an object selected by a given selection criteria in a rectangular area and returns the selection information as a message.
GlgCreateSelection returns an array of objects intersecting a given rectangle.
GlgGetDrawingMatrix returns the matrix corresponding to the input object.
GlgCreateInversedMatrix inverts a transformation matrix object.
GlgTransformPoint transforms a single point.
GlgCreatePointArray creates and returns an array containing all control points of an object.
GlgMoveObjectBy, GlgMoveObject, GlgScaleObject, GlgRotateObject,
GlgPositionObject, GlgFitObject and GlgTransformObject transform an object in various ways.
GlgLayoutObjects performs various alignment and layout operations.
GlgGetMatrixData and GlgSetMatrixData query and set matrix data values.
GlgScreenToWorld and GlgWorldToScreen convert coordinates between the screen and world coordinate systems.
As with the standard GLG API library, the programmer's task is made simpler by the dynamic typing of GLG objects. Most of the functions in the Extended API operate on several different kinds of objects. The action each one takes often depends on the type of its input object.
Each GLG object occupies space in the computer memory. Some objects are larger than others, but all of them take up some space. In order to make certain that only objects used by a program are kept in memory, each object is equipped with a reference count . This is simply an integer with which an object keeps track of the number of operations that care about its existence. The GLG Extended API provides functions to increase and decrease the reference count: GlgReferenceObject and GlgDropObject . When an object's reference count reaches zero, it is deleted, and its memory reclaimed.
When an object is created, its reference count is 1. Adding the object to a group increases its reference count, making sure that the object is kept around while it is needed. If you want the object to be deleted when the group is deleted, you can decrease the reference count once that object is safely contained in the group. This restores the reference count to 1. This is the standard sequence for creating GLG objects: create object, place in group or viewport, drop reference count. If the group is deleted or exploded, its members may be deleted, unless they are referenced beforehand.
An object is "responsible" for managing the reference count of its subsidiary objects. For example, a polygon object is responsible for managing the reference counts of its attribute objects. Similarly, when an object is inserted into a container, the container increments that object's reference count. When the object is removed from the group, its reference count is decremented. (Note that this can cause an object to be inadvertently deleted if the group was the only current reference to the object. If you want to remove an object from a group and put it somewhere else, you must increment its reference count before removing it.)
If these guidelines are met, any object with a reference count of zero may be safely deleted, and its memory reclaimed. This will prevent memory leaks, keeping all the system's memory available to the application.
To use any of the functions described in this chapter, the application program must include the function definitions from the GLG API header file. Use the following line to include those definitions:
#include "GlgApi.h"Creates a GLG object of any type.
GlgObject GlgCreateObject( type, name, data1, data2, data3, data4 ) GlgObjectType type; char * name; GlgAnyType data1; GlgAnyType data2; GlgAnyType data3; GlgAnyType data4;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 the resource access functions.
Using the object ID is the fastest method for accessing the object, but it requires keeping the object ID and referencing the object 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.
Parameters which depend on the type of the object to be created. These are described below.
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 when it is not needed any more or has been referenced by some other object (for example, adding an object to a group references the object). Refer to the description of the GlgReferenceObject function for the details on reference counting and object usage.
Most of the entities in the GLG Toolkit, such as graphical objects, container objects, transformations and even attributes, are objects. The GlgCreateObject function is used to create any of these objects and is probably the most complex function of the API.
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. More detailed descriptions of their use follow the table.
The following table summarizes the usage of the data parameters:
|
mandatory for all reference types (use NULL for file references) |
||||
Some object types, such as the attribute, font, and colortable, are not included in the table, or in the lists below. These objects types are created automatically when you create some other objects. For example, creating a polygon object automatically creates all the necessary attribute objects including the specified number of points. After a polygon object has been created, the polygon's attribute objects may be accessed and their values may be changed through the resource mechanism.
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.
Graphical objects are displayable objects used to represent graphical shapes in the drawing.The usage of the GlgCreateObject data parameters for the graphical objects is outlined in the following list:
data1
Specifies a
mandatory
connector subtype (
GlgObjectType
) which may have the following values:
GLG_POLYGON
Recta-linear connectors
data2
An optional number of control points for the recta-linear connectors (use NULL for arc connectors). The default value
for the recta-linear connectors is 2, resulting in one path segment connecting the two control points
. By using a value greater then two, more then one path segment is produced (i.e. using a value of 4 yields 3 path segments connecting 4 control points).
data3
,
data4
Not used. Use NULL for each parameter's value.
data1
Specifies a
mandatory
frame subtype (
GlgFrameType
), which can have the following values:
Refer to GLG Objects for the details on the frame subtypes. The point frame is the same as a free frame with only one point.
data2
Specifies a
mandatory
frame factor. The frame factor value defines the number of frame intervals, which is one smaller than the number of control points. The frame factor is a creation-time parameter and can't be changed after the frame has been created.
data1
A filename (
char*
) of an image file in GIF or BMP (Windows only) format.
data2
An optional image object subtype (
GlgImageType
) which may have the following values:
Refer to GLG Objects for details on the image subtypes. The default value is GLG_FIXED_IMAGE .
data3
,
data4
Not used. Use NULL for each parameter's value.
Specifies an optional number of polygon points ( GlgLong ). If NULL is used as the parameter's value, a default value of two (2) is used and a polygon with two points is created.
data2, data3
,
data4
Not used. Use NULL for each parameter's value.
data1
An optional string (
char*
) to be assigned to the text object. The text object will create a copy of the string. Using NULL causes the default value (the empty string) to be used.
data2
The optional text object subtype (
GlgTextType
) which may have the following values:
Refer to GLG Objects for the details on the text subtypes. The default value is GLG_FIXED_TEXT .
data3
,
data4
Not used. Use NULL for each parameter's value.
The following example shows a fragment of code which creates a polygon with three points, sets values of some attributes, and adds the polygon to a viewport:
{ GlgObject polygon; /* Create a polygon with 3 points named "Polygon1". */ polygon = GlgCreateObject( GLG_POLYGON, "Polygon1", (GlgAnyType)3, 0, 0, 0 ); /* Set some of the polygon's attributes, use the default attribute values for the rest of the attributes. */ GlgSetDResource( polygon, "OpenType", (double) GLG_CLOSED ); GlgSetDResource( polygon, "FillType", (double) GLG_EDGE ); GlgSetGResource( polygon, "FillColor", /* Green */ 0., 1., 0. ); /* Add the polygon to a viewport object for displaying. */ GlgAddObject( viewport, polygon, GLG_BOTTOM, 0 ); /* The group have referenced the added polygon. Dereference the polygon to let the group manage it. This is required since any object is created with the reference count set to 1. */ GlgDropObject( polygon ); }Refer to the description of the GlgIterate function for the coding fragment showing how to set coordinates of the polygon's points.
Also refer to the demo directory for examples of complete programs using the GLG Extended Library.
A container object may hold elements of different types as defined by the creation parameters described below and may be used to keep, save, load, and copy collections of user-defined values. A container may be used to group graphical objects in the drawing, in which case the container is a graphical object which may be added to the drawing. There are two types of containers, different in their internal representation: GLG_ARRAY (dynamic array) and GLG_LIST (linked list). There is also a GLG_GROUP type, which may be used to create a container object when the internal representation of the container is not important and whose default value is GLG_ARRAY.
Other GLG objects may inherit container functionality. For example, a viewport object serves as a container of graphical objects, and a polygon is a container of points.
data1
Specifies the type of the container's elements and may have the following values:
GLG_OBJECT
for containers to hold GLG objects of any type or hierarchies of GLG objects. This may also be used to hold double floating values, strings or geometrical points in form of the GLG data or attribute objects. Objects are referenced when added to the container, and dereferenced when they are deleted or their container gets destroyed.
GLG_NON_DRAWABLE_OBJECT
ADVANCED: same as GLG_OBJECT, but used when the container object will not be drawn. This may be used for creating light-weight containers which are never added to the drawing to be displayed, as well as for creating custom properties that should not be setup. For example, if a group of custom properties contains drawable objects, it should not be setup to avoid the drawable objects being drawn when the custom properties are setup.
GLG_STRING
for containers to hold C character strings. The strings added to the container will be clones of the input strings. Note that the
GlgFindObject
and
GlgIterate
functions return pointers to the internal strings which must not be altered or freed. Deleting a string from a container will automatically free it. Empty strings and NULL pointers are allowed in the container.
GLG_LONG
for containers to hold integer values or addresses. The container's elements will be of the longest integer type and are guaranteed to hold memory pointers. The memory pointed to by a pointer is not copied or freed automatically: this must be handled by the application which uses the container.
data2
Specifies a maximum number of objects in the group (
GlgLong
). This parameter is optional and is used only for GLG_GROUP and GLG_ARRAY containers. If you know the maximum number of objects in the group in advance, you may use this parameter to slightly optimize the group's performance. If the number is not known in advance, use NULL as the parameter's value. It will not cause an error to exceed the specified number of objects in the group at run time.
data1
Specifies a
mandatory
template object (
GlgObject
). This object is replicated by the series according to the series' factors. The series objects are created with the default value of the
Factor
attribute equal to one. The same template object should not be used for more than one series.
data2
,
data3
,
data4
Not used. Use NULL as the parameter's value.
data1
A
mandatory
template object (
GlgObject
) for a container or object reference. Use NULL for file reference objects.
data2
An optional reference subtype (
GlgRefType
) which may have the following values:
GLG_REFERENCE_REF
Template and file reference objects.
Refer to GLG Objects for details on the reference subtypes. The default value is GLG_REFERENCE_REF .
data3
,
data4
Not used. Use NULL for each parameter's value.
Non-graphical objects are used to keep data values as well as control a wide variety of the visible features of graphical objects. Refer to GLG Objects of the Glg User's Guide and Builder Reference Manual for more information. The following list outlines the usage of the GlgCreateObject data parameters for non-graphical objects:
data1
Specifies a
mandatory
data type (
GlgDataType
) which may have the following values:
G data (triplet of double values to define XYZ or RGB)
data2
Specifies an optional string value for the
S
data type. Use NULL for
D
and
G
data types.
data1
Specifies a
mandatory
data type (
GlgDataType
) which may have the following values:
G attribute (triplet of double values to define XYZ or RGB)
data2
Specifies a
mandatory
attribute role (
GlgXformRole
) which may have the following values:
The attribute's role determines the type of transformations that will affect the object. Refer to GLG Objects for more information.
data1
Specifies the alias name (
char*
). This is an alternative (logical) name for accessing the resource pointed to by the alias. The default value is NULL.
data2
Specifies the resource path for the alias (
char*
). The default value is NULL.
data1
Specifies the resource name mask (
char*
) used to access resources to be scrolled. The default value is NULL.
data2
Not used. Use NULL as the parameter's value.
data3
Specifies the data type of the entry point. Possible values are GLG_D, GLG_S and GLG_G. This data type must match the data type of the resources pointed to by the resource name mask. The default value is GLG_D.
This section details procedures for creating the transformation objects. An introduction to these objects can be found in GLG Objects.
data1
Specifies the role the transformation plays in the object hierarchy (
GlgXformRole
). It is a mandatory parameter and may have the following values:
GLG_GEOM_XR - for a geometrical transformation
GLG_COLOR_XR - for a color transformation
GLG_DDATA_XR - for a scalar transformation.
GLG_SDATA_XR - for a string transformation.
The data2 parameter is a mandatory parameter, and specifies the type of the transformation ( GlgXformType ) and may have the following values. Its possible values vary with the value of the data1 parameter.
The parameters used to control a transformation are set using the resource mechanism after the creation of the corresponding transformation object. So, for example, to create a move transformation that moves a geometric object 50 units in the X direction takes two steps. First, you create a MoveX transformation object (GLG_TRANSLATE_X_XF), and only then do you set its attributes to move the desired amount. For geometric transformations, the most commonly manipulated resource is divided into two attributes, and the transformation depends on the product of the two. For a MoveX transformation, the two attributes are the X distance and the Factor attributes. This allows the application to scale to the data it is to receive.
The following transformations may be attached to an attribute of any type (D, S or G), and use the following values of the data2 parameter:
GLG_LIST_XF
The transformed value is selected from a list of values based on the transformation's index attribute, which is 0-based. When a list transformation is created, the
data3
parameter can be used to pass an array of values using a group containing GLG_ATTRIBUTE objects. The type of attribute object in the group should match the type of attribute the transformation is attached to (D, S or G).
GLG_THRESHOLD_XF
The transformed value is selected from a list of values based on the transformation's input value, which is compared with a list of thresholds. When a list transformation is created, the
data3
parameter can be used to pass an array of values using a group containing GLG_ATTRIBUTE objects. The type of attribute object in the group should match the type of attribute the transformation is attached to (D, S or G). The
data4
parameter can be used to pass an array of thresholds, which is a group containing GLG_ATTRIBUTE objects of scalar (D) type.
For a transformation attached to a scalar (D) value, the data2 values can be:
GLG_RANGE_XF
Creates a range transformation where an input range is mapped to an output range of scalars. For example, if the input range is (0,1) and the output range is (100,200), then an input value of 0.5 will produce a transformed value of 150.
GLG_TIMER_XF
Creates a timer transformation which periodically changes a value of an object's attribute to implement blinking or other types of animation.
GLG_DIVIDE_XF
The transformed value is equal to the input value divided by the
Divisor
attribute.
GLG_LINEAR_XF
The transformed value is equal to the input value times the first attribute plus the second attribute.
GLG_COMBO_XF
This transformation uses four attributes. The transformed value is multiplied by ( A * B + C ) and divided by D, where A, B, C, and D are the four transformation attributes.
GLG_TRANSFER_XF
This transformation is used to transfer a value from one attribute object to another. It can be used to implement a "one-way" constraint, where changes in one object affect another, but not vice versa. It has only two attributes. The first attribute is meant to be constrained to the source attribute, while the second may be used to attach a transformation to the constrained value.
A transformation attached to a string attribute can have the following values:
GLG_S_FORMAT_XF
Creates a FormatS transformation. The transformed value of the string attribute is equal to an input string value formatted with a format string.
GLG_D_FORMAT_XF
Creates a FormatD transformation. The transformed value of the string attribute is equal to an input scalar value formatted with a format string.
GLG_TRANSFER_XF
This is the same as the transfer transformation for scalar values, described above.
Transformations for the geometrical or color attributes can have the following values:
GLG_TRANSLATE_XYZ_XF
Create a parametric translation transformation along the specified axis or axes.
GLG_TRANSLATE_XF
Creates a parametric translation transformation defined by a vector with a start and end point.
GLG_SCALE_Z_XF
Create a parametric scale transformation; scaling affects only the specified coordinate.
GLG_SCALE_XYZ_XF
Creates a parametric scale transformation.
GLG_ROTATE_Z_XF
Create a parametric rotate transformation around the axis defined by the transformation type.
GLG_SHEAR_Z_XF
Create a parametric shear transformation; the shear amount increases along the axis defined by the transformation type.
GLG_MATRIX_XF
Creates a matrix transformation. A matrix transformation is more compact than the parametric, although its action cannot be easily controlled by accessing resources. To create a matrix transformation, first create the parametric transformation which defines the desired transformations and then use this transformation as the value of the data3 parameter. The data4 parameter is not used; use NULL for its value. After the matrix transformation has been created, the parametric transformation is not needed any more and may be dropped using the
GlgDropObject
function. To create a complex matrix transformation, a concatenation of several transformations may be used as the data3 parameter.
Once a matrix transformation is created, it can be changed with the SetResourceFromObject function.
GLG_CONCATENATE_XF
Creates a concatenate transformation; it may be a concatenation of two matrix, parametric, or concatenate transformations. In this case
data3
and
data4
should contain the two transformation objects to be linked. Since a concatenate transformation references its components, they may be dereferenced using the
GlgDropObject
function after the concatenate transformation has been created.
The order of the transformation objects in the argument list corresponds to the order in which the transformations are applied when the resulting concatenate transformation is used to draw any object. The object is transformed with the first transformation, then with the second. Either object may itself be a concatenate transformation object, containing two or more other transformations.
A transformation may be used to create several concatenate transformations. In this case the corresponding transformations of the created concatenate transformations are constrained to have the same parameter values. Use the GlgCopyObject function to create copies of the transformation before passing them to the GlgCreateObject function to avoid constraints.
GLG_PATH_XF
Creates a parametric path transformation.When a path transformation is created, the
data3
parameter can be used to pass an array of path points. This array may be extracted from any polygon with its
Array
resource. Use a copy of the array if you don't want the path of the transformation to be constrained to the path polygon. If the
data3
parameter is NULL, a default path transformation with two points is created.
The following fragment of code shows an example of creating a concatenate transformation. It creates a rotate and translate transformations and then combines them in a concatenate transformation:
{ GlgObject rotate_xform, move_xform; /* Create a rotate transformation. */ rotate_xform = GlgCreateObject( GLG_XFORM, "Rotate", GLG_GEOM_XR, GLG_ROTATE_Z_XF, NULL, NULL ); /* Change the center of rotation from a default value (0;0;0) to the value (500; 0; 0). */ GlgSetGResource( rotate_xform, "XformAttr1", 500., 0., 0. ); /* Set the rotation angle to 90 degrees. */ GlgSetDResource( rotate_xform, "XformAttr2", 90. ); /* Create a translate transformation. */ move_xform = GlgCreateObject( GLG_XFORM, "Move", GLG_GEOM_XR, GLG_TRANSLATE_X_XF, NULL, NULL ); /* Set the move amount to 500 in world coordinates. */ GlgSetDResource( move_xform, "XformAttr2", 500. ); /* Create a concatenate transformation. */ concat_xform = GlgCreateObject( GLG_XFORM, "Concat", GLG_GEOM_XR, GLG_CONCATENATE_XF, rotate_xform, move_xform ); /* Dereference transformations; we do not need them any more. */ GlgDropObject( rotate_xform ); GlgDropObject( move_xform ); }The following example shows how to create a matrix transformations using the concatenate transformation from the previous example. It creates two different matrix transformations from the same concatenate transformation using different transformation parameters:
{ GlgObject matrix_xform1, matrix_xform2; /* Set transformation parameters for the first matrix. */ GlgSetDResource( concat, "Rotate/XformAttr2", 60. ); /* Angle */ GlgSetDResource( concat, "Move/XformAttr1", 500. ); /* Amount */ /* Create the first matrix transformation. */ matrix_xform1 = GlgCreateObject( GLG_XFORM, "Matrix", GLG_GEOM_XR, GLG_MATRIX_XF, concat_xform, NULL ); /* Set transformation parameters for the second matrix. */ GlgSetDResource( concat, "Rotate/XformAttr2", 30. ); /* Angle */ GlgSetDResource( concat, "Move/XformAttr1", 1500. ); /* Amount */ /* Create the second matrix transformation. */ matrix_xform2 = GlgCreateObject( GLG_XFORM, "Matrix", GLG_GEOM_XR, GLG_MATRIX_XF, concat_xform, NULL ); /* Dereference the concatenation transformation if not needed any more. */ GlgDropObject( concat_xform ); }Refer to GLG Objects for a description of all the transformation attributes.
Add an object to a container at the specified position: top, bottom or position defined by the index.
GlgBoolean GlgAddObjectToTop( container, object ) GlgObject container; GlgObject object; GlgBoolean GlgAddObjectToBottom( container, object ) GlgObject container; GlgObject object; GlgBoolean GlgAddObjectAt( container, object, index ) GlgObject container; GlgObject object; GlgLong index;Specifies the position in a container.
These functions add an object to a container object at the specified position and return GlgTrue if the object was successfully added or GlgFalse otherwise. The container object may have different types: it may be a group, a viewport or a polygon.
If the container object is a group or viewport, you may add any graphical object to it. Any attempt to add a non-graphical object will fail and an error message will be generated. The objects at the end (the bottom) of the list are drawn last and will appear in front of other objects.
If a polygon is passed as a container object parameter to this function, you may add points to the polygon. Any attempt to add an object different from a geometrical data object will fail, generating an error message.
A generic function for adding an object to a container.
GlgBoolean GlgAddObject( container, object, access_type, pos_modifier ) GlgObject container; GlgObject object; GlgAccessType access_type; GlgPositionModifier pos_modifier;Specifies the position at which the object is inserted. This parameter may have the following values:
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 position defined by the last call to
GlgFindObject
.
Used only with the GLG_CURRENT access type and may have the following values:
GLG_BEFORE
Adds object before the object defined by the last call to
GlgFindObject
.
GLG_AFTER
Adds input object after the object defined by the last call to
GlgFindObject
.
If the access type is not GLG_CURRENT, use 0 as the value of this parameter.
This function adds an object to a container object and returns GlgTrue if the object was successfully added or GlgFalse otherwise. The container object may have different types: it may be a group, a viewport or a polygon.
If the container object is a group or viewport, you may add any graphical object to it. Any attempt to add a non-graphical object will fail and an error message will be generated. The objects at the end (the bottom) of the list are drawn last and will appear in front of other objects.
If a polygon is passed as a container object parameter to this function, you may add points to the polygon. Any attempt to add an object different from a geometrical data object will fail, generating an error message.
A container object keeps an internal current position pointer, which is set by a successful call to the GlgFindObject function. For a call to GlgAddObject immediately following the GlgFindObject call, the pos_modifier parameter defines where to add the new object: right before or right after the object returned by GlgFindObject . 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 it is incremented by 1. This allows you to call GlgAddObject repeatedly after an initial call to GlgFindObject .
For example, the following sequence of calls:
GlgFindObject( container, object_B, GLG_FIND_OBJECT, 0 ); GlgAddObject( container, object_1, GLG_CURRENT, GLG_BEFORE ); GlgAddObject( container, object_2, GLG_CURRENT, GLG_BEFORE ); GlgAddObject( container, object_3, GLG_CURRENT, GLG_BEFORE ); (object_A, object_B, object_C)results in a group with the following object order:
(object_A, object_1, object_2, object_3, object_B, object_C). GlgFindObject( container, object_B, GLG_FIND_OBJECT, 0 ); GlgAddObject( container, object_1, GLG_CURRENT, GLG_AFTER ); GlgAddObject( container, object_2, GLG_CURRENT, GLG_AFTER ); GlgAddObject( container, object_3, GLG_CURRENT, GLG_AFTER );for the same group results in:
(object_A, object_B, object_1, object_2, object_3, object_C).Keep in mind that any other calls to GlgFindObject , GlgAddObject , and GlgDeleteObject may affect the current position pointer.
Constrains an attribute or point of an object to an attribute or point of another.
GlgBoolean GlgConstrainObject( from_attribute, to_attribute ) GlgObject from_attribute; GlgObject to_attribute;
Specifies the attribute or point object to be constrained. To obtain the object ID of the from_attribute, the GlgGetResourceObject function must be used with a default resource name rather than a user-defined resource name as the last part of resource path. For example, the "
object1/FillColor
" must be used to get the object ID of the FillColor attribute of object1, and not "
object1/color1
".
For objects that have a fixed number of control points (arc, text, etc.),
use the default attribute name ( "PointN" ) to access an object's N th control point. For objects which do not have a fixed number of points (e.g. polygons), use the GlgGetElement or GlgIterate function to get its points and use them as the from_attribute.
Specifies the attribute or point to constrain to. This object may be queried by using either the default or a user-defined resource name.
This function constrains the attribute or point specified by the from_attribute parameter to the attribute or point specified by the to_attribute parameter. If two attributes are constrained, changing the value of either attribute changes the values of both. For more information about constraining, see Constraints in Structure of a GLG Drawing.
If the object whose attribute ( from_attribute) is being constrained has already been drawn, an error message will be generated. You should either constrain object attributes before drawing the object or use the GlgSuspendObject function to suspend drawn objects before constraining their attributes.
You cannot constrain any objects beside attribute objects (a control point is an attribute object as well). The from_attribute and to_attribute attribute objects should be of the same data subtype. That is, you cannot constrain a color attribute object (G type) to the line width attribute object (D type) because they have different data types.
If any of the conditions above are not satisfied, the function fails and returns GlgFalse . If constraining is successful, the function returns GlgTrue .
Note that c onstraining an attribute object causes all the attributes of the attribute object to be identical to the attributes of the object to which it is constrained, including its name, transformation and value. If a transformation is added to an attribute object, it is automatically added to all the attribute objects that are constrained to this attribute object in order to maintain the constraints. Similarly, if the object name is changed, it is automatically changed for all the objects that are constrained to the object. These changes are permanent and remain in effect even after the constraints are removed.
Checks if object belongs to a container.
GlgBoolean GlgContainsObject( container, object ) GlgObject container; GlgObject object;Specifies the object to be copied.
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 after it has been used to avoid memory leaks. Refer to the description of the GlgReferenceObject function for details on reference counting.
GlgCopyObject is equivalent to using GlgCloneObject with the FULL_CLONE cloning type. Refer to GlgCloneObject below for more details on cloning types.
The GlgCopyObject function 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. Using GlgCopyObject can also save repeated calls to the resource-setting functions.
Creates a specialized copy (clone) of an object.
GlgObject GlgCloneObject( object, clone_type ) GlgObject object; GlgCloneType clone_type;This is an enumerated value, specifying the type of clone desired. The possible value are GLG_FULL_CLONE, GLG_STRONG_CLONE, GLG_WEAK_CLONE, GLG_CONSTRAINED_CLONE and GLG_SHALLOW_CLONE.
This function creates a copy of an object, according to the rules of cloning. There are four different kinds of clones available for a given object. The difference between them depends on their treatment of the original object's attributes according to the Global flag. There is also a special shallow clone type which can be applied only to the GLG group objects.
A full clone is a copy of the original object. No attributes of the copy are constrained to the attributes of the original.
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 points of the parallelogram, frame and connector are not constrained.
A strong clone is a copy of the original object. If any of the object's attributes are global or semi-global (have their Global flags set to GLG_GLOBAL or GLG_SEMI_GLOBAL), they will be constrained to the corresponding attribute of the original.
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.
A shallow clone is a special clone type that can be applied only to the group objects. 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 the objects from the original group.
Specifies the matrix to be inverted.
Creates and returns the matrix inverse of the input one. The returned matrix must be dereferenced using GlgDropObject when not needed any more.
This function may be used to invert the drawing transformation obtained with the GlgGetDrawingMatrix function. While the drawing transformation converts world to screen coordinates, the inverse of it may be used to convert the screen coordinates of objects and object bounding boxes back to world coordinates.
Creates and returns an array containing all of an object's control points:.
GlgObject GlgCreatePointArray( object, type ) GlgObject object; GlgCoordType type;Returns a list of an object's resources.
GlgObject GlgCreateResourceList( object, list_named_res, list_def_attr, list_aliases ) GlgObject object; GlgBoolean list_named_res, list_def_attr, list_aliases;A boolean value indicating whether the returned list should include the input object's named resources.
A boolean value indicating whether the returned list should include the input object's default attributes. The resource objects referred to by the default resource names are not actually included in the list. Instead a dummy scalar data object (type D) is included whose name is the same as the default attribute.
Indicates whether the returned list should include aliases. The resource objects referred to by the aliases are not included in the list. Instead a dummy scalar data object (type D) is included whose name is the same as the alias.
This function creates and returns the array of an object's resources. The list_named_res, list_def_attr and list_aliases parameters let you choose whether the array should include named resources, default attributes, aliases or any combination of the above.
The returned array has one entry for each resource. The entries are not sorted and are listed in the order of the occurrence inside their category. The named resources (if any) are listed first, then default resources and finally the aliases. The returned array must be dereferenced when not needed any more.
For named resources, the entries are the object IDs of the resource objects themselves. For default resources and aliases, the entries are dummy scalar data objects named after the default attributes or aliases. For both types of entries, the name of the entry object is the name of the resource listed. The following code fragment shows how to print the list of resources:
GlgObject object, list, list_element; GlgLong size, i; char * name; list = GlgCreateResourceList( object, True, True, False ); if( list ) { size = GlgGetSize( list ); for( i=0; i < size; ++i ) { list_element = GlgGetElement( list, i); GlgGetSResource( list_element, "Name", name ); printf( "Resource Name: %s\n", name ); } GlgDropObject( list ); }The GlgCreateResourceList function returns the resource list on only one level of the resource hierarchy. To see the resource lists of the returned resources, invoke the GlgCreateResourceList recursively using one of the following techniques:
Use GlgCreateResourceList on the resources in the returned list. This will only work for the named resources since the default resources and aliases are represented by dummy objects.
Get the name of a resource in the returned resource list and use the GlgGetResourceObject function to obtain its object ID, then call GlgCreateResourceList with that object ID. This method is slower but will work for both named resources, default attributes and aliases.
Searches all objects inside the given rectangle for a custom event of a specified type attached to an object and returns a selection message for the first found custom event:
GlgObject GlgCreateSelectionMessage( top_vp, rectangle, selected_vp, selection_type, button ) GlgObject top_vp; GlgRectangle * rectangle; GlgObject selected_vp; GlgSelectionEventType selection_type; GlgLong button;The bounding rectangle in screen coordinates. Any graphical shape whose rendering intersects this rectangle is included in the search.
The viewport relatively to which the bounding rectangle is defined. When used with the mouse events, this is the viewport in which the mouse event occurred.
This is an enumerated value specifying the selection type. The GLG_MOVE_SELECTION value selects custom mouse move events attached to an object, GLG_CLICK_SELECTION selects mouse click events and GLG_TOOLTIP_SELECTION selects the tooltip events.
The mouse button for the GLG_CLICK_SELECTION selection type.
This function may be used in a trace callback to determine whether a mouse event was meant to trigger a custom event attached to a graphical object in a drawing. The function returns a custom event message equivalent to the custom event message received in the input callback. If no matching custom events were found, NULL is returned.
Returns a list of names of objects intersecting a given rectangle.
GlgObject GlgCreateSelectionNames( top_vp, rectangle, selected_vp ) GlgObject top_vp; GlgRectangle * rectangle; GlgObject selected_vp;The bounding rectangle in screen coordinates. Any graphical shape whose rendering intersects this rectangle is included in the selection list.
The viewport relatively to which the bounding rectangle is defined. When used with the mouse events, this is the viewport in which the mouse event occurred.
This function may be used to determine whether a mouse event was meant to select graphical objects in a drawing. The function returns an array of strings containing the names of the objects that overlap with the given rectangle completely or partially. The name string is a complete resource path name (relative to the top_vp ) which can be used get the object ID of the object:
GlgObject selected_object =This function may be called from a trace callback function to implement the custom handling of mouse events. For example, it may be used to implement the "hot spot" functionality, highlighting objects when the cursor moves over them. The function returns NULL if no objects intersect the input rectangle, or if none of the intersected objects have names. The GlgCreateSelection function described below may be used to handle unnamed objects.
The array returned by this function must be dereferenced with the GlgDropObject function when the program is finished using it.
Returns a list of the objects intersecting a given rectangle.
GlgObject GlgCreateSelection( top_vp, rectangle, selected_vp ) GlgObject top_vp; GlgRectangle * rectangle; GlgObject selected_vp;The bounding rectangle in screen coordinates. Any graphical shape whose rendering intersects this rectangle is included in the selection list.
The viewport relatively to which the bounding rectangle is defined. When used with the mouse events, this is the viewport in which the mouse event occurred.
This function is similar to the GlgCreateSelectionNames function, but it returns an array of objects instead of an array of object names. The objects in the array are listed in the reversed order compared to their drawing order, so that the objects that are at the bottom of the drawing list and are drawn on top of other objects will be listed the first in the array.
While GlgCreateSelectionNames reports both the selected objects on the bottom of the hierarchy and all their parents, this function reports only objects at the bottom and doesn't include their parents. For example, if a polygon in a group is selected, only the polygon is reported and not the group. To get information about the parents of selected objects, use the GlgGetParent function.
The function returns NULL if no objects intersect the input rectangle. The returned array must be dereferenced with the GlgDropObject function when the program is finished using it.
Delete an object from a specified position in a container: top, bottom or a position defined by an index.
GlgBoolean GlgDeleteTopObject( container ) GlgObject container; GlgBoolean GlgDeleteBottomObject( container ) GlgObject container; GlgBoolean GlgDeleteObjectAt( container, index ) GlgObject container; Glglong index;A generic function for deleting an object from a container.
GlgBoolean GlgDeleteObject( container, reserved, access_type, pos_modifier ) GlgObject container; void * reserved; GlgAccessType access_type; GlgPositionModifier pos_modifier;Specifies the position of the object to be deleted and may have the following values:
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 position defined by the last call to
GlgFindObject
.
Used only with the GLG_CURRENT access type. It defines how to adjust the current position after the delete operation. This parameter allows using the function repeatedly to delete several objects before or after the object defined by the previous call to the GlgFindObject function. It may have the following values:
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.
If the access type is not GLG_CURRENT, use 0 as the value of the parameter.
This function deletes an object from the container object and returns GlgTrue if the object was successfully deleted or GlgFalse otherwise.
The object to be deleted is defined by the access_type parameter and may be the first (GLG_TOP) or the last object (GLG_BOTTOM) in the container's object list. It may also be an object defined by the previous successful call to GlgFindObject (GLG_CURRENT).
For example, the following sequence of calls:
GlgFindObject( container, object_D, GLG_FIND_OBJECT, 0 ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_AFTER ); (object_A, object_B, object_C, object_D, object_E, object_F, object_G )results in deleting objects object_D , object_E , and object_F .
GlgFindObject( container, object_B, GLG_FIND_OBJECT, 0 ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE ); GlgDeleteObject( container, NULL, GLG_CURRENT, GLG_BEFORE );for the same group deletes objects object_D , object_C , and object_B , in that order.
Keep in mind that any other calls to GlgFindObject , GlgAddObject , and GlgDeleteObject may affect the current position pointer. The current position pointer must be used immediately after the GlgFindObject call.
Finds and deletes the object from a container.
GlgBoolean GlgDeleteThisObject( container, object ) GlgObject container; GlgObject object;Decrements an object's reference count.
void GlgDropObject( object ) GlgObject object;Specifies 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.
The GlgDropObject function 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.
A generic find function: finds an object in a container. Use GlgContainsObject , GlgGetNamedObject , GlgGetElement or GlgGetIndex convenience functions for specialized tasks.
GlgObject GlgFindObject( container, object, search_type, reserved ) GlgObject container; void * object; GlgSearchType search_type; void * reserved;Specifies the data to search for. Depending on the search type, it may be an object ID, object name, or object's index in the container's object list.
Specifies the search type and may have the following values:
GLG_FIND_OBJECT
Finds an object by the object ID (pass the object ID as the value of the
object
parameter).
GLG_FIND_BY_NAME
Find an object by its name (pass the name as the value of the object parameter).
GLG_FIND_BY_INDEX
Finds an object by its position in the container object list (pass the zero-based position index as the value of the
object
parameter).
Reserved
A reserved parameter for future extensions; must be NULL.
This function searches for an object based on the specified name, index, or object ID. If the object is found, the function modifies the container's internal position pointer to point to the found object and returns the object; otherwise it leaves the position pointer intact and returns NULL. The container's position pointer may be affected by other GlgFindObject , GlgAddObject and GlgDeleteObject calls. Any function using the position pointer ( GLG_CURRENT access type) must be called immediately after the GlgFindObject call before any other call which may affect the pointer.
Fits an object to a specified rectangular area:
GlgBoolean GlgFitObject( object, coord_type, anchoring, x, y, z ) GlgObject object; GlgCoordType coord_type; GlgBoolean keep_ratio; GlgCube * box;Specifies the coordinate system to interpret the fit area in. If GLG_SCREEN_COORD is used, the area is defined in screen pixels. If GLG_OBJECT_COORD is used, the area is defined in the GLG world coordinates.
The area to fit the object to. If the Z extent of the box is 0, 2D fitting is performed and the object is not scaled in the Z dimension. If Z extent is not 0, 3D fitting is performed.
If the parameter is set to True, the function preserves the object's X/Y ratio by using the smallest of the required X and Y scale factors for both directions. If keep_ratio is set to False, different scale factors may be used for X and Y scaling to fit the object to the box more precisely.
This function transforms the object to fit it to the area, calculating new control point values. The object's hierarchy must be setup to use this function.
The following types defined in the GlgApi.h file are used:
typedef struct _GlgCube { GlgPoint p1; /* Lower left */ GlgPoint p2; /* Upper right */ } GlgCube;Returns an object's bounding box.
GlgCube * GlgGetBoxPtr( object ) GlgObject object;Specifies the object whose bounds are to be returned.
Returns a pointer to the object's 3-D bounding box. The box boundaries are in absolute screen coordinates (pixels) and are valid only after the object has been drawn. (That is, after the hierarchy has been set up.) The returned pointer points to internal structures which are valid only while the object exists and should not be modified. The object box may be converted to world coordinates by using the GlgGetDrawingMatrix , GlgCreateInversedMatrix and GlgTransformPoint functions.
The following types defined in the GlgApi.h file are used:
typedef struct _GlgPoint { double x, y, z; } GlgPoint; typedef struct _GlgCube { GlgPoint p1; /* Lower left */ GlgPoint p2; /* Upper right */ } GlgCube;Returns the transformation matrix attached to the input object.
GlgObject GlgGetDrawingMatrix( object ) GlgObject object;Returns the transformation matrix for the set of all transformations attached to an input object. Transformation matrices are only used for geometric transformations, so this function may be called only for graphical objects, like polygons and polylines. This function must be called after the object has been drawn. (That is, after its hierarchy has been set up.) The function returns the internal matrix object which is valid only immediately after the function call. The matrix should not be modified or destroyed. To prevent the matrix from being destroyed, you may reference it with GlgReferenceObject (and dereference later), or, even better, create a copy.
Querying the drawing matrix of a viewport returns the drawing matrix used to position the viewport's control points, and not the matrix used to render the objects inside it. To get the drawing matrix the viewport uses to draw objects inside it, query the drawing list of the viewport (the Array resource of the viewport) and use it as a parameter of the GlgGetDrawingMatrix function.
Returns the object at the specified position in a container.
GlgObject GlgGetElement( container, index ) GlgObject container; GlgLong index;Returns the index of the first occurrence of an object in a container.
GlgLong GlgGetIndex( container, object) GlgObject container; GlgObject object;Returns an object ID of the object in a container with the specified name.
GlgObject GlgGetNamedObject( container, name ) GlgObject container; char * name;This function returns named objects of a container with no regards to the resource hierarchy, and is different from the GlgGetResourceObject function (which returns named resources on the current level of the resource hierarchy but not necessarily the elements of the container).
This function returns NULL if the object with the specified name wasn't found in the container.
Returns an object's parent object, if one exists.
GlgObject GlgGetParent( object, num_parents ) GlgObject object; GlgLong * num_parents;Used to return the number of parents attached to the input objects. If this is NULL on input, an error message will be generated if the object has more than one parent.
This function returns an ID for an object's parent object. For constrained objects, there may be more than one parent object. In this case, the function returns an array of parent object IDs. (This may be used to check whether an object is constrained.)
The returned object ID is a pointer to an internal data structures and it should not be dereferenced. To keep it from being destroyed when the object is destroyed, you can reference it with GlgReferenceObject (and dereference later). If the return value is an array of parents and you want to keep it around, the safer method to keep it is to create a copy. This prevents the array's elements from being modified by the GLG internals.
This function must be called after the hierarchy is created.
Returns the ID of a resource object.
GlgObject GlgGetResourceObject( object, resource_name ) GlgObject object; char * resource_name;A character string that specifies the resource name.
This function finds and returns a named resource of an object or an object ID of the object's attribute. The resource_name parameter should identify an object, such as an attribute object or a named object of a group. If the resource is not found, the function returns NULL. No error message is generated in this case, so this function can be used to query an object's existence. The object ID returned by the function is not referenced and is valid only immediately after the function call. Reference the object if the resource ID has to be stored for later use to make sure the object is not destroyed.
Queries the size of a container object.
GlgLong GlgGetSize( container ) GlgObject container;Specifies the container object.
This function returns the size of a container object. For a viewport or group object, the size is the number of objects in the viewport or group. For a polygon, the size is the number of vertices. While the function provides the Extended API functionality, it is also available in the Standard API when used with the group object.
Returns the index of the first occurrence of the string in a string container.
GlgLong GlgGetStringIndex( container, string) GlgObject container; char * string;Returns a tag object with a specified tag name or tag source, or a list of tags matching the specified tag name or tag source pattern.
GlgObject GlgGetTagObject( object, search_string, by_name, unique_tags, single_tag ) GlgObject object; char * search_string; GlgBoolean by_name; GlgBoolean unique_tags; GlgBoolean single_tag;If set to GlgTrue , the search is performed by matching the tag names, otherwise the search is done by matching the tag sources.
If set to GlgTrue , only one tag instance will be listed when several tags with the same tag name or tag source exist in the drawing, otherwise all tags with the same tag name or tag source will be included in the returned list. The parameter is ignored in the single tag mode.
Defines the single tag ( GlgTrue ) or multiple tag ( GlgFalse ) mode.
In a single tag mode, the function returns the first attribute that has a tag matching the search criteria.
In the multiple tag mode, a list containing all attributes with matching tags will be returned. The unique_tags controls if only one tag is included in case there are multiple tags with the same tag name or tag source. It is ignored in the single tag mode. The returned list must be dereferenced using GlgDropObject when it is no longer needed.
Traverses the container object.
GlgObject GlgIterate( container ) GlgObject container;Specifies the container object.
This function increments the container's current position pointer and returns the object at the current position. The function stores the traversing state in the object is not safe to use if some other functions access the container during the traversing, modifying the stored state. The GlgGetElement function is a slower but safer alternative.
The following coding example shows how to set coordinates of the first three points of a polygon object using the GlgIterate function:
{ GlgObject point; if( GlgGetSize( polygon ) < 3 ) { fprintf( stderr, "Wrong number of points." ); exit( 0 ); } GlgSetStart( polygon ); /* Initialize traversing. */ point = GlgIterate( polygon ); /* The first point */ GlgSetGResource( point, NULL, -100., -100., 0. ); point = GlgIterate( polygon ); /* The second point */ GlgSetGResource( point, NULL, 100., 100., 0. ); point = GlgIterate( polygon ); /* The third point */ GlgSetGResource( point, NULL, 100., 200., 0. ); }The above example uses an extension of the GlgSetGResource function which allows setting the value of the attribute object itself if NULL is used as a value of the resource_name parameter.
Performs operations ranging from setting the object's width and height to align and layout of groups of objects.
GlgBoolean GlgLayoutObjects( object, sel_elem, type, distance, use_box, process_subobjects ) GlgObject object; GlgObject sel_elem; GlgLayoutType type; double distance; GlgBoolean use_box; GlgBoolean process_subobjects;Specifies the anchor object for alignment operations. If null value is specified, the first encountered object in the specified alignment direction is used.
Specifies the type of the layout action to perform. May have the following values:
Align the left edge of elements within the group with the left edge of the anchor element.
Align the right edge of elements within the group with the right edge of the anchor element.
Align the center of elements within the group with the center of the anchor element horizontally.
Align the bottom edge of elements within the group with the bottom edge of the anchor element.
Align the center of elements within the group with the center of the anchor element vertically.
Set the width and height of elements within the group to the width and height of the anchor.
Equally distributes the group's elements in vertical direction as measured by the distance between their centers.
Equally distributes the group's elements in horizontal direction as measured by the distance between their centers.
If anchor is null, sets the object's height; if anchor in not null, sets the height of all elements within the group. The height is defined by the value of the distance parameter.
If anchor is null, sets the object's width; if anchor in not null, sets the width of all elements within the group. The width is defined by the value of the distance parameter.
Set vertical distance between centers of the group's elements to a value defined by the distance parameter.
Set horizontal distance between centers of the group's elements to a value defined by the distance parameter.
The distance in screen coordinates for positioning objects, depending on the layout action.
If set to True, the object's bounding box is used to align objects, otherwise the control points will be used to determine the object's extent.
Controls how to apply the layout action if the object is a group. If set to True, the action is applied to all objects contained in the group, otherwise the action (such as SET_HSIZE) is applied to the group itself.
The function returns False if errors were encountered during the requested layout action.
Loads an object from a file in GLG format.
GlgObject GlgLoadObject( filename ) char * filename;Specifies the name of the file to load the object from.
This function loads an object from the specified file and returns the object ID. If the file is not accessible or is not in the GLG save format, an error message is generated and NULL is returned. If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object has to be explicitly dereferenced after it has been used to avoid memory leaks. Refer to the description of the GlgReferenceObject function for details on the reference counting.
Loads an object from a memory image created by the GLG Code Generation Utility.
GlgObject GlgLoadObjectFromImage( image_address, image_size ) void * image_address; GlgLong image_size;Specifies the address of the drawing image generated by the GLG Code Generation Utility.
This function loads an object from the specified drawing's memory image and returns the object ID. If the memory is corrupted, an error message is generated and NULL is returned. If the object is loaded successfully, the reference count of the returned object is set to 1. The loaded object must be explicitly dereferenced after it has been used to avoid memory leaks. Refer to the description of the GlgReferenceObject function for details on the reference counting. For information about the Code Generation Utility, see GLG Programming Tools and Utilities.
NOTE: this function does not work with compressed drawing files. Save drawings with the drawing compression option disabled to use them with GlgLoadObjectFromImage .
Moves an object by a move vector:
GlgBoolean GlgMoveObject( object, coord_type, start_point, end_point ) GlgObject object; GlgCoordType coord_type; GlgPoint * start_point; GlgPoint * end_point;Specifies the coordinate system for interpreting the move vector. If GLG_SCREEN_COORD is used, the move vector is in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. If GLG_OBJECT_COORD is used, the move vector is in the GLG world coordinates.
The start point of the move vector. If the parameter is NULL, (0,0,0) is used as the start point.
The end point of the move vector.
This function moves an object's control points by the distance defined by the move vector, calculating new control point values. The object's hierarchy must be setup to use this function.
The GlgPoint data type is defined in the GlgApi.h file:
typedef struct _GlgPoint { double x, y, z; } GlgPoint;Moves an object by a move distance:
GlgBoolean GlgMoveObjectBy( object, coord_type, x, y, z ) GlgObject object; GlgCoordType coord_type; double x, y, z;Specifies the coordinate system for interpreting the move distance. If GLG_SCREEN_COORD is used, the move distance is in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. If GLG_OBJECT_COORD is used, the move distance is specified in the GLG world coordinates.
Positions an object at the specified location:
GlgBoolean GlgPositionObject( object, coord_type, anchoring, x, y, z ) GlgObject object; GlgCoordType coord_type; GlgLong anchoring; double x, y, z;Specifies the coordinate system for interpreting the position. If GLG_SCREEN_COORD is used, the position is defined in screen pixels. If GLG_OBJECT_COORD is used, the position is defined in the GLG world coordinates.
Specifies what part of the object's bounding box will be anchored at the specified position. It's formed as a bitwise "or" of the horizontal anchoring constant (GLG_LEFT, GLG_HCENTER or GLG_RIGHT) with the vertical anchoring constants (GLG_TOP, GLG_VCENTER or GLG_BOTTOM). For example, using ( GLG_TOP | GLG_LEFT ) causes the upper left corner of the object's bounding box to be positioned at the specified location.
Increments an object's reference count.
GlgObject GlgReferenceObject( object ) GlgObject object;Specifies the object to be referenced.
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:
{ GlgObject polygon; /* Create a polygon object with default values of the attributes. */ polygon = GlgCreateObject( GLG_POLYGON, NULL, NULL, NULL, NULL, NULL ); /* Add the polygon to a group. */ GlgAddObject( group, polygon, GLG_BOTTOM, 0 ); /* 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.
You can use the GlgReferenceObject function 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 the GlgDropObject function when the object is no longer needed.
The GlgReferenceObject function 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. The GlgDropObject function is used after the operation is completed to return the object's reference count to its initial state.
The following code fragment illustrates this:
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( GlgFindObject( group1, object, GLG_FIND_OBJECT, 0 ) ) GlgDeleteObject( group1, NULL, GLG_CURRENT, 0 ); /* Adding the object to the group2 automatically references it, so that it is safe to dereference it now. */ GlgAddObject( group2, object, GLG_BOTTOM, 0 ); 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.
Releases a suspended object after editing.
void GlgReleaseObject( object, suspend_info ) GlgObject object; GlgObject suspend_info;Changes the object's position inside a container.
void GlgReorderElement( container, old_index, new_index ) GlgObject object; GlgLong old_index; GlgLong new_index;Specifies the coordinate system for interpreting the rotation center. If GLG_SCREEN_COORD is used, the center is defined in screen pixels. If GLG_OBJECT_COORD is used, the center is defined in the GLG world coordinates.
The center of rotation. If the parameter is NULL, the object is rotated relative to the center of its bounding box.
The X, Y and Z rotation angles.
This function rotates an object's control points by the specified rotation angles and relative to the specified center, calculating new control point values. If more than one rotation angle is specified, X rotation is applied the first, then Y and Z. The object's hierarchy must be setup to use this function.
The GlgPoint data type is defined in the GlgApi.h file:
typedef struct _GlgPoint { double x, y, z; } GlgPoint;Specifies the name of the file to save the object into.
This function saves the specified object and all its subsidiary objects into a file. If the file is not accessible for writing, the function returns GlgFalse , otherwise it returns GlgTrue . A GLG object of any type may be saved in this fashion and later loaded using the GlgLoadObject function. You can use the GlgSaveFormat configuration resource described Appendices to modify the save type.
Specifies the coordinate system for interpreting the scale center. If GLG_SCREEN_COORD is used, the center is defined in screen pixels. If GLG_OBJECT_COORD is used, the center is defined in the GLG world coordinates.
The center of scaling. If the parameter is NULL, the object is scaled relative to the center of its bounding box.
The X, Y and Z scaling factors. Use (1,1,1) to scale the object uniformly in all dimensions.
This function scales an object's control points by the specified scale factors and relative to the specified center, calculating new control point values. The object's hierarchy must be setup to use this function.
The GlgPoint data type is defined in the GlgApi.h file:
typedef struct _GlgPoint { double x, y, z; } GlgPoint;Converts a point's coordinates from the screen to the GLG world coordinate system.
GlgBoolean GlgScreenToWorld( object, inside_vp, in_point, out_point ) GlgObject object; GlgBoolen inside_vp; GlgPoint * in_point; GlgPoint * out_point;Specifies the object whose world coordinate system to convert to. The world coordinate system of an object includes the effect of all drawing transformations attached to the object and all its parents.
For a viewport object, specifies which world coordinate system to use: the world coordinate system used to draw the viewport inside its parent viewport (inside_vp=GlgFalse), or the world coordinate system used to draw object inside the viewport (inside_vp=GlgTrue). The value of this parameter is ignored for other objects.
Replaces the object at the specified position in a container.
GlgBoolean GlgSetElement( container, index, new_object ) GlgObject container; GlgLong index; GlgObject new_object;Specifies a new resource object.
This function 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 the object, or to replace them with new values. A container object may be used as the o_value to attach a list of properties or other objects. If objects have been drawn, they must be suspended with GlgSuspendObject before using GlgSetResourceObject and released with GlgReleaseObject when finished.
This function may also be used to set or replace values of other resources. For example, it may be used instead of the GlgSetXform function to set the object's transformation using the Xform resource name. However, GlgSetResourceObject provides direct manipulation capabilities and doesn't do any error checking, making the user responsible for the proper handling of objects.
The function returns GlgTrue if the operation was successful.
Initializes the container object for traversing.
void GlgSetStart( container ) GlgObject container;Adds or deletes transformations attached to an object.
GlgBoolean GlgSetXform( object, xform ) GlgObject object; GlgObject xform;Specifies the transformation object to be attached to the object.
This function replaces the current object's transformation with a new one. The 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 GlgGetResourceObject function). The function returns GlgTrue upon successful completion, and GlgFalse for failure.
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, GlgSetXform 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 the GlgSuspendObject function. Use the GlgReleaseObject when done. Adding a transformation without using the GlgSuspendObject function after the object has been drawn generates an error message.
Suspends an object for editing.
GlgObject GlgSuspendObject( object ) GlgObject object;Specifies an object to be suspended.
Some operations, such as attaching a transformation to an object, constraining the object's attribute and some others, may be carried out only before the object has been drawn. If the object has been drawn and you still need to perform these operations, the GlgSuspendObject functions must be used to suspend the object for editing. If the GlgSuspendObject function is not used, any attempt to perform these modifications fails, producing an error message.
The GlgSuspendObject function may be called only for the graphical objects, such as a viewport, group, polygon, or others.
The GlgReleaseObject function must be called after the editing operations have been completed. It an object is suspended, it is not allowed to call an update function before the object has been released.
The GlgSuspendObject function returns an object which keeps suspension information. This information should be passed to the GlgReleaseObject function when the object is released.
Transforms all control points of an object with an arbitrary transformation:
GlgBoolean GlgTransformObject( object, xform, coord_type, parent ) GlgObject object; GlgObject xform; GlgCoordType coord_type; GlgObject parent;Specifies the coordinate system to interpret the transformation in. If GLG_SCREEN_COORD is used, the parameters of the transformation are considered to be in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. If GLG_OBJECT_COORD is used, the transformation parameters are interpreted as GLG world coordinates.
Transforms all control points of an object with an arbitrary transformation:
void GlgTransformObject( object, xform, coord_type, parent ) GlgObject object; GlgObject xform; GlgCoordType coord_type; GlgObject parent;Specifies the coordinate system to interpret the transformation in. If GLG_SCREEN_COORD is used, the parameters of the transformation are considered to be in screen pixels. For example, this may be used to move the object by the number of screen pixels as defined by the mouse move. If GLG_OBJECT_COORD is used, the transformation parameters are interpreted as GLG world coordinates.
Specifies the attribute or point object to be unconstrained.
This function removes any constraints applied to an attribute object. Any changes made to the object while it was constrained to another object are permanent and will be in effect even after the constraints are removed. The removal of the constraints only means that changes to this object are no longer copied to the other objects to which it was once constrained.
If any of the objects which are using this attribute object (or any objects with attributes constrained to it) have already been drawn, an error message will be produced. Use the GlgSuspendObject function to suspend drawn objects before removing constraints from their attributes.
Converts a point's coordinates from the GLG world coordinate system to the screen coordinate system.
GlgBoolean GlgWorldToScreen( object, inside_vp, in_point, out_point ) GlgObject object; GlgBoolen inside_vp; GlgPoint * in_point; GlgPoint * out_point;Specifies the object whose world coordinate system to convert from. The world coordinate system of an object includes the effect of all drawing transformations attached to the object and all its parents.
For a viewport object, specifies which world coordinate system to use: the world coordinate system used to draw the viewport inside its parent viewport (inside_vp=GlgFalse), or the world coordinate system used to draw object inside the viewport (inside_vp=GlgTrue). The value of this parameter is ignored for other objects.
You can use the GlgGet*Resource and GlgSet*Resource functions to set and query the value of an attribute object. To do this, pass the attribute object ID as the object parameter for these functions and use NULL as the resource name parameter.
The following example shows how to use this feature to create a function to move a polygon:
GlgBoolean GlgMovePolygon( polygon, by, direction ) GlgObject polygon; double by; GlgLong direction; { long i, size; GlgObject polygon; double x, y, z; size = GlgGetSize( polygon ); GlgSetStart( polygon ); /* Initialize traversing. */ for( i=0; i<size; ++i ) { /* Get the next point. */ point = GlgIterate( polygon ); /* Query the point's coordinates. */ GlgGetGResource( point, NULL, &x, &y, &z ); /* Move the point in the desired direction. */ switch( direction ) { case 'x': GlgSetGResource( point, NULL, x + by, y, z ); break; case 'y': GlgSetGResource( point, NULL, x, y + by, z ); break; case 'z': GlgSetGResource( point, NULL, x, y, z + by ); break; default: fprintf( stderr, "Invalid direction.\n" ); return False; } } return True; }Although the dynamic typing used by the GLG Library is quite useful and tremendously flexible, some application programmers prefer to rely on their compiler to help them identify bugs at compile time. If you prefer to have strongly typed functions, you may create function wrappers with statically typed parameters for every argument type.
For example, for the generic GlgCreateObject function:
GlgObject GlgCreateObject( type, name, data1, data2, data3, data4 ) GlgObjectType type; char * name; GlgAnyType data1; GlgAnyType data2; GlgAnyType data3; GlgAnyType data4;the following strongly typed wrappers may be created:
GlgObject GlgCreatePolygon( name, num_points ) char * name; long num_points; { return GlgCreateObject( GLG_POLYGON, name, (GlgAnyType)num_points, NULL, NULL, NULL ); } GlgObject GlgCreateText( name, string ) char * name; char * string; { return GlgCreateObject( GLG_TEXT, name, (GlgAnyType)string, NULL, NULL, NULL ); }