PREV NEXT

Generic Logic, Inc. www.genlogic.com


2.6 GLG Intermediate and Extended API

The GLG Standard API enables an application to display a GLG drawing and animate it by querying and setting resources. The GLG Extended API adds functionality that allows an application program to edit or create the drawing at run time. The GLG Intermediate API is a subset of the Extended API that provides all of the Extended API methods for manipulating the drawing, except for the methods for creating, adding or deleting objects from the drawing at run time.

The GLG Intermediate API may be used to modify GLG drawings created in the GLG Graphics Builder and to implement elaborate custom logic to handle user interaction. The Intermediate API may also be used to obtain object IDs of resources in the drawing to access them directly, eliminating the resource path parsing required by the Standard API methods and increasing update performance of large drawings. The Intermediate API provides extensive functionality for changing an object's geometry and layout, creating and removing constraints, as well as advanced introspection capabilities for traversing the drawing and determining its content at run time.

The GLG Extended API includes all method of the Standard and Intermediate APIs and adds methods for creating, copying and adding objects to the drawing at run time. The Extended API may be used for adding objects to the drawing at run time or creating a drawing on the fly based on a configuration file. It may also be used for adding dynamics, tags and custom properties to objects at run time.

Both the Intermediate and Extended APIs are available in all deployment options supported by the Toolkit, including C/C++, Java, C#/.NET, JavaScript and (on Windows) ActiveX Control.

Refer to the DEMOS and examples directories for examples of using the Intermediate and Extended API methods in various programming environments.

Overview

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 many different combinations to obtain different effects, using the resource notation to control their actions.

There are two libraries that provide the Extended API functionality: GLG Intermediate Library and GLG Extended Library. The Intermediate Library provides all of the Extended API methods, except for the methods for creating and deleting objects at run time. The Extended Library contains all Extended API functions, including the methods for creating objects at run time.

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 Intermediate API includes the following functions:

The Intermediate API also includes functions specific to the Real-Time Chart and GIS objects. These functions are described in Real-Time Chart Functions on page 188 and GIS Object Functions on page 202.

The GLG Extended API includes the following functions:

Handling GLG Objects

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.

The Reference Count

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.

Using Mouse Coordinates and Pixel Mapping

The Toolkit's rendering engine uses the OpenGL-style pixel mapping for consistent rendering across all windowing systems and programming environments. The integer pixel values are mapped to the center of the pixel, which means that the x and y coordinates of the center of the upper left pixel of a window are (0.5;0.5) instead of (0;0). When using the mouse position to obtain screen coordinates passed to the GLG functions, add GLG_COORD_MAPPING_ADJ (defined as 0.5 in GlgApi.h) to the x and y screen coordinates of the mouse for better precision.

Include Files

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"

Intermediate API Function Descriptions

GlgConstrainObject

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;
Parameters
from_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 Nth 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.
to_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 the Constraints section 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 constraining 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.

GlgContainsObject

Checks if object belongs to a container.

GlgBoolean GlgContainsObject( container, object )
	GlgObject container;
	GlgObject object;
Parameters
container
Specifies the container object.
object
Specifies the object to search for.

This function returns GlgTrue if the object belongs to the container and GlgFalse otherwise.

GlgConvertViewportType

Converts a viewport to a light viewport, or a light viewport to a viewport.

Returns a newly created object on success or NULL on error.

GlgObject GlgConvertViewportType( object )
	GlgObject object;
Parameters
object
A viewport or a light viewport to be converted.

If a converted object is added to the drawing, the original object must be deleted, since both objects reuse the graphical objects inside the viewport and cannot be both displayed at the same time.

GlgCreateInversedMatrix

Inverts a matrix object.

GlgObject GlgCreateInversedMatrix( matrix )
	GlgObject matrix;
Parameters
matrix
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.

GlgCreatePointArray

Creates and returns an array containing all of an object's control points:.

GlgObject GlgCreatePointArray( object, type )
	GlgObject object;
	GlgControlPointType type;
Parameters
object
Specifies the object.
type
Specifies the type of points to be returned: control points, or control and attachment points.

GlgCreateResourceList

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;
Parameters
object
The input object.
list_named_res
A boolean value indicating whether the returned list should include the input object's named resources.
list_def_attr
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.
list_aliases
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 finished.

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, GlgTrue, GlgTrue, GlgFalse ); 
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:

GlgCreateSelectionMessage

Searches all objects inside the given rectangle for an action with the specified selection trigger type attached to an object and returns a selection message for the first found action attached to the object:

GlgObject GlgCreateSelectionMessage( top_vp, rectangle, selected_vp, 
selection_type, button )
	GlgObject top_vp;
	GlgRectangle * rectangle;
	GlgObject selected_vp;
	GlgSelectionEventType selection_type;
	GlgLong button;
Parameters
top_vp
The top viewport of the selection query (must be an ancestor of selected_vp). It may be either a viewport or a light viewport.
rectangle
The bounding rectangle in screen coordinates of the selected_vp viewport. Any graphical shape whose rendering intersects this rectangle is included in the search.
selected_vp
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. It may be either a viewport or a light viewport.
selection_type
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.
button
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 an action attached to a graphical object in a drawing. The function returns a message equivalent to the message received in the input callback. If no matching actions were found, NULL is returned.

GlgCreateSelectionNames

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;	
Parameters
top_vp
The top viewport or light viewport of the selection query (must be an ancestor of selected_vp). It may be either a viewport or a light viewport.
rectangle
The bounding rectangle in screen coordinates of the selected_vp viewport. Any graphical shape whose rendering intersects this rectangle is included in the selection list.
selected_vp
The viewport or light 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. It may be either a viewport or a light viewport.

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 = GlgGetResourceObject( top_vp, path_name );

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.

GlgCreateSelection

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;	
Parameters
top_vp
The top viewport or light viewport of the selection query (must be an ancestor of selected_vp). It may be either a viewport or a light viewport.
rectangle
The bounding rectangle in screen coordinates of the selected_vp viewport. Any graphical shape whose rendering intersects this rectangle is included in the selection list.
selected_vp
The viewport or light 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. It may be either a viewport or a light viewport.

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.

GlgDropObject

Decrements an object's reference count.

void GlgDropObject( object )
	GlgObject object;
Parameters
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.

GlgDeleteTags

Deletes all object's data tags or all object's public properties. Returns GlgTrue on success.

GlgBoolean GlgDeleteTags( object, tag_type_mask )
	GlgObject object;
	GlgTagType tag_type_mask;
Parameters
object
Specifies the object to delete the tags from.
tag_type_mask
Specifies a bitwise mask that defines the type of tags to be deleted: data tags (GLG_DATA_TAG), public properties (GLG_EXPORT_TAG) or both.

GlgEnableAttachmentPoints

Controls the use of attachment points to determine object extents when the objects are aligned. Returns the previous state of the setting.

GlgBoolean GlgEnableAttachmentPoints( state )
	GlgBoolean state;
Parameters
state
Specifies if attachment points should be used in addition to the control points to determine object extents when the objects are aligned.

GlgFindObject

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;
Parameters
container
Specifies the container object.
object
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.
search_type
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.

GlgFindMatchingObjects

Finds either one or all parents or children of the specified object that match the supplied criteria:

GlgBoolean GlgFindMatchingObjects( object, data )
	GlgObject object;
	GlgFindMatchingObjectsData * data;
Parameters
object
Specifies the object whose parents or children to search.
data
The structure that specifies search criteria and returns the search results:
typedef struct _GlgFindMatchingObjectsData
{
	GlgObjectMatchType match_type;
	GlgBoolean find_parents;
	GlgBoolean find_first_match;
	GlgBoolean search_inside;
	GlgBoolean search_drawable_only;
	GlgBoolean (*custom_match)( GlgObject object, void * custom_data );
	void * custom_data;
	GlgObjectType object_type;
	char * object_name;
	char * resource_name;
	GlgObject object_id;
	GlgObject found_object;
	GlgBoolean found_multiple;
} GlgFindMatchingObjectsData;

The structure's fields control the way the search is performed:

match_type
Specifies a bitwise mask of the object matching criteria:
Multiple criteria can be ORed together. All of the criteria in the mask must be true in order for an object to match.
find_parents
If set to GlgTrue, ancestors (parents, grandparents and so on) of the object are searched. Otherwise, the object's descendents (children, grandchildren and so on) are searched.
find_first_match
If set to GlgTrue, the search is stopped after the first match and the first matching object is returned, otherwise all matching objects are returned.
search_inside
If set to GlgFalse, the object's children or parents are not searched if the object itself matches. Otherwise, the search proceeds to process the object's children or parents even if the object matches.
search_drawable_only
If set to GlgTrue when searching descendents, only drawable objects are searched. For example, when this flag is set, a polygon object's attributes such as FillColor and EdgeColor, will not be searched, which can be used to speed up the search. Refer to the description of the GlgIsDrawable method on 1
custom_match
Provides a custom matching function that is invoked for each searched object. The function can perform a custom matching and should return GlgTrue to indicate a match. The function will also receive custom data supplied by the custom_data field.
custom_data
Custom data for the custom_match function.
object_type
The type for the GLG_OBJECT_TYPE_MATCH search. Only objects of this type will be matched.
object_name
The name for the GLG_OBJECT_NAME_MATCH search. Only objects with this name will be matched.
resource_name
The resource name for the GLG_RESOURCE_MATCH search. Only objects that have this resource will be matched. The resource has to be an object.
object_id
The name for the GLG_OBJECT_ID_MATCH search. Only the object with this object ID will be matched. This type of search can be used to find out if an object is either a child or a parent of another object.
found_object
Returns a single found object or a group containing multiple found objects, according to the state of the found_multiple parameter. If a group containing multiple objects is returned, the group should be dereferenced using GlgDropObject to avoid memory leaks. It is set to NULL if no matching objects were found.
found_multiple
Will be set to GlgTrue or GlgFalse to indicate the type of the returned result. If it is set to GlgTrue, the result of the search stored in the found_object field contains a group of several matching objects. Otherwise (GlgFalse), found_object contains a single matching object.

The function returns GlgTrue if at least one matching object was found.

GlgFitObject

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;
Parameters
object
Specifies the object to fit.
coord_type
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.
box
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.
keep_ratio
If the parameter is set to GlgTrue, 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 GlgFalse, 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;

GlgGetAlarmObject

Returns a tag object with a specified alarm label, or a list of alarms matching the specified alarm label pattern.

GlgObject GlgGetAlarmObject( object, search_string, single_alarm, 
reserved )
	GlgObject object;
	char * search_string;
	GlgBoolean single_alarm;
	GlgLong reserved;
Parameters
object
Specifies the object whose alarms to query.
search_string
Specifies a string or a pattern for the search (may include ? and * wildcards).
single_alarm
Defines a single alarm (GlgTrue) or multiple alarm (GlgFalse) mode.
reserved
Reserved for future use, must be 0.

In a single alarm mode, the function returns the alarm that has an alarm label matching the search criteria.

In the multiple alarm mode, a list containing all alarms with matching alarm labels will be returned. The returned list must be dereferenced using GlgDropObject when it is no longer needed.

GlgGetBoxPtr

Returns an object's bounding box.

GlgCube * GlgGetBoxPtr( object )
	GlgObject object;
Parameters
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;

GlgGetDrawingMatrix

Returns the transformation matrix attached to the input object.

GlgObject GlgGetDrawingMatrix( object )
	GlgObject object;
Parameters
object
Specifies the input 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.

GlgGetElement

Returns the object at the specified position in a container.

GlgObject GlgGetElement( container, index )
	GlgObject container;
	GlgLong index;
Parameters
container
Specifies the container object.
index
Specifies the object position inside the container.

This function returns NULL if the specified index is invalid. While the function provides the Intermediate API functionality, it is also available in the Standard API when used with the group object, such as querying elements of a message object.

GlgGetIndex

Returns the index of the first occurrence of an object in a container.

GlgLong GlgGetIndex( container, object)
	GlgObject container;
	GlgObject object;
Parameters
container
Specifies the container object.
object
Specifies the object to search for.

This function returns -1 if the object wasn't found in the container.

GlgGetMatrixData

Queries matrix coefficients:

void GlgGetMatrixData( matrix, matrix_data )
	GlgObject matrix;
	GlgMatrixData * matrix_data;
Parameters
matrix
Specifies the matrix object to query.
matrix_data
The structure to hold the matrix's coefficients.

The GlgMatrixData data type is defined in the GlgApi.h file:

typedef struct _GlgMatrixData	
{
	long type;
	double matrix[4][4];
} GlgMatrixData;

GlgGetNamedObject

Returns an object ID of the object in a container with the specified name.

GlgObject GlgGetNamedObject( container, name )
	GlgObject container;
	char * name;
Parameters
container
Specifies the container object.
name
Specifies the object's 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.

GlgGetParent

Returns an object's parent object, if one exists.

GlgObject GlgGetParent( object, num_parents )
	GlgObject object;
	GlgLong * num_parents;
Parameters
object
Specifies the object whose parents are to be returned.
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.

GlgGetParentViewport

Returns a parent viewport of a drawable GLG object.

GlgObject GlgGetParentViewport( object, heavy_weight )
	GlgObject object;
	GlgBoolean heavy_weight;
Parameters
object
A drawable GLG object.
heavy_weight
Controls the type of a parent viewport to be returned. If set to GlgFalse, the method returns the closest parent viewport regardless of its type: either a heavyweight or light viewport. If set to GlgTrue, it returns the closest heavyweight parent viewport. For example, if the object is inside a light viewport, it will return the heavyweight viewport which is a parent of the light viewport.

The object's hierarchy must be setup to use this function.

GlgGetResourceObject

Returns the ID of a resource object.

GlgObject GlgGetResourceObject( object, resource_name )
	GlgObject object;
	char * resource_name;
Parameters
object
Specifies the object whose resources are queried.
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.

GlgGetSize

Queries the size of a container object.

GlgLong GlgGetSize( container )
	GlgObject container;
Parameters
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 Intermediate API functionality, it is also available in the Standard API when used with a group object.

GlgGetStringIndex

Returns the index of the first occurrence of the string in a string container.

GlgLong GlgGetStringIndex( container, string)
	GlgObject container;
	char * string;
Parameters
container
Specifies the container object.
string
Specifies the string to search for.

This function returns -1 if the string wasn't found in the container.

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.

GlgObject GlgGetTagObject( object, search_string, by_name, 
unique_tags, single_tag, tag_type_mask)
	GlgObject object;
	char * search_string;
	GlgBoolean by_name;
	GlgBoolean unique_tags;
	GlgBoolean single_tag;
	GlgTagType tag_type_mask;
Parameters
object
Specifies the object whose tags to query.
search_string
Specifies a string or a pattern for the search (may include ? and * wildcards).
by_name
If set to GlgTrue, the search is performed by matching the tag names, otherwise the search is done by matching the tag sources. Tag sources can be used only for data tags.
unique_tags
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.
single_tag
Defines the single tag (GlgTrue) or multiple tag (GlgFalse) mode.
tag_type_mask
Defines the type of tags to query: data tags or export tags. Tag type constants may be ORed to query tags of several types.

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.

GlgInverse

Inverses the order of elements inside a container object.

void GlgInverse( container )
	GlgObject container;
Parameters
container
Specifies the container object.

GlgIsAt

Checks the position of the iteration pointer (the current element of the container).

GlgBoolean GlgIsDAt( container, position )
	GlgObject object;
	GlgPositionType position;
Parameters
container
Specifies the container object.

The following lists return values for different values of the position argument:

GlgIsDrawable

Returns GlgTrue if the object is drawable.

GlgBoolean GlgIsDrawable( object )
	GlgObject object;
Parameters
object
Specifies the object.

Drawable objects can be placed directly in a drawing area, have control points and a bounding box, have the Visibility attribute and can contain custom properties, actions and aliases.

For a chart object, the chart itself is drawable, but its plots are not.

GlgIterate

GlgIterateBack

Traverse the container object forward or backward.

GlgObject GlgIterate( container )
	GlgObject container;
GlgObject GlgIterateBack( container )
	GlgObject container;
Parameters
container
Specifies the container object.

For the forward traversing, GlgIterate advances the iteration pointer and returns the next element of container. For backward traversing, GlgIterateBack decrements the iteration pointer and returns the previous element.

The GlgSetStart function must be used to initialize the container for iterating before GlgIterate is invoked the first time, and GlgSetEnd must be used to initialize the container for backward iteration with GlgIterateBack. The add, delete and search operations affect the iteration state and should not be performed on the container while it is being iterated.

To perform a safe iteration that is not affected by the add and delete operations, a copy of the container can be created using the GlgCloneObject function with the SHALOW_CLONE clone type. The shallow copy will return a container with a list of objects IDs, and it can be safely iterated while objects are added or deleted from the original container.

Alternatively, GlgGetElement can be used to traverse elements of the container using an element index, which is not affected by the search operations on the container.

The following coding example shows how to iterate all objects in a container in the forward and backward direction using GlgIterate and GlgIterateBack:

int i, size;
GlgObject object;

size = GlgGetSize( container );
if( size != 0 )
{
	GlgSetStart( container );     /* Initialize direct traversing. */
	for( i=0; i<size; ++i )
	{
		object = GlgIterate( container );
		... /* Code to process the object */
	}

	GlgSetEnd( container );    /* Initialize for backward traversing. */
	for( i=0; i<size; ++i )
	{
		object = GlgIterateBack( container );
		... /* Code to process the object */
	}
}

GlgLayoutObjects

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;
Parameters
object
Specifies the object or group of objects to perform the requested operations upon.
sel_elem
Specifies the anchor object for alignment operations. If null value is specified, the first encountered object in the specified alignment direction is used.
type
Specifies the type of the layout action to perform. May have the following values:
ALIGN_LEFT
Align the left edge of elements within the group with the left edge of the anchor element.
ALIGN_RIGHT
Align the right edge of elements within the group with the right edge of the anchor element.
ALIGN_HCENTER
Align the center of elements within the group with the center of the anchor element horizontally.
ALIGN_TOP
Align the top edge of elements within the group with the top edge of the anchor element.
ALIGN_BOTTOM
Align the bottom edge of elements within the group with the bottom edge of the anchor element.
ALIGN_VCENTER
Align the center of elements within the group with the center of the anchor element vertically.
SET_EQUAL_VSIZE
Set the height of elements within the group to the height of the anchor.
SET_EQUAL_HSIZE
Set the width of elements within the group to the width of the anchor.
SET_EQUAL_SIZE
Set the width and height of elements within the group to the width and height of the anchor.
SET_EQUAL_VDISTANCE
Equally distributes the group's elements in vertical direction as measured by the distance between their centers.
SET_EQUAL_HDISTANCE
Equally distributes the group's elements in horizontal direction as measured by the distance between their centers.
SET_EQUAL_VSPACE
Equally distributes space gaps between group's elements in vertical direction.
SET_EQUAL_HSPACE
Equally distributes space gaps between group's elements in horizontal direction.
SET_VSIZE
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.
SET_HSIZE
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_VDISTANCE
Set vertical distance between centers of the group's elements to a value defined by the distance parameter.
SET_HDISTANCE
Set horizontal distance between centers of the group's elements to a value defined by the distance parameter.
SET_VSPACE
Sets space gaps between group's elements in vertical direction to a value defined by the distance parameter.
SET_HSPACE
Sets space gaps between group's elements in horizontal direction to a value defined by the distance parameter.
distance
The distance in screen coordinates for positioning objects, depending on the layout action.
use_box
If set to GlgTrue, the object's bounding box is used to align objects, otherwise the control points will be used to determine the object's extent.
process_subobjects
Controls how to apply the layout action if the object is a group. If set to GlgTrue, 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 GlgFalse if errors were encountered during the requested layout action.

GlgLoadObject

Loads an object from a file in GLG format.

GlgObject GlgLoadObject( filename )
	char * filename;
Parameters
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.

GlgLoadObjectFromImage

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;
Parameters
image_address
Specifies the address of the drawing image generated by the GLG Code Generation Utility.
image_size
Specifies the image size.

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.

GlgMoveObject

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;
Parameters
object
Specifies the object to be moved.
coord_type
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.
start_point
The start point of the move vector. If the parameter is NULL, (0,0,0) is used as the start point.
end_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;

GlgMoveObjectBy

Moves an object by a move distance:

GlgBoolean GlgMoveObjectBy( object, coord_type, x, y, z )
	GlgObject object;
	GlgCoordType coord_type;
	double x, y, z;
Parameters
object
Specifies the object to move.
coord_type
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.
x, y, z
The X, Y and Z move distances.

This function moves an object's control points by the X, Y and Z distances, calculating new control point values. The object's hierarchy must be setup to use this function.

GlgPositionObject

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;
Parameters
object
Specifies the object to position.
coord_type
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.
anchoring
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.
x, y, z
The X, Y and Z coordinates of the desired object position.

This function positions the object, calculating new control point values. The object's hierarchy must be setup to use this function.

GlgReferenceObject

Increments an object's reference count.

GlgObject GlgReferenceObject( object )
	GlgObject object;
Parameters
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.

GlgReleaseObject

Releases a suspended object after editing.

void GlgReleaseObject( object, suspend_info )
	GlgObject object;
	GlgObject suspend_info;
Parameters
object
Specifies the object to be released after it was suspended for editing.
suspend_info
Suspension information returned by the previous call to the GlgSuspendObject function.

This function releases previously suspended object and is intended to be used only with the GlgSuspendObject function.

GlgReorderElement

Changes the object's position inside a container.

void GlgReorderElement( container, old_index, new_index )
	GlgObject object;
	GlgLong old_index;
	GlgLong new_index;
Parameters
container
Specifies the container object.
old_index
Specifies the index of an object to be reordered.
new_index
Specifies a new position for the object.

This function moves the object at the old_index to the new_index position. It returns GlgFalse if indexes are out of range.

GlgRootToScreenCoord

Converts screen coordinates relative to the root window to the screen coordinates in the specified viewport.

GlgBoolean GlgRootToScreenCoord( viewport, point )
	GlgObject viewport;
	GlgPoint2 * point;
Parameters
viewport
Specifies the viewport whose screen coordinate system to convert to.
point
The point to be converted. The result is placed back into the structure pointed by this pointer.

The viewport's hierarchy must be set up to use this function.

The GlgPoint2 data type is defined in the GlgApi.h file:

typedef struct _GlgPoint2	
{
	double x, y;
} GlgPoint2;

GlgRotateObject

Rotates an object:

GlgBoolean GlgRotateObject( object, coord_type, center, x, y, z )
	GlgObject object;
	GlgCoordType coord_type;
	GlgPoint * center;
	double x, y, z;
Parameters
object
Specifies the object to rotate.
coord_type
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.
center
The center of rotation. If the parameter is NULL, the object is rotated relative to the center of its bounding box.
x, y, z
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;

GlgSaveObject

Saves an object into a file.

GlgBoolean GlgSaveObject( object, filename )
	GlgObject object;
	char * filename;
Parameters
object
Specifies the object to be saved; it may be any GLG object.
filename
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.

For applications that load a drawing, modify it and save if back into a file, the drawing should be loaded using the GlgLoadObject function instead of GlgLoadWidget. GlgLoadWidget extracts the $Widget viewport from the loaded drawing, discarding the rest of the drawing, while GlgLoadObject returns an object that represents the whole drawing. Using GlgSaveObject to save a viewport loaded with GlgLoadWidget will result in a loss of information contained in the discarded part of the drawing, such as the type of the coordinate system used to display the viewport, which will make it difficult to load and edit the drawing in the Builder. The following example demonstrates the proper technique:

GlgObject drawing = GlgLoadObject( "drawing.g" );
GlgObject viewport = GlgLoadWidgetFromObject( drawing ); /* Extracts $Widget viewport */
... /* Code that modifies the drawing. */
GlgSaveObject( drawing, "new_drawing.g" );

GlgScaleObject

Scales an object:

GlgBoolean GlgScaleObject( object, coord_type, center, x, y, z )
	GlgObject object;
	GlgCoordType coord_type;
	GlgPoint * center;
	double x, y, z;
Parameters
object
Specifies the object to scale.
coord_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.
center
The center of scaling. If the parameter is NULL, the object is scaled relative to the center of its bounding box.
x, y, z
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;

GlgScreenToWorld

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;
Parameters
object
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.
inside_vp
If object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use. If inside_vp=GlgTrue, the method will use the world coordinate system used to draw objects inside this (object) viewport. If inside_vp=GlgFalse, the method will use the world coordinate system used to draw this object viewport inside its parent viewport.
The value of this parameter is ignored for objects other than a viewport or light viewport.
in_point
The point to be converted.
out_point
The point structure to hold the converted value.

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;

When converting the cursor position to world coordinates, add GLG_COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.

GlgSetMatrixData

Sets matrix coefficients:

void GlgSetMatrixData( matrix, matrix_data )
	GlgObject matrix;
	GlgMatrixData * matrix_data;
Parameters
matrix
Specifies the matrix object.
matrix_data
The new matrix's coefficients.

The GlgMatrixData data type is defined in the GlgApi.h file:

typedef struct _GlgMatrixData	
{
	long type;
	double matrix[4][4];
} GlgMatrixData;

GlgSetStart

GlgSetEnd

Initializes the container object for the forward or backward traversing.

void GlgSetStart( container )
	GlgObject container;
void GlgSetEnd( container )
	GlgObject container;
Parameters
container
Specifies the container object.

GlgSetStart sets the current position pointer before the first element of the container, preparing the container object for forward traversing with GlgIterate.

GlgSetEnd sets the current position pointer past the last element of the container, preparing it for backward traversing with GlgIterateBack.

GlgSuspendObject

Suspends an object for editing.

GlgObject GlgSuspendObject( object )
	GlgObject object;
Parameters
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.

GlgTransformObject

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;
Parameters
object
Specifies the object to transform.
xform
Specifies the transformation to be applied to the object's points.
coord_type
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.
parent
The object's parent. It is required in the GLG_OBJECT_COORD mode, may be NULL for GLG_SCREEN_COORD mode.

This function applies the given transformation to an object's control points, calculating new control point values. The object's hierarchy must be setup to use this function.

GlgTransformPoint

Transforms a single point.

void GlgTransformPoint( matrix, in_point, out_point )
	GlgObject matrix;
	GlgPoint * in_point;
	GlgPoint * out_point;
Parameters
matrix
Specifies the matrix to be applied to the input point.
in_point
The input point to be transformed.
out_point
The transformed point.

This function applies the given transformation matrix to the in_point parameter, and returns the result in out_point.

The GlgPoint data type is defined in the GlgApi.h file:

typedef struct _GlgPoint	
{
	double x, y, z;
} GlgPoint;

GlgTranslatePointOrigin

Converts screen coordinates of a point in one viewport to the screen coordinates of another viewport.

void GlgTranslatePointOrigin( from_viewport, to_viewport, 

				point )
	GlgObject from_viewport;
	GlgObject to_viewport;
	GlgPoint * point;
Parameters
from_viewport
Specifies the viewport in which the point's screen coordinates are defined.
to_viewport
Specifies the viewport whose screen coordinate system to convert to.
in_point
The point to be converted. The result is placed back into the structure pointed by this pointer.

The objects' 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;

GlgTraceObject

Highlights all objects in the drawing that depend on the tag or resource object that is being traced.

GlgBoolean GlgTraceObject( object, state, is_widget, top_parent, 

                func, data )
	GlgObject object;
	GlgBoolean state;
	GlgBoolean is_widget;
	GlgBoolean (*func)( GlgObject parent, void * data );
	void * data;
Parameters
object
Specifies the object to trace. The object must be set up.
state
May be set to True to highlight the objects in the drawing that depend on the traced object or set to False to unhighlight them.
is_widget
If set to True, the parent objects that have resource named IsWidget will be highlighted or unhighlighted depending on the state parameter.
top_parent
If non-null, the parent objects that are direct children of top_parent will be highlighted or unhighlighted.
func
An optional function that provides a custom condition. The function will be invoked for each parent of a traced object to check if a custom condition is satisfied. If the function returns True, the parent will be highlighted or unhighlighted.
data
Specifies a pointer to the custom data passed to the func function.

GlgTraceObject searches all parents of the traced object and highlights or unhighlights them (as directed by the state parameter) based on the specified conditions. The parent search is performed until any of the specified conditions (is_widget, top_parent or a custom criteria evaluated by the supplied function) is satisfied. If no conditions are specified, all immediate drawable parents of the traced object will be highlighted or unhighlighted.

The function returns True if any parents were highlighted or unhighlighted.

The dependent parent objects are highlighted with an outline. The attributes of the outline are defined by the GlgHighlightPolygon global configuration resource.

Internally, object highlighting is done setting an object's HighlightFlag attribute to True. An application can also set and reset this attribute of drawable objects via the GlgSetDResource function to highlight or unhighlight individual objects of interest.

GlgTraverseObjects

Traverses the object hierarchy of the object and invokes the supplied function on the object itself and all its subobjects, including object attributes.

void GlgTraverseObjects( object, func, data )
	GlgObject object;
	GlgBoolean (*func)( GlgObject object, void * data );
	void * data;
Parameters
object
Specifies the object to traverse.
func
Specifies the custom function to be invoked. The function return result is used to modify the traversal: if the function returns GlgFalse for a subobject, the traversal of objects inside the subobject will not be performed.
data
Specifies a pointer to the custom data passed to the function.

GlgUnconstrainObject

Unconstrains an object.

GlgBoolean GlgUnconstrainObject( attribute )
	GlgObject attribute;
Parameters
attribute
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.

GlgWorldToScreen

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;
Parameters
object
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.
inside_vp
If object is a viewport or a light viewport, inside_vp specifies which world coordinate system to use. If inside_vp=GlgTrue, the method will use the world coordinate system used to draw objects inside this (object) viewport. If inside_vp=GlgFalse, the method will use the world coordinate system used to draw this object viewport inside its parent viewport.
The value of this parameter is ignored for objects other than a viewport or light viewport.
in_point
The point to be converted.
out_point
The point structure to hold the converted value.

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;

Get and Set Resource Function Extension

The GlgGet*Resource and GlgSet*Resource functions may be used to set or query the value of an attribute object directly, without searching for the resource name. To do this, pass the attribute object ID as the object parameter and use NULL as the resource_name parameter. It will set the attribute object directly, speeding up the operation by eliminating the search for the resource name.

The following example shows how to use this feature in a function that moves a polygon:

GlgBoolean MovePolygon( 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;
}

The above source code is used for example purpose only. The same functionality may be accomplished by the GlgMoveObjectBy function.

Extended API Function Descriptions

GlgCreateObject

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;
Parameters
type
Specifies the type of 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 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.
data1, data2, data3, data4
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.

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. More detailed descriptions of their use follow the table.

The following table summarizes the usage of the data parameters:

Object Type
data1
data2
data3
data4
GLG_ARC
GLG_MARKER
GLG_PARALLELOGRAM
GLG_POLYLINE
GLG_POLYSURFACE
GLG_VIEWPORT
GLG_BOX_ATTR
GLG_RENDERING
GLG_LIGHT
NULL
NULL
NULL
NULL
GLG_POLYGON
GLG_SPLINE
number of vertices
GlgLong
optional
polygon default: 2
spline default: 3
NULL
NULL
NULL
GLG_TEXT
string
char *
optional
default: empty string
text subtype
GlgTextType
optional
default:
GLG_FIXED
NULL
NULL
GLG_IMAGE
image filename
char*
optional
default: NULL
image subtype
GlgImageType
optional
default: GLG_FIXED_IMAGE
NULL
NULL
GLG_GROUP
GLG_ARRAY
GLG_LIST
type of group
GlgContainerType
optional
default: NULL
number of objects
GlgLong
optional
default: NULL
NULL
NULL
GLG_REFERENCE
template
GlgObject
mandatory for all reference types (use NULL for file references)
referencing type
GlgRefType
optional
default: GLG_REFERENCE_REF
NULL
NULL
GLG_SERIES
GLG_SQUARE_SERIES
template
GlgObject
mandatory
NULL
NULL
NULL
GLG_CONNECTOR
connector subtype
GlgObjectType
mandatory
number of points for recta-linear path or NULL
optional
default: 2
NULL
NULL
GLG_FRAME
frame subtype
GlgFrameType
mandatory
frame factor
GlgLong
mandatory
NULL
NULL
GLG_GIS
dataset file
char *
optional
NULL
NULL
NULL
GLG_DATA
data type (D, S or G)
GlgDataType
mandatory
string value (S data only)
char *
optional
default: NULL
NULL
NULL
GLG_ATTRIBUTE
data type (D, S or G)
GlgDataType
mandatory
attribute role
GlgXformRole
mandatory
NULL
NULL
GLG_ALIAS
alias name
char *
optional
default: NULL
resource path
char *
optional
default: NULL
NULL
NULL
GLG_HISTORY
resource name mask
char *
optional
default: NULL
NULL
entry point data type (D, S or G)
GlgDataType
optional
default: GLG_D
NULL
GLG_XFORM
xform role
GlgXformRole
mandatory
xform subtype
GlgXformType
mandatory
xform object
GlgObject
optional
default: NULL
xform object
GlgObject
optional
default: NULL
GLG_TAG
tag name
char *
optional
default: NULL
tag source
char *
optional
default: NULL
tag comment
char *
optional
default: NULL
NULL

Usage Summary for GlgCreateObject

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

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:

GLG_ARC
No data parameters are used. Use NULL for each parameter value.
GLG_CONNECTOR
data1
Specifies a mandatory connector subtype (GlgObjectType) which may have the following values:
GLG_POLYGON
Recta-linear connectors
GLG_ARC
Arc 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 than two, more than 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.
GLG_FRAME
data1
Specifies a mandatory frame subtype (GlgFrameType), which can have the following values:
GLG_1D
GLG_2D
GLG_3D
GLG_FREE
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.
data3, data4
Not used. Use NULL as the parameter's value.
GLG_IMAGE
data1
A filename (char*) of an image file in the GIF, JPEG, PNG or BMP (Windows only) format.
data2
An optional image object subtype (GlgImageType) which may have the following values:
GLG_FIXED_IMAGE
GLG_SCALED_IMAGE
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.
GLG_MARKER
No data parameters are used. Use NULL for each parameter value.
GLG_PARALLELOGRAM
No data parameters are used. Use NULL for each parameter value.
GLG_POLYGON
data1
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.
GLG_POLYLINE
No data parameters are used. Use NULL for each parameter value.
GLG_POLYSURFACE
No data parameters are used. Use NULL for each parameter value.
GLG_TEXT
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:
GLG_FIXED_TEXT
GLG_FIT_TO_BOX_TEXT
GLG_WRAPPED_TEXT
GLG_TRUNCATED_TEXT
GLG_WRAPPED_TRUNCATED_TEXT
GLG_SPACED_TEXT
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.
Example: Creating a Polygon

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 );
}

Since the GLG polygon is a container of points, its points may be accessed via the GlgGetElement or GlgIterate function. Each point is a GLG data object of G type, and its coordinates may be set using the GlgSetGResource function, using the point as the object parameter and NULL as the resource_name parameter.

Refer to the demos and examples directories for examples of complete programs using the GLG Extended API.

Containers and Composite Objects

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.

GLG_GROUP
GLG_ARRAY
GLG_LIST
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 lightweight 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.
data3, data4
Not used. Use NULL as the parameter's value.
GLG_VIEWPORT.
No data parameters are used. Use NULL for each parameter's value.
GLG_SERIES
GLG_SQUARE_SERIES
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.
GLG_REFERENCE
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.
GLG_CONTAINER_REF
Container 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

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:

GLG_DATA.
data1
Specifies a mandatory data type (GlgDataType) which may have the following values:
GLG_D
D data (double)
GLG_S
S data (string)
GLG_G
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.
data3, data4
Not used. Use NULL as the parameter's value.
GLG_ATTRIBUTE.
data1
Specifies a mandatory data type (GlgDataType) which may have the following values:
GLG_D
D attribute (double)
GLG_S
S attribute (string)
GLG_G
G attribute (triplet of double values to define XYZ or RGB)
data2
Specifies a mandatory attribute role (GlgXformRole) which may have the following values:
GLG_GEOM_XR
GLG_COLOR_XR
GLG_GDATA_XR
GLG_DDATA_XR
GLG_SDATA_XR
The attribute's role determines the type of transformations that will affect the object. Refer to GLG Objects for more information.
data3, data4
Not used. Use NULL as the parameter's value.
GLG_ALIAS
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.
data3, data4
Not used. Use NULL as the parameter's value.
GLG_HISTORY
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.
data4
Not used. Use NULL as the parameter's value.
Transformation Objects

This section details procedures for creating the transformation objects. An introduction to these objects can be found in GLG Objects.

GLG_XFORM
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 transformation object is created. 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.
GLG_SMAP_XF
GLG_DMAP_XF
The transformed value is selected by mapping an input key to an output value by matching the input key with the list of keys. The type of the keys is determined by the type of the transformation: D (double) or S (string). The type of the output values is determined by the type of the attribute the transformation is attached to. When a transformation is created, the data3 and data4 parameters can be used to pass a list of values and a list of keys. The lists are passed using a group containing GLG_ATTRIBUTE objects of an appropriate type.
GLG_JAVA_SCRIPT_XF
Creates a JavaScript transformation that sets the output value to the result of a Java Script expression based on a variable number of input parameters.
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.
GLG_IDENTITY_XF
This transformation is used to transfer a value from one attribute object to another. It is used in the internal design of the GLG Control Widgets.
GLG_CHANGE_ALARM_XF
Creates a Change Alarm transformation that generates an alarm when its input value changes.

For a transformation attached to a scalar (D) value, the data2 values can be:

GLG_RANGE_CONVERSION_XF
Creates a Range Conversion transformation used to map an input range 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_RANGE_CHECK_XF
Creates a Range Check transformation that changes the output value when its input value goes out of range.
GLG_RANGE_ALARM_XF
GLG_RANGE2_ALARM_XF
Creates a Range Alarm or Range2 Alarm transformation that generates an alarm when its input value goes out of range.
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
Creates a Divide transformation used to divide an attribute value by the Divisor attribute.
GLG_LINEAR3_XF
Creates a Linear transformation that calculates the output value as a linear combination of the transformation's parameters.
GLG_BOOLEAN_XF
Creates a Boolean transformation that sets the output value to a boolean combination of the transformation's parameters.
GLG_COMPARE_XF
Creates a Compare transformation that sets the output value to 0 or 1 depending on the result of comparing two transformation parameters.
GLG_BITMASK_XF
Creates a Bitmask transformation that sets the output value to a value formed by interpreting the states of four input parameters as bits of a 4-bit integer.
GLG_D_FROM_G_XF
Creates a D From G transformation that extracts an X, Y or Z coordinate (or an R, G or B color value) from a G data object containing a triplet of XYZ or RGB values.
GLG_SCREEN_FACTOR_XF
Creates a Screen Factor transformation that proportionally increases or decreases a scalar attribute depending on zooming and resizing of a parent viewport.

For a transformation attached to a string (S) value, the data2 values can have the following values:

GLG_S_FORMAT_XF
Creates a Format S 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 Format D transformation. The transformed value of the string attribute is equal to an input scalar value formatted with a format string.
GLG_TIME_FORMAT_XF
Creates a Time Format transformation to format POSIX time values and display them as strings.
GLG_STRING_CONCAT_XF
Creates a String Concatenation transformation that concatenates several strings.

Transformations for color attributes may also have the following value:

GLG_COLOR_SCALE_XF
Creates a Bitmask transformation that converts a base color by either increasing or decreasing its intensity, storing the result as the color attribute's transformed value.

Transformations for color attributes and attributes of G type other than control points may also have the following value:

GLG_G_FROM_D_XF
Creates a G From D transformation that forms a single data object of G type (such as an XYZ point or RGB color) from three D (double) data objects that define individual X, Y, Z or R, G, B components.

Transformations for geometrical or color attributes can have the following values:

GLG_TRANSLATE_X_XF
GLG_TRANSLATE_Y_XF
GLG_TRANSLATE_Z_XF
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_X_XF
GLG_SCALE_Y_XF
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_X_XF
GLG_ROTATE_Y_XF
GLG_ROTATE_Z_XF
Create a parametric rotate transformation around the axis defined by the transformation type.
GLG_SHEAR_X_XF
GLG_SHEAR_Y_XF
GLG_SHEAR_Z_XF
Create a parametric shear transformation; the shear amount increases along the axis defined by the transformation type.

Geometrical transformations attached to control points can have the following values:

GLG_WORLD_OFFSET_XF
Creates a World Offset transformation.
GLG_PIXEL_OFFSET_XF
Creates a Pixel Offset transformation.
GLG_FIXED_OFFSET_XF
Creates a Fixed Offset transformation.

Geometrical transformations attached to objects and their control points can have the following values:

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.
Example: Concatenate Transformation

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 );
}
Example: Matrix Transformation

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.

GlgAddObjectToTop

GlgAddObjectToBottom

GlgAddObjectAt

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;
Parameters
container
Specifies the container object.
object
Specifies the object to be added to the container object.
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.

Note: For viewports with integrated scrolling enabled by the viewport's Pan attribute, child viewport objects added to the bottom of the viewport object list will appear in front of the integrated scrollbars until the viewport is reset. Resetting the viewport reorders the scrollbars to be the last in the object list. To achieve proper rendering without resetting the viewport, use GlgAddObjectAt to add the child viewport at a proper position before the integrated scrollbars. If a single X or Y scrollbar is used, the position index will be list_size - 1, where list_size is the number of objects in the viewport. If both X and Y scrollbars are active, list_size - 3 position should be used.

GlgAddObject

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;
Parameters
container
Specifies the container object.
object
Specifies the object to be added to the container object.
access_type
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.
pos_modifier
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 );

for a group with objects:

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

The sequence of calls:

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.

GlgAddAttachmentPoint

Adds an attachment point to a reference object and returns the added point.

GlgObject GlgAddAttachmentPoint( object, dx, dy, dz )
	GlgObject object;
	double dx, dy, dz;
Parameters
object
Specifies a reference object (other than a subwindow) to add an attachment point to.
dx, dy, dz
Specify world coordinate offsets for initial position of the attachment point relatively to the reference's single control point. When the reference object is resized, the offsets will be automatically adjusted to maintain the point's position relatively to the object.

GlgCopyObject

Creates a copy of an object.

GlgObject GlgCopyObject( object )
	GlgObject object;
Parameters
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 the GlgCloneObject section 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.

GlgCloneObject

Creates a specialized copy (clone) of an object.

GlgObject GlgCloneObject( object, clone_type )
	GlgObject object;
	GlgCloneType clone_type;
Parameters
object
Specifies the object to be cloned.
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.

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 NONE, such as 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. 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.
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 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.

GlgDeleteTopObject

GlgDeleteBottomObject

GlgDeleteObjectAt

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;
Parameters
container
Specifies a container object.
index
Specifies an index of the object to be deleted from the container.

These functions delete an object from the container object and returns GlgTrue if the object was successfully deleted or GlgFalse otherwise.

GlgDeleteObject

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;
Parameters
container
Specifies a container object.
reserved
A reserved parameter for the future extensions; must be NULL.
access_type
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.
pos_modifier
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 );

for a group with objects:

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.

The sequence of calls:

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.

GlgDeleteThisObject

Finds and deletes the object from a container.

GlgBoolean GlgDeleteThisObject( container, object )
	GlgObject container;
	GlgObject object;
Parameters
container
Specifies a container object.
object
Specifies an object to be deleted from the container.

This function finds and deletes an object from the container object. It returns GlgTrue if the object was successfully deleted or GlgFalse if object was not found in the container.

GlgFlush

Set the container object's size:

void GlgGetSize( container, size)
	GlgObject container;
	GlgLong size;
Parameters
container
Specifies the container object.
size
Specifies the new size.

This function sets the container size to the requested size. If the new size is less than the current container size, extra elements are removed. If the new size is greater than the current size, the function adds elements by making a copy of the last element in the container.

The container may be a group, a viewport, a polygon (as a container of points), a spline or a connector. The function can only be invoked if the container is not set up. If the container is set up (drawn), the function must be surrounded by the GlgSuspendObject and GlgReleaseObject calls.

GlgSetAttachmentMoveMode

Changes the attachment point move mode and returns the previous mode state.

GlgBoolean GlgSetAttachmentMoveMode( state )
	GlgBoolean state;
Parameters
state
Specifies the state of the attachment point move mode. By default, the attachment point move mode is off, and moving the attachment point will move the reference object it is attached to. If the mode is on, moving the attachment point will change its position relatively to the reference object.

GlgSetElement

Replaces the object at the specified position in a container.

GlgBoolean GlgSetElement( container, index, new_object )
	GlgObject container;
	GlgLong index;
	GlgObject new_object;
Parameters
container
Specifies the container object.
index
Specifies the position inside the container at which the object will be replaced.
new_object
Specifies the new object.

This function returns GlgFalse if the specified index is invalid.

GlgSetResourceObject

Replaces a resource object:

GlgBoolean GlgSetResourceObject( object, resource_name, o_value )
	GlgObject object;
	char * filename;
	GlgObject o_value;
Parameters
object
Specifies the object whose resource is being set or replaced.
resource_name
Specifies a default attribute name of a resource that is being set or replaced.
o_value
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.

While this function provides the Intermediate API functionality, it may also be used with the Standard API for setting global configuration resources.

GlgSetXform

Adds or deletes transformations attached to an object.

GlgBoolean GlgSetXform( object, xform )
	GlgObject object;
	GlgObject xform;
Parameters
object
Specifies the object to which a transformation is to be attached.
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.

2.7 Real-Time Chart Functions

The following Standard and Intermediate API methods may be used to handle specific aspects of the GLG Real-Time Chart object:

Standard API
Intermediate API

The following sections provide detailed description of these methods.

Chart Functions of the Standard API

GlgAddAnnotation

Adds an annotation to a chart object.

GlgObject GlgAddAnnotation( object, resource_name, annotation,
                            position_x, position_y, add_box )
	GlgObject object;
	char * resource_name;
	GlgObject time_line;
	double position_x;
	double position_y;
	GlgBoolean add_box;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
annotation
Specifies an object ID of an annotation object to add. NULL may be used to create a new annotation.
position_x
Specifies an annotation's position relative to the X axis.
position_y
Specifies an annotation's position relative to the Y axis.
add_box
If set to GlgTrue, a text box will be added to the annotation's text object.

The function returns an object ID of the added annotation on success, or NULL on failure. The returned annotation is referenced only by the chart's annotation array it has been added to and may be destroyed when the chart scrolls. The program should increase the annotation's reference count if it needs to keep a persistent reference to it.

The NumAnnotations attribute of the chart should be set to -1 in order to use this function.

GlgAddPlot

Adds a plot to a chart object.

GlgObject GlgAddPlot( object, resource_name, plot )
	GlgObject object;
	char * resource_name;
	GlgObject plot;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
plot
Specifies an object ID of a plot object. NULL may be used to create a new plot.

The function returns an object ID of the added plot on success, or NULL if it fails. The returned plot is referenced only by the chart's plot array it has been added to and may be destroyed when the number of plots changes. The program should increase the plot's reference count if it needs to keep a persistent reference to the plot.

GlgAddTimeLine

Adds a vertical time line to a chart object.

GlgObject GlgAddTimeLine( object, resource_name, time_line,
                          time_stamp )
	GlgObject object;
	char * resource_name;
	GlgObject time_line;
	double time_stamp;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
time_line
Specifies an object ID of a level line object to be used as a time line. NULL may be used to create a new time line.
time_stamp
Specifies the time stamp to position the time line at. This value will be assigned to the time line's Level attribute.

The function returns an object ID of the added time line on success, or NULL on failure. The returned time line is referenced only by the chart's time line array it has been added to and may be destroyed when the chart scrolls. The program should increase the time line's reference count if it needs to keep a persistent reference to the time line.

The NumTimeLines attribute of the chart should be set to -1 in order to use this function.

GlgClearDataBuffer

Clears accumulated data samples of a real-time chart or one of its plots.

GlgBoolean GlgClearDataBuffer( object, resource_name )
	GlgObject object;
	char * resource_name;
	GlgObject plot;
Parameters
object
Specifies a chart, a plot or a container object containing the chart.
resource_name
If not NULL, specifies a resource name for accessing the chart or one of its plots inside the container specified by the object parameter. Use NULL when the object parameter specifies a chart or plot object.

For a Chart object, GlgClearDataBuffer discards data samples in all plots of the chart. For a Plot object, it discards only the data samples of that plot. The method returns GlgTrue on success

GlgDeleteAnnotation

Deletes an annotation from a chart.

GlgBoolean GlgDeletePlot( object, resource_name, annotation,

         position_x, position_y )
	GlgObject object;
	char * resource_name;
	GlgObject annotation
	double position_x;
	double position_y;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
annotation
Specifies the annotation object to delete. If set to NULL, the annotation with the time stamp specified by the position_x and position_y attributes will be deleted.
position_x, position_y
Specify the position of the annotation to be deleted when the annotation parameter is NULL. The parameter is ignored if annotation is not NULL.

The function returns GlgTrue if the annotation was successfully deleted. The NumAnnotations attribute of the chart should be set to -1 in order to use this function.

GlgDeletePlot

Deletes a plot from a chart.

GlgBoolean GlgDeletePlot( object, resource_name, plot )
	GlgObject object;
	char * resource_name;
	GlgObject plot;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
plot
Specifies the plot to delete. The GlgGetNamedPlot method may be used to obtain a plot's object ID.

The function returns GlgTrue if the plot was successfully deleted.

GlgDeleteTimeLine

Deletes a time line from a chart.

GlgBoolean GlgDeleteTimeLine(object, resource_name, time_line,

               time_stamp )
	GlgObject object;
	char * resource_name;
	GlgObject time_line;
	double time_stamp;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
time_line
Specifies the time line to delete. If set to NULL, the time line with the time stamp specified by the time_stamp attribute will be deleted.
time_stamp
Specifies the time stamp of the time line to be deleted when the time_line parameter is NULL. The parameter is ignored if time_line is not NULL.

The function returns GlgTrue if the time line was successfully deleted. The NumTimeLines attribute of the chart should be set to -1 in order to use this function.

GlgGetChartDataExtent

Queries the minimum and maximum extent of the data accumulated in a chart or in one of its plots.

GlgBoolean GlgGetChartDataExtent( object, resource_name, min_max, 

                 x_extent )
	GlgObject object;
	char * resource_name;
	GlgMinMax min_max;
	GlgBoolean x_extent;
Parameters
object
Specifies a chart, a plot or a container object containing the chart.
resource_name
Specifies a resource name to access the chart inside the container, or a plot inside the chart. Use NULL when the object parameter specifies the chart or its plot.
min_max
Returned data extent. It is defined in the GlgApi.h file:
typedef struct _GlgMinMax	
{
	double min, max;
} GlgMinMax;
x_extent
If GlgTrue, the function returns the X extent, otherwise it returns the Y extent.

If the object and resource_name parameters point to a chart object, the data extent of all plots in the chart is returned. If object and resource_name point to a plot, the data extent of that plot is returned. The object hierarchy must be set up for this function to succeed. The function returns GlgTrue on success.

GlgGetNamedPlot

Given a name of a chart's plot, returns the plot's object ID. The function returns NULL if a plot with the specified name was not found.

GlgObject GlgGetNamedPlot( object, resource_name, plot_name )
	GlgObject object;
	char * resource_name;
	char * plot_name;
Parameters
object
Specifies a chart or a container object containing a chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
plot_name
Specifies the plot name.

GlgGetSelectedPlot

Returns the plot object corresponding to the last legend item selected with the mouse, if any.

GlgObject GlgGetSelectedPlot( void )

If a legend item is selected with the mouse, the corresponding plot is stored internally and returned when the function is invoked. The selected plot is stored indefinitely until it is replaced by a new plot selection. Therefore, if the last mouse selection did not select any legend items, the function returns a previously selected plot, or NULL if no plots were previously selected.

GlgSetLinkedAxis

Associates a chart's plot or a level line with an Y axis for automatic rescaling, returns GlgTrue on success.

GlgBoolean GlgSetLinkedAxis( object, resource_name, axis_object, 
                 axis_resource_name )
	GlgObject object;
	char * resource_name;
	GlgObject axis;
	char * axis_resource_name;
Parameters
object
Specifies a plot or a level line, or a parent object containing the plot or the level line.
resource_name
Specifies a resource name for accessing the plot or the level line inside the parent. Use NULL when the object parameter specifies the plot or the level line.
axis_object
Specifies the axis to link with, or a parent of the axis.
axis_resource_name
Specifies a resource name for accessing the axis inside the parent. Use NULL when the axis_object parameter specifies an axis.

GlgSetLabelFormatter

Attaches a custom label formatter to a stand-alone axis object or an axis of a chart, returns GlgTrue on success.

GlgBoolean GlgSetLabelFormatter( object, resource_name, formatter )
	GlgObject object;
	char * resource_name;
	GlgLabelFormatter formatter;
Parameters
object
Specifies a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the chart inside the container. Use NULL when the object parameter specifies the chart.
formatter
Specifies a custom label formatter.

A label formatter is a function which is invoked every time a new label string needs to be generated. It can create and return a label string, or return NULL to use a default label string. When the created label string is no longer needed, it will be freed by the Toolkit using the GlgFree call. Therefore, it must be allocated using GlgAlloc or one of the GLG string utility functions, such as GlgStrClone or GlgConcatStrings. All custom label formatters have the following function prototype:

typedef char * (*GlgLabelFormatter)

( GlgObject object, GlgLong label_type,

  GlgLong value_type, double value, time_t sec, 

  double fractional_sec, void * reserved );

A custom label formatter is invoked with the following parameters:

object
The axis object the formatter is attached to.
label_type
The type of an axis label to be generated: GLG_TICK_LABEL_TYPE for major tick labels,
GLG_SELECTION_LABEL_TYPE for chart selection labels and GLG_TOOLTIP_LABEL_TYPE for chart tooltip labels.

A label formatter may be invoked by the chart selection or chart tooltip methods if an axis label is requested by the selection or tooltip formats.
value_type
The type of the axis value: GLG_TIME_VALUE or GLG_NUMERICAL_VALUE.
value
The label's X value or time stamp.
sec
An integer number of seconds since the Epoch corresponding to the label position (time axes only).
fractional_sec
A label's fractional number of seconds.
reserved
Is reserved for future use, must be NULL.

GlgSetChartFilter

Attaches a custom data filter to a chart's plot, returns GlgTrue on success.

GlgBoolean GlgSetChartFilter( object, resource_name, filter, 
                  client_data )
	GlgObject object;
	char * resource_name;
	GlgChartFilter filter;
	void * client_data;
Parameters
object
Specifies a chart's plot, a chart or a container object containing the chart.
resource_name
Specifies a resource name for accessing the plot inside the container. Use NULL when the object parameter specifies the plot.
filter
Specifies a custom data filter.
client_data
Specifies data to be passed to the custom filter.

A data filter is a function which is invoked by a chart to aggregate the plot's data. A custom data filter has the following function prototype:

typedef GlgLong (*GlgChartFilter)

( GlgChartFilterCBReason reason, 

  GlgChartFilterData * filter_data, void * client_data );

A custom data filter is invoked with the following parameters:

reason
The reason the filter is invoked.
filter_data
Contains data passed to the filter by the chart.
client_data
Contains client data passed to the filter by the application when the filter was attached to the plot.

The src subdirectory of the GLG installation contains source code of custom filter examples for various programming environments (CustomChartFilter.c, CustomChartFilter.java and CustomChartFilter.cs) that provide extensive self-documented examples of custom filters. Each example implements several types of custom filters (MIN_MAX, AVERAGE and DISCARD), and contains detailed explanation of all possible values of the reason parameter, as well as the fields of the filter_data structure.

Chart Functions of the Intermediate API

GlgAddDataSampleNode

Adds a data sample to a chart, is used to prefill the chart with large number of samples:

void GlgAddDataSampleNode( plot, datasample_node, quick_mode )
	GlgObject plot;
	GlgDataSampleNode * datasample_node;
	GlgBoolean quick_mode;
Parameters
plot
A chart's plot to add datasample to.
datasample_node
A data sample node containing the data sample to be added. The GlgCreateDataSampleNode function may be used to create data sample nodes.
quick_mode
The quick mode may be activated to increase prefill speed by bypassing the chart scrolling and auto-scaling when adding data samples. When the last data sample is added, the chart can be scrolled by setting the EndValue of the chart's Time axis to the data sample's time stamp. To auto-scale the chart when prefilling is finished, set the chart's AutoScale attribute to a desired value.

This function is used to enhance performance when prefilling a chart with a large number of data samples. For periodic updates, new data may be pushed into the plot's entry points using GlgSetDResource.

The RealTime Chart Demo provides an coding example of prefilling a chart.

GlgCreateDataSampleNode

Creates a data sample node structure to be used with the GlgAddDataSampleNode function:

GlgDataSampleNode * GlgCreateDataSampleNode( plot, extended )
	GlgObject plot;
	GlgBoolean extended;
Parameters
plot
An optional plot the data sample node will be added to. If provided, a new data sample node will be taken from the plot's cache, if possible.
extended
Specifies the type of the data sample to be created inside the node. If set to GlgTrue, an extended data sample (GlgDataSampleExt) is created, otherwise a data sample (GlgDataSample) is created.

The GlgGetNodeDataSample function can be used to get access to the node's data sample. The fields of the data sample structure must be filled before adding it to the plot.

GlgGetNodeDataSample

Returns the node's data sample. Depending on the type of the data sample contained in the node, returns either GlgDataSample or GlgDataSampleExt pointer that can be used to fill the data sample's fields before adding it to the chart.

GlgDataSample * GlgGetNodeDataSample( node )
	GlgDataSampleNode node;
Parameters
node
A data sample node.

GlgFreeDataSampleNode

Returns a data sample node to the plot cache or the global node cache for reuse.

void GlgFreeDataSampleNode( plot, node )
	GlgObject plot;
	GlgBoolean extended;
Parameters
plot
An optional plot the data sample node belongs to. If provided, the data sample node will be returned to the plot's cache. Otherwise, the node will be returned to the global cache.
node
The data sample node to be freed.

GlgCreateChartSelection

Selects a chart's data sample closest to the specified position and returns a message object containing the selected sample's information.

GlgObject GlgCreateChartSelection( object, plot, x, y, dx, dy,

                       screen_coord, include_invalid, 
                       x_priority )
	GlgObject object;
	GlgObject plot;
	double x, y; 
	double dx, dy;
	GlgBoolean screen_coord; 
	GlgBoolean include_invalid; 
	GlgBoolean x_priority;
Parameters
object
Specifies a chart object. If the plot parameter is NULL, the function queries samples in all plots of the chart and selects the sample closest to the specified position.
plot
Specifies an optional plot object. If it is not NULL, the function queries only the samples in that plot.
x, y
Specifies the position inside the chart. If the screen_coord parameter is set to GlgTrue, the position is defined in the screen coordinates of the chart's parent viewport. If screen_coord is set to GlgFalse, the x position is defined as an X or time value, and the y position is defined in relative coordinates in the range [0; 1] to allow the chart to process selection for plots with different ranges (0 corresponds to the Low range of each plot, and 1 to the High range).

When the mouse position is used, add GLG_COORD_MAPPING_ADJ to the x and y screen coordinates of the mouse for precise mapping.
dx, dy
Specify an extent around the point defined by the x and y parameters. The extent is defined in the same coordinates as x and y, depending on the value of the screen_coord parameter. Only the data samples located within the dx and dy distances of the specified position are considered for the selection.
screen_coord
Specifies the type of the x and y coordinates. If set to GlgTrue, the x and y parameters supply screen coordinates in the chart's parent viewport, otherwise they supply relative coordinates.
include_invalid
If set to GlgTrue, invalid data samples are considered for selection, otherwise invalid samples are never selected.
x_priority
If set to GlgTrue, the function selects the data sample closest to the specified position in the horizontal direction with no regards to its distance from the specified position in the vertical direction. If it is set to GlgFalse, a data sample with the closest distance from the specified position is selected.

The information about the selected data sample is returned in the form of a message object described in the Chart Selection Message Object section on page 458. The function returns NULL if no data sample matching the selection criteria was found. The returned message object must be dereferenced using the GlgDropObject function when finished.

GlgCreateTooltipString

Creates and returns a chart or axis tooltip string corresponding to the specified position in screen coordinates. The string can be used to provide cursor feedback and display information about the data sample under the current mouse position, as shown in the Real-Time Strip-Chart demo.

char * GlgCreateTooltipString( object, x, y, dx, dy, format )
	GlgObject object;
	double x, y; 
	double dx, dy;
	char * format;
Parameters
object
Specifies a chart or axis object for creating the tooltip.
x, y
Specifies a screen position on top of a chart or an axis. When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's x and y screen coordinates for precise mapping.
dx, dy
Specify the maximum extent in screen pixels around the specified position.
format
Provides a custom format for creating a tooltip string and uses the same syntax as the TooltipFormat attributes of the chart and axis objects. If it is set to NULL or an empty string, the format provided by the TooltipFormat attribute of the chart or the axis will be used. A special "<single_line>" tag may be prepended to the format string to force the function to remove all line breaks from the returned tooltip string. A "<chart_only>" tag may also be prepended to search only for a chart tooltip and disable search for the axes' tooltips when the function is invoked for a chart object.

If the object parameter specifies a chart, and the selected position is within the chart's data area, the function selects a data sample closest to the specified position and returns a tooltip string containing information about the sample. The dx and dy parameters define the maximum extent for selecting a data sample, and the TooltipMode attribute of the chart defines the data sample selection mode: X or XY. The function returns NULL if no samples matching the selection criteria were found.

If the object parameter specifies an axis, or if the object parameter specifies a chart and the selected position is on top of one of the chart's axes, the function returns a tooltip string that displays the axis value corresponding to the specified position.

The returned string must be freed using the GlgFree function.

GlgGetLegendSelection

Returns the plot object corresponding to the legend item at the specified position, if any. If no legend item is found at the specified position, NULL is returned.

GlgObject GlgGetLegendSelection( object, x, y )
	GlgObject object;
	double x, y; 
Parameters
object
Specifies a legend object.
x, y
Specifies the position in screen coordinates of the viewport containing the legend.

GlgPositionToValue

Returns a value corresponding to the specified position on top of a chart or an axis object.

GlgBoolean GlgPositionToValue( object, resource_name, x, y,

                  outside_x, outside_y, value )
	GlgObject object;
	char * resource_name;
	double x, y; 
	GlgBoolean outside_x, outside_y; 
	double * value;
Parameters
object
If resource_name is NULL, specifies a chart, a plot or an axis object, otherwise it specifies a container object containing a chart, a plot or an axis.
resource_name
Specifies a resource path of a child chart, plot or axis object relative to the container object.
x, y

Specify a position in the screen coordinates of the parent viewport. When using the cursor position, add GLG_COORD_MAPPING_ADJ to the cursor's x and y coordinates for precise mapping.

outside_x, outside_y
If set to GlgTrue, the function returns GlgFalse if the specified position is outside of the chart or the axis in the corresponding direction.
value
A pointer to the returned value.

For a plot, the function converts the specified position to a Y value in the Low/High range of the plot and returns the value through the value pointer.

For an axis, the function converts the specified position to the axis value and returns the value.

For a chart, the function converts the specified position to the X or time value of the chart's X axis and returns the value.

The function returns GlgTrue on success.

2.8 GIS Object Functions

The following Standard API methods may be used to handle user interaction with the GLG GIS object:

GIS Function Descriptions

GlgGISConvert

Performs coordinate conversion from the GIS coordinates of the GIS Object to the GLG coordinates of the drawing and visa versa.

GlgBoolean GlgGISConvert( object, resource_name, coord_type, 
coord_to_lat_lon, in_point, out_point )
	GlgObject object;
	char * resource_name;
	GlgCoordType coord_type;
	GlgBoolean coord_to_lat_lon;
	GlgPoint * in_point;
	GlgPoint * out_point;
Parameters
object
If the resource_name parameter is NULL, specifies the GIS Object whose coordinate system to use for conversion. If the resource_name parameter is not NULL, specifies a parent of the GIS Object.
resource_name
If not NULL, specifies the resource name of the GIS Object inside the parent object specified by the object parameter.
coordinate_type
The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_OBJECT_COORD for world coordinates.
coord_to_lat_lon
GlgTrue to convert from GLG coordinates to GIS longitude and latitude, GlgFalse to convert from GIS to GLG coordinates.
in_point
A pointer to the GlgPoint structure containing coordinate values to be converted.
out_point
A pointer to the GlgPoint structure that receives converted coordinate values.

The function returns GlgTrue if conversion succeeds. When converting from GLG to GIS coordinates, the Z coordinate is set to a negative GLG_GIS_OUTSIDE_VALUE value for points on the invisible part of the globe.

The GlmConvert function of may be used to perform coordinate conversion between GIS and GLG coordinates without the use of the GIS object.

GlgGISCreateSelection

Provides a high-level interface to the map server's GlmGetSelection function; returns a message object containing information about GIS features located at a specified position on the map.

GlgObject GlgGISCreateSelection( object, resource_name, layers, 

x, y, select_labels)
	GlgObject object;
	char * resource_name;
	char * layers;
	double x, y;
	GlgLong select_labels;
Parameters
object
If the resource_name parameter is NULL, specifies the GIS Object to query. If the resource_name parameter is not NULL, specifies a parent of the GIS Object.
resource_name
If not NULL, specifies the resource name of the GIS Object inside the parent object specified by the object parameter.
layers
A list of layers to query.
x, y
Specifies coordinates of a point in the screen coordinates of a viewport that contains the GIS object.
select_labels
Specifies the label selection mode, can have the following values (defined in the GlmLabelSelectionMode enum in the GlmApi.h file):
The layer's settings have precedence over the select_labels parameter. The labels will be considered for selection only for the layers that do not override it by setting their LABEL SELECTION MODE = NONE in the layer's LIF file. If LABEL SELECTION MODE = INTILE, the labels will always be considered using the IN_TILE precision.

The function returns a message object containing information about the selected GIS features. The message object has to be dereferenced using the GlgDropObject function when finished.

If the GIS verbosity level is set to 2000 or 2001, extended information is also written into the error log file and printed to the terminal on Linux/Unix for debugging purposes.

Refer to the GlmGetSelection section on page 129 of the GLG Map Server Reference Manual for information on the structure of the returned message object as well as a programming example that demonstrates how to handle it.

GlgGISGetDataset

Returns a dataset object associated with the GIS object:

GlgObject GlgGISGetDataset( object, resource_name )
	GlgObject object;
	char * resource_name;
Parameters
object
If the resource_name parameter is NULL, specifies the GIS Object to query. If the resource_name parameter is not NULL, specifies a parent of the GIS Object.
resource_name
If not NULL, specifies the resource name of the GIS Object inside the parent object specified by the object parameter.

The function may be invoked after the GIS object has been setup to retrieve its dataset. The dataset may be used to dynamically change attributes of individual layers displayed in the GIS object. The program can use GlgSetResource methods for changing layer attributes. Refer to the GLG Map Server Reference Manual for information on layer attributes. The GLG GIS Demo provides an example of changing layer attributes programmatically.

GlgGISGetElevation

Returns an elevation of a lat/lon point on a map:

GlgBoolean GlgGISGetElevation( object, resource_name, layer_name, 

lon, lat, elevation )
	GlgObject object;
	char * resource_name;
	double lon, lat;
	double * elevation;
Parameters
object
If the resource_name parameter is NULL, specifies the GIS Object to query. If the resource_name parameter is not NULL, specifies a parent of the GIS Object.
resource_name
If not NULL, specifies the resource name of the GIS Object inside the parent object specified by the object parameter.
layer_name
The name of the layer with elevation data to query.
lon, lat
The lon/lat coordinates of a point on the map.
elevation
A pointer to the variable of a double type that will receive the returned elevation data.

The function returns GlgFalse if the point is outside of the map in the ORTHOGRAPHIC projection or if there is no elevation data for the specified location. If the function returns GlgTrue, the elevation value is returned in the units (such as meters or feet) defined by the elevation data file.

GlmConvert

A low level function that performs coordinate conversion from the GIS coordinates of a map to the GLG coordinates of the drawing and visa versa without the help of a GLG GIS Object. Since the function does not rely on a GIS Object being displayed and set up, it may be used before the drawing is rendered or without a drawing at all.

void GlmConvert( projection, stretch, coord_type, coord_to_lat_lon, 
center, extent, angle, 

min_x, max_x, min_y, max_y, in_point, out_point )
	GlgProjectionType projection;
	GlgBoolean stretch;
	GlgCoordType coord_type;
	GlgBoolean coord_to_lat_lon;
	GlgPoint * center, * extent;
	double angle;
	double min_x, max_x, min_y, max_y;
	GlgPoint * in_point, * out_point;
Parameters
projection
A GIS map projection, may have values of GLG_RECTANGULAR or GLG_ORTHOGRAPHIC.
stretch
Specifies if the map preserves the X/Y ratio (GlgFalse) or not (GlgTrue).
coordinate_type
The type of the GLG coordinate system to convert to or from: GLG_SCREEN_COORD for screen coordinates or GLG_OBJECT_COORD for world coordinates.
coord_to_lat_lon
GlgTrue to convert from GLG coordinates to GIS longitude and latitude, GlgFalse to convert from GIS to GLG coordinates.
center
A pointer to the GlgPoint structure containing lat/lon coordinates of the map center. The Z coordinate must be set to 0.
extent
A pointer to the GlgPoint structure containing X and Y extent of the map in the selected projection: in degrees for the rectangular projection or in meters for orthographic. The Z extent must be set to 0. Refer to 1, 2
angle
A map rotation angle in degrees.
min_x, max_x, min_y, max_y
A map extent in the selected coordinate system. To get X/Y coordinates relative to the map image origin, use min_x=0, min_y=0, max_x=image_width, max_y=image_height.
in_point
A pointer to the GlgPoint structure containing coordinate values to be converted.
out_point
A pointer to the GlgPoint structure that receives converted coordinate values.

When converting from X/Y to lat/lon coordinates in the orthographic projection, the Z coordinate is set to a negative value for points on the invisible part of the globe or outside the globe area, and to zero for points on the edge of the globe. The coordinates of the returned point may be outside of the visible portion of the map for all projections.

2.9 GLG Installable Interface Handlers

GLG Installable Interface Handler Utilities assist an application developer with implementing functionality of complex user interactions usually encountered in editor-style applications. The utilities include a collection of methods as part of the GLG Intermediate API library and are available for the C/C++, Java, C#/.NET and JavaScript environments. The GLG Diagram demo provides an example of a custom diagraming editor application implemented using the GLG Installable Interface Handlers functionality.

The mechanism of interface handlers facilitates rapid application development for writing elaborate GUI with sophisticated application functionality for handling user interaction.

Overview

Installable Interface Handlers (referred to as interface handlers in the rest of this manual) provide a mechanism for handling user interaction where persistency is necessary to handle interrelated sequences of user actions. The interface handlers are hierarchical, allowing an application to handle nested operations, such as nested dialogs or chained operations. Internally, a stack is used to maintain a hierarchy of handlers, making it possible to handle arbitrary nested sequences, for example display a confirmation dialog based on the action of the parent dialog (such as parent dialog closing).

The use of the stack allows to easily pass control to the previous handler in the stack after the currently active handler is uninstalled and deleted from the stack. The handlers also automate the flow of control: if the currently active handler on the bottom of the stack is not interested in the event, it can uninstall itself from the stack and pass the event to the previous handler on the stack, which, in turn, can pass the event further to the next handler in the stack.

For example, a top-level handler can be used to handle events from toolbar icons and main pull-down menu, and a nested second-level handler can be installed to handle a popup dialog. A third-level handler can be used to confirm closing of the dialog managed by the second handler. When the dialog closing is confirmed, the third and then the second handlers are uninstalled (get removed from the stack), and the control returns to the main top-level handler.

Each handler maintains its own persistent data storage for intermediate data, which is automatically cleaned up when the handler is uninstalled. A variable number of dynamic parameters can be supplied to each handler to modify its behavior as needed. Parameters can be either optional or mandatory. Optional parameters allow the developer to extend a handler's functionality while maintaining backward compatibility.

User interaction events passed to an interface handler are encoded as integer tokens for efficiency and are passed to the currently active handler (the bottom handler currently stored on a stack).

The source code for each handler is provided by an application; the code handles a set of user interaction events identified by the tokens. A handler is typically designed to handle a particular set of tokens, for example tokens for an Apply or Cancel button for a specific dialog. If an unrecognized token is encountered, the handler can either ignore the event to implement a modal dialog, or it can uninstall itself and pass the event to the parent handler, which, in turn, can pass it to its parent, and so on.

Interface handlers extend functionality of event handling callbacks and listeners (referred collectively as callbacks in the rest of this section). A disadvantage of a callback is that it does not provide data persistency: when a callback is invoked to handle a particular event, any changes to an application state have to be kept in an external global structure shared by all callbacks. A callback exits after processing each event and does not provide any means for storing intermediate interaction state in the callback itself. For example, if a dialog has several buttons, individual callbacks are invoked on each button press event, making it difficult to implement a single integrated event handler for the dialog as a whole.

GLG interface handlers address this problem by providing event handlers that support persistency and provide data storage for intermediate data that control user interaction. An interface handler stays active to process all events for a dialog or a page, until the handler is uninstalled when dialog closes or a page is switched to display another page. The interface handlers provide a flexible alternative to the Hierarchical State Machines (HMS) that are often used to handle the state of the user interface transitions. Unlike HMS, interface handlers allow a developer to extend the handler functionality by adding handler parameters and augment the handler source code based on the parameter values passed to it, which could be easier than adding new states to the state machine.

The GLG Diagram demo provides examples of implementing several design patterns for handling various types of user interaction. Many other alternative options of using the interface handlers are possible, and an application can implement any desirable design pattern depending on the application requirements.

List of Functions

The following Installable Interaction Handlers functions are provided as a part of the GLG Intermediate API library:

Function Descriptions

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"

GlgIHInit

Initializes installable handler utilities, must be invoked after GlgInit, but before any installable handler methods.

void GlgIHInit()

GlgIHTerminate

Terminates installable handler utilities. All currently installed handlers must be uninstalled before invoking this method.

void GlgIHTerminate()

GlgIHGlobalData

Returns the global data container.

void GlgIHGlobalData()

GlgIHInstall

Creates a handler with the specified entry point and installs the handler.

GlgIH GlgIHInstall( GlgIHEntryPoint func )

The function creates the handler, adds it to a stack of handlers and returns the handler's ID. The stack of handlers is used to keep track of nested handlers; the last handler pushed onto the stack becomes the active handler, referred to as the current handler in the rest of this manual.

The func parameter specifies the entry point function of the new handler with the following function prototype:

void GlgIHEntryPoint( GlgIH ih, GlgCallEvent call_event )

The handler's entry point is invoked with the call_event parameter that provides the user interface event. The ih parameter provides the ID of the handler the entry point belongs to, and can be used to access parameters stored in the handler's data storage. The code of this function implements functionality of the handler. Parameters can be passed to a handler after is has been installed. An example of a handler code is shown in the description of the GlgIHStart function below.

GlgIHStart

Invokes the handler's entry point with the GLG_HI_SETUP_EVENT event, which allows the handler to perform any desired initialization, such as displaying a dialog associated with the handler, if any.

void GlgIHStart()

Parameters can be passed to a handler by storing them in the installed handler's data storage via SetParameter methods prior to invoking GlgIHStart, as shown in the following example:

GlgIHInstall( ConfirmIH )
GlgIHSetOParameter( GLG_IH_NEW, "ok_dialog", ok_dialog );
GlgIHSetSParameter( GLG_IH_NEW, "message", "OK to discard changes?" );
GlgIHStart();

The first argument of the SetParameter methods defines the handler to add parameters to. For convenience, a GLG_IH_NEW macro can be used to supply the ID of the just installed handler instead of using the handler ID returned by GlgIHInstall, as shown in the above example.

The following shows an example of a handler code that uses parameters from the above example to initialize the handler. The handler displays a confirmation dialog with a supplied message on start up and closes it when the handler is uninstalled. An optional modal parameter specifies if the dialog is modal.

void ConfirmIH( GlgIH ih, GlgCallEvent call_event )
{
	GlgObject ok_dialog;
	char * message;
	GlgCallEventType event_type;
	GlgIHToken token;

	ok_dialog = GlgGetOParameter( ih, dialog );
	event_type = GlgIHGetType( call_event );
   switch( event_type )
   {
	 case GLG_HI_SETUP_EVENT:
		message = GlgIHGetOptSParameter( ih, "message" );
		GlgSetSResource( ok_dialog, "DialogMessageString", message );
		GlgSetDResource( ok_dialog, "Visibility", 1. );
		GlgUpdate( ok_dialog );
		break;
		
	 case GLG_MESSAGE_EVENT:
      token = GlgIHGetToken( call_event );
      switch( token )
		{
		 case IH_OK:
		 case IH_CANCEL:
			/* Pass selection to the parent. */
			GlgIHUninstallWithToken( token );
			break;

		 default: 
         if( GlgIHGetOptIParameter( ih, "modal_dialog", GlgFalse ) )
			   /* Don't allow to leave in a modal mode.*/
			   GlgBell( Viewport );
			else
			   /* Pass event to the parent. */
			   GlgIHUninstallWithEvent( call_event );
         break;
		
	 case GLG_CLEANUP_EVENT:
		GlgSetDResource( ok_dialog, "Visibility", 0. );
		GlgUpdate( ok_dialog );
		break;
	}
}

The IH_OK and IH_CANCEL tokens used in the above example are generated by the GLG Input callback that converts interface events to integer tokens for efficiency. The tokens are then passed to the currently active handler via the GlgIHCallCurrIHWithToken function call. Refer to the GLG Diagram demo for a complete source code example.

GlgIHResetup

Invokes the handler's entry point with the GLG_HI_RESETUP_EVENT event.

void GlgIHResetup( GlgIH ih )

GlgIHResetup can be used to reinitialize the handler by sharing some of the GLG_HI_SETUP_EVENT code, as shown in the following example:

void ConfirmIH( GlgIH ih, GlgCallEvent call_event )
{
	GlgObject ok_dialog;
	char * message;
	GlgCallEventType event_type;
	int token;

	ok_dialog = GlgGetOParameter( ih, dialog );
	event_type = GlgIHGetType( call_event );
   switch( event_type )
   {
	 case GLG_HI_SETUP_EVENT:
		message = GlgIHGetOptSParameter( ih, "message" );
		GlgSetSResource( ok_dialog, "DialogMessageString", message );
		/* Fall through to popup the dialog. */
	 case GLG_HI_RESETUP_EVENT: /* Popup the dialog again. */
		GlgSetDResource( ok_dialog, "Visibility", 1. );
		GlgUpdate( dialog );
		break;
		
	...
	}
}

GlgIHUninstall

Uninstalls the current handler (the last handler on the stack).

void GlgIHUninstall()

The handler's entry point is invoked with the GLG_CLEANUP_EVENT event prior to uninstalling to let the handler perform any required cleanup. After the handler is uninstalled, a previous handler in the stack (if any) becomes the active current handler.

Uninstalling a handler deletes its stored data and invalidates its ID; the ID should not be used after the handler has been uninstalled.

GlgIHUninstallWithToken

Uninstalls the handler using GlgIHUninstall and invokes the previous handler (which becomes current after GlgIHUninstall is invoked) with the specified token.

void GlgIHUninstallWithToken( GlgIHToken token )

GlgIHUninstallWithEvent

Uninstalls the handler using GlgIHUninstall and passes the event to the previous handler (which becomes current after GlgIHUninstall is invoked).

void GlgIHUninstallWithEvent( GlgCallEvent call_event )

GlgIHGetType

Returns event's type.

GlgCallEventType GlgIHGetType( GlgCallEvent call_event )

The type can be one of the following:

GLG_HI_SETUP_EVENT
received when the handler is started using GlgIHStart; is used to perform any required initialization.
GLG_HI_RESETUP_EVENT
received when the handler is reinitialized via GlgIHResetup.
GLG_CLEANUP_EVENT
received before destroying the handler when it is uninstalled; is used to perform any required cleanup.
GLG_MESSAGE_EVENT
a message event that is further identified by an associated token.

GlgIHGetToken

Returns a token associated with the GLG_MESSAGE_EVENT event.

GlgIHToken GlgIHGetToken( GlgCallEvent call_event )

Tokens are application-defined integer values used to uniquely identify each user interaction event. For example, IH_OK token can be associated with pressing dialog's OK button, and IH_MOUSE_MOVED can identify a mouse move event that provides coordinates of the cursor. Integer values are used to allow efficient event processing using switch statements. An enum is usually used to define tokens, for example:

enum MyTokens
{
	IH_UNDEFINED_TOKEN = 0,
	IH_OK,
	IH_CANCEL
}

In a GLG application, Input and Trace callbacks are used to convert interface events to tokens, as shown in the GLG Diagram demo. The tokens are then passed to the currently active handler via the GlgIHCallCurrIHWithToken function call.

GlgIHCallCurrIHWithToken

Invokes the entry point of the current handler (the last handler on the stack) with the specified token.

GlgBoolean GlgIHCallCurrIHWithToken( GlgIHToken token )

Returns GlgTrue if the handler was uninstalled as a result of processing the token.

The function creates a call event object used to pass the token to the handler, and destroys the event object when done.

GlgIHCallCurrIHWithModifToken

Same as GlgIHCallCurrIHWithToken, but it reuses the existing event by setting its token instead of creating a new call event to pass the token to the handler.

GlgBoolean GlgIHCallCurrIHWithModifToken( GlgCallEvent call_event,

                               GlgIHToken token )

Returns GlgTrue if the handler was uninstalled as a result of processing the token.

GlgIHCallCurrIH

Passes the event to the entry pointy of the current handler.

GlgBoolean GlgIHCallCurrIH( GlgCallEvent call_event )

Returns GlgTrue if the handler was uninstalled as a result of processing the event.

GlgIHCallPrevIHWithToken

Passes the token to the parent handler of the currently active handler. The parent handler is the handler preceding the current handler on the stack.

void GlgIHCallPrevIHWithToken( GlgIHToken token )

Please note that when the parent handler is invoked, the current handler is not the parent handler, but the handler that invoked it. Therefore, the parent handler cannot uninstall itself by simply calling GlgIHUninstall.

GlgIHCallPrevIHWithModifToken

Same as GlgIHCallPrevIHWithToken, but reuses the event object for efficiency, the same way as GlgIHCallCurrIHWithModifToken.

void GlgIHCallPrevIHWithModifToken( GlgCallEvent call_event,

                         GlgIHToken token )

GlgIHGetCurrIH

Returns the ID of the current handler.

GlgIH GlgIHGetCurrIH()

GlgIHGetFunction

Returns the function used to implement the handler.

GlgIHEntryPoint GlgIHGetFunction( GlgIH ih )

The GLG_IH_CURR macro can be used as the ih parameter to access the current handler.

The following example demonstrates the use of GlgIHGetFunction to identify the currently active handler.

extern GlgIHEntryPoint MyIH;

if( GlgIHGetFunction( GLG_IH_CURR ) == MyIH )
	...

GlgIHGetPrevIH

Returns the ID of the current handler's parent handler.

GlgIH GlgIHGetPrevIH()

GlgIHGetPrevFunction

Returns the function used to implement the parent handler of the currently active handler. The parent handler is the handler preceding the current handler on the stack.

GlgIHEntryPoint GlgIHGetPrevFunction()

GlgIHPassToken

Installs the specified handler and invokes its entry point with the specified token.

void GlgIHPassToken( GlgIHEntryPoint func, GlgIHToken token,

         GlgBoolean uninstall )

If the uninstall parameter is GlgTrue, the handler is uninstalled after processing the token, unless the handler has already uninstalled itself. If the handler installs other handlers while processing the token, the last installed handler (the current handler) will be uninstalled instead of the handler the token is passed to.

This function is used to implement pass-through handlers for processing global accelerators, stateless options, as well as managing floating stay-open dialogs, such as the Edit Properties dialog shown on the GlgDiagram demo.

GlgIHSetIParameter

GlgIHSetDParameter

GlgIHSetSParameter

GlgIHSetOParameter

GlgIHSetPParameter

GlgIHSetOParameterFromD

GlgIHSetOParameterFromG

Create a named parameter of a requested type: I (integer), D (double), S (string), O (GLG object) or P (pointer).

GlgIHSetOParameterFromD and GlgIHSetOParameterFromG create a GLG data object parameter containing double (D) or geometrical (G) data.

void GlgIHSetIParameter( GlgIH ih, char * name, GlgLong value )
void GlgIHSetDParameter( GlgIH ih, char * name, double value )
void GlgIHSetSParameter( GlgIH ih, char * name, char * value )
void GlgIHSetOParameter( GlgIH ih, char * name, GlgObject value )
void GlgIHSetPParameter( GlgIH ih, char * name, void * value )
void GlgIHSetOParameterFromD( GlgIH ih, char * name, double value );
void GlgIHSetOParameterFromG( GlgIH ih, char * name, double value1,

                  double value2, double value3 );

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GetParameter functions. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

A parameter is added to the data storage of the handler specified by the ih argument. The GLG_IH_CURR macro can be used to specify the currently active handler, which can eliminate the need to pass the handler ID into all functions the handler may invoke.

The GLG_IH_GLOBAL macro can be used to add parameters to the global data storage.

When parameters are added, string parameters are cloned and object parameters are referenced. When the handler is uninstalled, all parameters stored in its data storage are automatically cleaned: string parameters are freed and object parameters are dereferenced. If pointer parameters are used to store addresses of allocated memory, the memory should be freed, as shown in the following example.

case GLG_HI_SETUP:
	ptr = malloc( sizeof my_struct );
	GlgIHSetPParameter( ih, "my__struct", ptr );
break;

...

case GLG_IH_CLEANUP:
	ptr = GlgIGGetPParameter( ptr );
	free( ptr );
	break;

GlgIHChangeIParameter

GlgIHChangeDParameter

GlgIHChangeSParameter

GlgIHChangeOParameter

GlgIHChangePParameter

Same as corresponding SetParameter functions, except that the named parameter must exist. If the parameter does not exist, a GLG error is generated.

void GlgIHChangeIParameter( GlgIH ih, char * name, GlgLong value )
void GlgIHChangeDParameter( GlgIH ih, char * name, double value )
void GlgIHChangeSParameter( GlgIH ih, char * name, char * value )
void GlgIHChangeOParameter( GlgIH ih, char * name, GlgObject value )
void GlgIHChangePParameter( GlgIH ih, char * name, void * value )

GlgIHGetIParameter

GlgIHGetDParameter

GlgIHGetSParameter

GlgIHGetOParameter

GlgIHGetPParameter

Return a value of a named parameter of a requested type: I (integer), D (double), S (string), O (GLG object) or P (pointer).

GlgLong GlgIHGetIParameter( GlgIH ih, char * name )
double GlgIHGetDParameter( GlgIH ih, char * name )
char * GlgIHGetSParameter( GlgIH ih, char * name )
GlgObject GlgIHGetOParameter( GlgIH ih, char * name )
void * GlgIHGetPParameter( GlgIH ih, char * name )

A GLG error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested type.

For string parameters, a returned string pointer is not allocated and should not be modified, as it points to the internal string stored in the data storage.

GlgIHGetOptIParameter

GlgIHGetOptDParameter

GlgIHGetOptSParameter

GlgIHGetOptOParameter

GlgIHGetOptPParameter

Same as the corresponding GetParameter functions, except that the named parameter is optional. If a parameter with the requested name does not exist, a default value provided by the default_value argument is returned.

GlgLong GlgIHGetOptIParameter( GlgIH ih, char * name, 

                   GlgLong default_value )
double GlgIHGetOptDParameter( GlgIH ih, char * name, 

                  double default_value )
char * GlgIHGetOptSParameter( GlgIH ih, char * name, 

                  char * default_value )
GlgObject GlgIHGetOptOParameter( GlgIH ih, char * name, 

                     GlgObject default_value )
void * GlgIHGetOptPParameter( GlgIH ih, char * name, 

                  void * default_value )


Generic Logic, Inc.
www.genlogic.com
PREV NEXT