GLG Objects

Common Attributes

Name
An object's name is its entry in the resource hierarchy. An object need not have a name.

HasResources
Controls where in the resource hierarchy the names of an object's children appear. For more information about this flag and the subject of "resource transparency", see Hierarchy of Resources in Structure of a GLG Drawing.

Xform
A slot for attaching an optional transformation object. A Concatenate transformation type may be used to attach a list of several transformations. The list is accessed by using the Edit Dynamics buttons in the Builder. The Xform attribute assumes the value of NULL if no transformation is attached.

Common Attributes of Graphical Objects

Visibility
The Visibility attribute of a graphical object controls whether the object is displayed or not. This attribute is a floating point value that can range between 0 and 1. A value of 1 indicates that the object is visible; a value of 0 makes the object invisible. The values between 0 and 1 make the object transparent, with the object transparency increasing as the visibility value decreases. The transparency effect does not apply to the viewports.

Negative values of Visibility have a special meaning and are handled as dimming. A visibility value between -1 and 0 causes object colors to be dimmed by decreasing their saturation. The closer the value is to 0, the duller the object colors become. If the visibility value is negative but its absolute value is bigger than 1, the object's colors will be brightened. The dimming effect may be used to change appearance of icons when they are desensitized.

The dimming and transparency of a container object are inherited by all its children. The child's visibility may further alter the child's rendering, with the effective visibility value calculated by multiplying the child's visibility value by the visibility values of all its parents.

For environments with the OpenGL support (the OpenGL and Java versions of the Toolkit), the transparency is rendered as true alpha-blending. For non-OpenGL versions of the Toolkit, the transparency is supported only in the Unix environment, where it is simulated using dithering patterns, except for the image objects.
Transparency is not supported in the Postscript output.

MoveByXform
This attribute specifies whether an object's control point values are actually modified when the object or its points are moved or transformed using the Transform Object Points button. If the MoveByXform flag is NO, when you move an object, you reassign the spatial coordinates of its control points. If the flag is set to YES, then a move of that object simply creates a matrix transformation attached to that object. This is useful if you need to preserve the original coordinates of an object's points.

CoordFlag
This advanced attribute specifies the coordinate system used for rendering the object. If set to GLG_INHERIT_COORD_SYSTEM ("INHERIT" label), the coordinate system used to interpret coordinates of the object's control points is inherited from the viewport in which the object is drawn. When CoordFlag is set to GLG_ABS_SCREEN_COORD_SYSTEM ("ABS_SCR" label), the screen coordinate system is used. The GLG_ABS_FLIPPED_SCREEN_COORD_SYSTEM setting ("GLG_SCR" label) uses the GLG screen coordinate system which has the same upper left origin as the screen coordinate system, but has the Y axis pointing up. The screen coordinate systems may be used for rendering prompts and overlays which do not change their position when the drawing is zoomed or resized.

History
A slot for attaching one or more optional History objects. A group is used to attach a list of history objects. The list is accessible by using the Edit History buttons on the Object Menu. The attribute assumes the value of NULL if no History objects are attached.

Aliases
A slot for attaching one or more optional Alias objects. A group is used to attach a list of aliases. The list is accessible by using the Edit Aliases buttons on the Object Menu. The attribute assumes the value of NULL if no Alias objects are attached.

CustomData
A slot for attaching one or more optional Custom Data Properties . A group is used to attach a list of properties. The list is accessible by using the Edit Custom Properties buttons on the Object Menu. The attribute assumes the value of NULL if no Custom Properties are attached. In order to minimize memory consumption, custom properties may only be attached to graphical objects (polygons, viewports, text objects, etc.).

Rendering
A slot for attaching an optional Rendering object to control an expanded set of rendering attributes, such as gradient fill, cast shadows, fill level and arrow heads. The rendering object is accessible by using the Add/Edit Rendering buttons in the Object Properties dialog. To delete the rendering object, use the Delete Rendering button in the Rendering Object properties. The attribute assumes the value of NULL if no rendering object is attached. See Rendering on page 83 for details.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Common Attributes of Attribute and Data Objects

Global
This attribute is used to establish the relationship between the attributes of an object, and the attributes of copies of that object. In general, the global attributes of two copied objects are constrained to each other. For example, if a polygon has a global FillColor attribute, any copies made of it using a copy operation other than a Full Copy will have their FillColor attributes constrained to that of the original. The Global attribute has three possible values for controlling such attribute constraints: GLOBAL, LOCAL, and SEMI-GLOBAL. The last value is used by specialized copy operations; see, for example, GlgCloneObject in The GLG Extended API.

The Global attribute also has a special BOUND value which is used for rebinding attributes or reference objects and subdrawings. Refer to Reference on page 70 for more details.

Though most of the objects described in this chapter use these attributes, they are not separately described in the lists that follow.

The control points of objects are also omitted. Objects may have either a fixed (marker, text, etc.) or variable (polygon) number of control points. For objects with a fixed number of points, the points can be accessed using the Point1, Point2, ..., PointN default attribute names. For objects with a variable number of points, the points can be accessed using functions which access a container's elements. A user can also make control points into named resources by granting them names in the Builder.

The lists in the following sections include only attributes with default names other then control points.

Polygon

The polygon is a basic graphical object, and is used to represent both lines and polygons. A line in a GLG drawing is simply an open polygon, while most shapes are represented by closed polygons of one sort or another. A straight line is a two-point polygon.

The polygon is basic to the structure of a GLG drawing in other ways. Arcs, parallelograms, splines and connectors inherit their attributes from a polygon.

A simple polygon has a control point at each vertex. It also has the following attributes:

FillColor
The color of the polygon's interior, if it is filled.

EdgeColor
The color of the polygon's defining line or edge.

LineWidth
The thickness of a polygon's edge. Lines with odd line width use round line ends. Lines with an even line width use square ends. The intermediate connections of a multi-line polygon always use rounded connections.

LineType
The line pattern (solid, dashed, etc.) for rendering the edge of the polygon.

FillType
Defines how a polygon is rendered. The choices are formed by combining the three possible choices by ORing together their binary constants:

GLG_FILL - enables rendering of the polygon's fill using FillColor

GLG_EDGE - enables rendering of the polygon's edge using EdgeColor

GLG_LINE_FILL - used with the GLG_EDGE to render the outer edges of thick lines using EdgeColor and the middle part using FillColor.

OpenType
Defines whether or not the line connecting the first and the last points of the polygon is drawn. It does not have any effect on polygons with fewer than three points.

Shading
Disables shading for an individual polygon. Shading is enabled for the viewport if it has a light object added to it.

AntiAliasing
Controls antialiasing of the polygon's edges and may have the following values:

GLG_ANTI_ALIASING_INHERIT

Inherit antialiasing settings from the global setting, which is GLG_ANTI_ALIASING_INT by default.

GLG_ANTI_ALIASING_OFF

Disable antialiasing.

GLG_ANTI_ALIASING_INT

Enable antialiasing and map vertices to integer pixel boundaries. This matches the coordinate mapping of the native non-OpenGL renderer and makes the straight lines look sharper.

GLG_ANTI_ALIASING_DBL

Enables antialiasing and uses double vertex coordinates. This setting makes the curved lines look better. It is used as a default setting for arcs and spline objects.

The antialiasing is enabled only for the viewports that use the OpenGL renderer and have their OpenGLHint=ON . The antialiasing can be set globally by using the GlgAntiAliasing global configuration resource. This attribute is ignored in the Java version of the Toolkit.

Point List
A list of polygon's control point. Allows you to change the order of points in the polygon as well as add and delete points from the polygon.

Rendering
A slot for attaching an optional Rendering object to control an expanded set of rendering attributes, such as gradient fill, cast shadows, fill level and arrow heads. The rendering object is accessible by using the Add/Edit Rendering buttons in the Object Properties dialog. To delete the rendering object, use the Delete Rendering button in the Rendering Object properties. The attribute assumes the value of NULL if no rendering object is attached. See Rendering on page 83 for details.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Parallelogram

A parallelogram is a four sided polygon that includes implicit constraints to keep the opposite sides parallel. The parallelogram has only three control points and one constrained point. The attributes of a parallelogram are the same as the attributes of a polygon except that, because a parallelogram is always closed, the OpenType attribute is not present.

When a parallelogram is "exploded" in the Builder it becomes a regular four-sided polygon. The constraints that keep its sides parallel are removed, and the fourth point becomes a simple control point.

Note that there is no "Rectangle" object. The GLG Graphics Builder has a "rectangle" button, but this simply creates a parallelogram with right angles between its sides. This is because a parallelogram needs three points to be uniquely defined in three-dimensional space. The Builder allows you to create a rectangle by selecting two points, but this is just a convenience. The third point is automatically selected for you according to the current view.

Arc

The Arc object is used to represent both arcs and circles. One part of an arc is a section of a circle's perimeter. A chord arc simply joins the two ends of the curve with a straight line, while a sector arc is shaped like a piece of a pie, with two straight lines joined at the center of the circle describing the extent of the third, curved side. A circle is simply the special case of an arc whose interior angle is 360°.

An arc has two control points: a center and a vector point. A vector from the center point to the vector point defines a line perpendicular to the arc plane. As you move either of the two ends of this vector, you can see the arc twist in space. The length of this normal vector is not used, only its orientation in space.

Since the arc vector is perpendicular to the arc plane, the vector point of the arc coincides with its arc's center point in the main projection. Also, visually, the vector point is on top of the center point, so selecting the point in the center of the arc and moving it rotates the arc's vector instead of moving the arc's center point. To access the center point, use Shift+click and the point selection arrows in the Control Point dialog, and use the Object Move Point to move the arc.

Like the parallelogram, the arc is simply a special case (sub-class) of the polygon, so it has the usual polygon attributes, like LineType and FillColor . In addition, an arc has the following attributes:

ArcFillType
Defines the type of the arc: GLG_CHORD or GLG_SECTOR.

AngleType
Defines the way the arc's angles are defined. Possible choices are GLG_START_AND_ANGLE and GLG_START_AND_END.

StartAngle and EndAngle
Define the angular position of the start and end points of the arc relative to its center. The angles are measured in degrees (counter clockwise). The StartAngle is always measured from the 3 o'clock position. The EndAngle is measured relative the StartAngle if AngleType is set to GLG_START_AND_ANGLE, and relative to the 3'o'clock position if the value of AngleType is GLG_START_AND_END. A circle is represented as an arc with a start angle of 0° and an end angle of 360°.

Radius
Defines a radius of an arc's curved edge.

Resolution
The arc's resolution is the number of line segments used to render its perimeter. A circle drawn with a resolution of 5 is simply a regular pentagon. The default value for this is 100. A smaller value may be used for small arcs and circles to increase performance.

As with the parallelogram, an arc may be exploded in the Builder into its constituent polygon. The center and vector control points disappear, and simple polygon control points are shown on the arc's perimeter.

Spline

The spline is a multi-point Bezier or Catmull Rom cubic spline used to render curves in 2D or 3D space. A one-segment spline is a parametrically represented curve controlled by 4 control points. The shape of the segment may be changed by dragging the control points. The multi-point spline is a "blending" of one or more spline segments with a variable number of points. The spline starts and ends at the first and last control points respectively. The intermediate control points control the curvature and shape of the spline.

Like the parallelogram, the spline is a special case of the polygon, so it has the usual polygon attributes, like LineType and FillColor . The spline has two additional attributes:

SplineType
Defines the type of a spline, GLG_B_SPLINE (Bezier) or GLG_C-SPLINE (Catmull Rom). The Catmull Rom spline passes through the control points, while the Bezier spline yields a smoother curve due to its continuous second derivative.

SplineResolution
The spline's resolution is the number of line segments used to render each spline segment. The default value for this is 10. A larger value may be used to increase the rendering quality of splines with large segments or high curvature.

Text

The text object is used to place labels and legends on a GLG drawing. There are four types of text object, which differ both in their behavior and in the number of control points:

FIXED
Has one control point defining its position. The text font size is defined by the FontSize attribute, and is not controlled by a bounding rectangle.

SCALED
Text has two control points defining a rectangle in which to fit the text. The FontSize attribute defines the maximum and the MinFontSize attribute controls the minimum size allowed. The actual size of the font is determined dynamically by constraining the text to the rectangle. Note that the scaling done is not infinitely variable: different sizes of text are selected from the fonts in the font table according to the size of the bounding rectangle. Setting MinFontSize to -1 may be used for automatic text label decluttering, in which case the text will disappear if the drawing is zoomed out of and there is not enough space to draw the text inside the rectangle.

SPACED
Text has three control points. The letters of the text are evenly distributed along the line connecting the first two points. For multi-line text, all text lines are parallel to the first line, and the start position of each line is aligned with the line connecting the first and third control points. Similar to the SCALED text, the SPACED text is fit to the parallelogram defined by it's tree control points, with the FontSize and MinFontSize defining the maximum and minimum font sizes for scaling.

SCROLLED
Text has two control points, same as a SCALED text, but fitting is done only in the vertical direction. It also has a cursor, which allows using the object in a text input widget. It's superseded by the native text input objects.

All text objects have the following attributes (in addition to control points):

TextColor
Defines the color of the text.

Compatibility Note: The name of this attribute changed in the release 2.9. Previously, the default attribute name for this attribute was EdgeColor. The GlgCompatibilityMode global configuration resource may be set to obtain behavior compatible with the earlier versions.

TextString
This is the text string displayed by the text object. If the text string contains the \n (ASCII NL:) and \r (ASCII CR) characters, they will be used as line separators and the text will be displayed in multiple lines. The TextString of a multi-line text can be edited only by using the text edit field of the Attribute Object dialog (ellipsis button ).

TextType
Can have the following values:

FIXED (GLG_FIXED_TEXT)
SCALED (GLG_AUTOSCALED_TEXT)
SPACED (GLG_SPACED_TEXT)
SCROLLED (GLG_SCROLLED_TEXT).

Direction
Defines whether text is GLG_HORIZONTAL, GLG_VERTICAL, GLG_VERTICAL_ROTATED_RIGHT or GLG_VERTICAL_ROTATED_LEFT.

Anchor
Defines vertical and horizontal.text alignments relative to the text's control point for the FIXED text, or within the text bounding box for other text types. The choices are CENTER, LEFT, or RIGHT for horizontal alignment, and CENTER, TOP, or BOTTOM for the vertical.

The corresponding defined constants are GLG_HCENTER, GLG_HLEFT, GLG_HRIGHT and GLG_VCENTER, GLG_VTOP, GLG_VBOTTOM. The two choices are combined (logical OR) to define the resource value.

FontType
Specifies the type of the font used to draw the text.The FontType is the row index in the font table attribute for a viewport. (Each viewport can have its own font table.)

FontSize
Defines the font size of the FIXED text, or the maximum font size to use for fitting other text types. The FontSize is a column index to the viewport's font table. That is, the FontType specifies a row in the font table, and the FontSize specifies the column.

MinFontSize
Specifies the minimum font size to use when fitting the text.The MinFontSize is a column index to the viewport's font table. Setting MinFontSize to -1 activates automatic decluttering feature for SCALED and SPACED text types. In the case the text will not be drawn if there is not enough space to fit the smallest font (0) into the text area.

SizeConstraint
This attribute is used to synchronize the fitting of SCALED and SPACED text objects. If more than one text object is used, fitting may yield different font sizes due to different area sizes or different string lengths of each text object. As a result, they will be rendered using different font sizes.

The actual value of this attribute is irrelevant, because it is determined dynamically. However, if the attribute is constrained, all text objects with constrained SizeConstraint attributes will vary together, using the same font size regardless of the string length and other conditions. The MinFontSize for all constrained text objects has to be set to the same value as well.

If several text objects have constrained SizeConstraint attributes, they all will be displayed using the smallest needed font size in the group. To avoid constraint loops, the font size will stay small until the drawing is resized, even if the original reason for using the small font size has been eliminated.

Text Box
A slot for attaching an optional Box Attributes object to control attributes of an optional box drawn around a text object. A filled box may be used to provide a background for drawing a text object. The box attributes object is accessible by using the Add/Edit Text Box buttons in the Object Properties dialog. To delete box attributes, use the Delete Text Box button in the Box Attributes Object properties. The attribute assumes the value of NULL if no box attributes object is attached, in which case no box is drawn. See BoxAttributes on page 85 for details.

When a box attributes object is added to all text objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added box attribute objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Rendering
A slot for attaching an optional Rendering object to control an expanded set of rendering attributes, such as gradient fill, cast shadows, fill level and arrowheads. The rendering object is accessible by using the Add/Edit Rendering buttons in the Object Properties dialog. To delete the rendering object, use the Delete Rendering button in the Rendering Object properties. The attribute assumes the value of NULL if no rendering object is attached. See Rendering on page 83 for details.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Note that a text object's behavior under various graphical transformations is limited by the availability of suitable fonts. For reasons of efficiency, GLG text objects contain text displayed in un-transformed fonts, taken from the viewport's font table. This limits a text object's ability to react appropriately to shear and scale transformations, for example, but greatly improves real-time update performance by eliminating multiple instances of similar fonts scaled slightly differently.

Marker

The marker object is used to mark a position in space. For example, a point graph might be presented as a collection of marker objects arranged on a graph. It has a fixed size, and does not change when a window is resized.

Markers have only one control point defining their position. A marker object also has the following attributes:

MarkerType
Defines the shape of the marker. When drawn, a marker consists of components like cross, rectangle, filled rectangle, circle, filled circle and dot. Any mix of components can be chosen to represent a marker as defined by the marker type. The components are chosen from the following list:

CROSS

SQUARE

FILLED SQUARE

CIRCLE

FILLED CIRCLE

DOT

DIAMOND

FILLED_DIAMOND

The marker drawn is a superposition (Logical OR) of the set chosen by the MarkerType value.

MarkerSize
Defines the size of the marker in pixels.

FillColor and EdgeColor
Define colors used to draw marker's components.

Rendering
A slot for attaching an optional Rendering object to control an expanded set of rendering attributes, such as gradient fill, cast shadows, fill level and arrow heads. The rendering object is accessible by using the Add/Edit Rendering buttons in the Object Properties dialog. To delete the rendering object, use the Delete Rendering button in the Rendering Object properties. The attribute assumes the value of NULL if no rendering object is attached. See Rendering on page 83 for details.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Image

The image object is used to represent graphical images in GIF, JPEG and BMP formats. The GIF and JPEG formats are supported across all platforms, while the BMP format is supported only in the C/C++ version on Windows. TIFF images are also supported in the Java version of the Toolkit. Transparent colors in GIF images are supported in the OpenGL renderer mode and in the Java version of the Toolkit. The image transparency is also supported via the Visibility attribute.

An image may be of fixed size, defined by the size of the image in the original file, and have one control point. The image object may also be resizable, in which case it's size is adjusted to fit the rectangle defined by the image's two control points.

An image object has the following attributes:

ImageType
Defines the type of the image: a fixed-size (GLG_FIXED_IMAGE) with 1 control point or a scalable (GLG_SCALED_IMAGE) with two control points.

ImageFile
Defines the location of the image file in the GIF or BMP format. The type of the file is determined by the file's extension:

.gif for a GIF file,

.jpg for a JPEG file,

.bmp for a Windows bitmap.

If the ImageFile attribute defines a relative file name, the Toolkit tries to find the file it in the following order:

- attempting to load the file relative to the current directory

- attempting to load the file relative to the directory of the drawing

- trying to locate the file in one of the directories defined by the GLG_PATH environment variable or the GlgSearchPath configuration parameter.

A List transformation may be attached to the ImageFile attribute to specify a list of image files for implementing image dynamics.

Anchor
Defines the vertical and horizontal alignments of the fixed size image relative to its control point. The choices are CENTER, LEFT, or RIGHT for horizontal alignment, and CENTER, TOP, or BOTTOM for the vertical.

The corresponding defined constants are GLG_HCENTER, GLG_HLEFT, GLG_HRIGHT and GLG_VCENTER, GLG_VTOP, GLG_VBOTTOM. The two choices are combined (logical OR) to define the resource value. The attribute has no effect for scalable images.

GIS Object

Generic Logic provides a GIS Map Server product designed for real-time rendering of high-resolution maps with millions of objects. There are a variety of applications that might need to display a map in the background as contextual information, and place GLG objects on top of the map to represent dynamic or static icons. Such applications need to provide map zooming and panning functionality, handle window resizing and user interaction with the icons.

The GIS Object seamlessly integrates Map Server functionality into the GLG drawing, both in the application and in the Graphics Builder. The GIS Object displays a map image in a selected GIS projection and transparently handles all aspects of interaction with the Map Server, automatically issuing map requests every time the map is resized, panned or zoomed.

The GIS Object supports integrated zooming and panning, as well as integrated scrollbars. In the GIS Zoom Mode, zoom and pan controls zoom and pan the map displayed in the GIS Object instead of zooming and panning the viewport's drawing. The map can also be dragged with the mouse, which works best with either fast CPUs or not very complex maps. In the Builder, the GIS Zoom Mode may be set by using the Set as parent viewport's GIS Object option in the Arrange menu while the GIS Object is selected. The GIS Zoom Mode is persistent and is saved with the drawing.

The map displayed in the GIS Object can also be zoomed and panned programmatically via the GlgSetZoom method. Refer to the description of the Pan and ZoomEnabled attributes of a viewport object on page 59 and page 60 correspondingly for details of the integrated GIS Zooming.

The GIS Object can be used as a container that holds dynamic icons, polylines and other graphical objects. The objects added to the GIS Object are drawn on the map in the GIS Rendering Mode, in which the coordinates of the objects' control points are interpreted as lat/lon coordinates. This allows positioning of icons and lines on the map by defining their lat/lon coordinates directly, without any coordinate conversions. When the map is zoomed or panned, the objects drawn on the map will be automatically adjusted to zoom and scroll with the map. The GIS Object also provides utilities to convert from screen or world coordinates to latitude/longitude in the selected projection and vise versa.

The Graphics Builder supports the GIS Editing Mode for interactive creating and editing objects drawn on the map. In this mode, dynamic icons, polylines and other objects can be drawn or positioned on the map with the mouse in the lat/lon coordinates. The Builder automatically converts the mouse position from the screen to lat/lon coordinates, which are stored in the object's control points. The Builder transparently handles GIS projections, which allows the user to draw polylines on top of the globe displayed in the orthographic projection. To start the GIS Editing Mode, select the GIS Object, then press the Hierarchy Down button to go down into it. In the GIS Editing Mode, you can draw and position objects on top of the map with the mouse, as well as edit attributes of the previously created objects. All objects added to the GIS Object in the GIS Editing Mode will be contained in its GISArray and will be saved with the GIS Object. Dynamic icons and other graphical objects may also be added to the GIS Object programmatically at run time using one of the GlgAddObject methods. The GLG GIS Demo and GLG AirTraffic Control Demo may be used as source code examples of adding dynamic icons at run-time.

The two control points of the GIS Object define the size of the map image. When the GIS Object is used to provide a background map for the drawing, its points' values may be set to (-1000, -1000, 0) and (1000, 1000, 0) to cover the whole drawing (in the Builder, Shift -click on the control point with the mouse to enter exact coordinates).

The following attributes of the GIS Object provide easy resource-based access to the underlying Map Server functionality (refer to the GLG Map Server Reference Manual for more information):

FillColor
Defines the color of the map's background, which is visible when the map is sufficiently zoomed out.

GISDisabled
Disables the GIS Object for quick editing.

GISProjection
Defines the projection used to render the map: GLG_RECTANGULAR_PROJECTION or GLG_ORTHOGRAPHIC_PROJECTION. The rectangular projection displays the world as a rectangular region and is convenient for displaying detailed maps, where parallels and meridians appear as straight lines. The orthographic projection maps the whole world onto a sphere, and is often used for the top-level globe-like views.

GISCenter
Defines the latitude and longitude of the map to be displayed in the center of the GIS Object. This attribute is of the geometrical (G) type and is a set of three values. The first two values supply the longitude and latitude correspondingly, while the third value must be set to zero. The attribute is automatically adjusted when integrated GIS panning is performed.

GISExtent
Defines the extent of the map visible in the GIS Object. This attribute is of the geometrical (G) type and is a set of three values. The first two values supply the X and Y extents, while the third value must be set to zero. For the rectangular projection the extents are measured in degrees of the longitude and latitude. For the orthographic projection the extents are specified in meters as dictated by the Open GIS Standard. The default extent value for the orthographic projection is 14,000,000, which is slightly bigger then the earth's diameter. The attribute is automatically adjusted when integrated GIS zooming is performed.

GISAngle
Defines the map rotation angle in degrees. For example, an application can set the rotation angle to display a map from the point of view of an airplane pilot. The map rotation feature is supported only in the rectangular projection; the attribute's value is ignored in the orthographic projection. The attribute is automatically adjusted when integrated GIS rotation is performed.

GISStretch
Defines the stretch mode. If the attribute is set to YES, the map is stretched, otherwise the aspect ratio of the map is preserved and the map image may include an area which is slightly bigger then the area defined by the GISExtent attribute.

GISDataFile
Specifies a Server Data File (.sdf) which describes the dataset to be used by the Map Server to generate the map image. It may be specified using either a relative or absolute path. This attribute is used only by the C/C++ and ActiveX version of the Toolkit, as well as the Graphics Builder, which use the Map Server in the form of a C library.

GISMapServerURL
Specifies the Map Server URL to be used by the Java version of the Toolkit. The URL has to have a web server based GLG Map Server setup as described in the GLG Map Server Reference Manual. This attribute only affects the Java version of the Toolkit, which connects to a web-based GLG Map Server to retrieve the map image. The GIS Object handles all aspects of connecting to the Map Server URL with proper parameters.

GISLayers
Defines a list of layers to be displayed in the generated image. The value of this attribute is a comma separated list of layer names, defined in the Server Data File (.sdf). The "default" string may be used to enable the layers whose "DEFAULT ON" attribute is set to YES in the Layer's Information File (.lif). See the GLG Map Server Reference Manual for details.

GISArray
A group object used as a container to hold graphical objects that will be drawn on top of the map. GLG objects added to the GIS Object in the Builder are placed into this group. The content of the group is rendered in the GIS Rendering Mode, which interprets coordinates of the objects' control points as lat/lon coordinates. The objects may be added programmatically either to the GIS Object or directly to its GISArray. When objects are added to the GIS Object, they are placed into its GISArray group.

GISVerbosity
May be set to a value from 0 (no debugging output) to 10 (maximum debugging output) to assist debugging of the Map Server setup. It may also be set to a negative value in the range from -1 (overall performance data) to -3 (the most detailed per-tile performance data) to display performance measuring information. The attribute may also be set to a value of 1001 to display tile extents. This attribute has no effect in the Java version of the Toolkit.

GISDiscardData
Controls Map Server data caching. If set to NO (default), the Map Server data is cached resulting in faster image generation. For map images that are generated only once or very infrequently, the attribute may be set to YES to discard data after generating the image, saving memory. This attribute has no effect in the Java version of the Toolkit.

The GIS Object may be prototyped in the Builder by going down into it using the Hierarchy Down button. The zoom and pan controls may be used to zoom and pan the map, testing the automatic layer switching of the GLG Map Server and the map server setup. Alternatively, the GIS Zoom Mode may be set by using the Set as Parent's Viewport GIS Object option of the Arrange menu. With the GIS Zoom Mode activated, the map in a viewport can be zoomed and scrolled with the Builder's zoom and pan controls without going down into the GIS Object. The viewport's Pan property may be set to Pan XY to use the viewport's integrated scrollbars for scrolling the map.

The icons and other GLG objects drawn on the map in the GIS Rendering Mode are clipped to the visible area of the map, which eliminates icons on the invisible part of the globe in the ORTHOGRAPHIC projection. In the ORTHOGRAPHIC projection, the polyline segments on the invisible part of the globe are also eliminated. When rendering polylines that span the whole globe in the ORTHOGRAPHIC projection, it is recommended to use a sufficient number of points for better rendering of polyline segments that cross the boundary between the visible and invisible parts of the globe.

Refer to the GLG Map Server Reference Manual for more information on the GLG Map Server, its setup and usage.

Viewport

A viewport object is a GLG encapsulation of a window, and is rendered as a non-transparent rectangular region into which graphical objects can be placed. You can think of it as the drawing surface for a GLG drawing. Unlike a simple rectangle, however, the viewport object contains the objects that appear in front of it (which can include other viewports). This creates a convenient way to group objects in a GLG drawing. A viewport can control the resizing of its member objects, as well as the magnification, angle, and lighting with which a drawing is seen.

A viewport also differs from a simple rectangle in that it always appears in the plane parallel to the screen. You cannot view a viewport from an oblique angle.

The viewport has its own coordinate system with the origin at the center of the viewport and the Z axis perpendicular to the plane of the viewport's rectangle. The corners of the viewport are [-1000,-1000] and [1000,1000] in the viewport's coordinate system, and this mapping is maintained when the viewport is resized. The viewport's coordinate system is used to interpret the coordinates of any objects drawn in the viewport. When the viewport is resized, all objects within are resized as well.

Panning and zooming affects the mapping of the viewport's coordinate system. For example, if the viewport is zoomed in to by a factor of 2, the corners of the viewport will correspond to (-500 -500) and (500 500) instead of (-1000 -1000) and (1000 1000) without zooming.

To add objects to the viewport, the editing focus has to be moved in the viewport, by either going "down" into the viewport using the Hierarchy Down button , or by setting the editing focus by Ctrl-Shift-clicking on the viewport. When finished, use the use the Hierarchy Up button or the Main Focus button , depending on the action used to set the focus inside the viewport.

Note: If the focus was moved into the viewport, the Hierarchy Down button will be disabled. To traverse down into the viewport's objects, use the Hierarchy Down button to get inside the viewport, and then use it again to get inside the viewport's objects.

A widget is defined to be a viewport that has resources ( HasResources is YES) and is named $Widget . When the GLG API reads a drawing from a file, it looks for a widget definition to use. The widget name should appear only once in a drawing. All subsequent resource read and set operations implicitly refer to this object. In an application, a viewport could be used to define a graph or a control.

A viewport's attributes may be divided into four categories. The first group of attributes controls the appearance of the viewport's background rectangle, and the second controls the display of its child objects. A third group of attributes controls some aspects of event handling and viewport interactive behavior. The last group is made up of window-specific attributes, and is embodied by the screen object, described in the next section.

In addition to the two control points, the viewport backing rectangle has the following attributes:

FillColor
Defines a background color of the viewport.

EdgeColor
Defines a border color for the viewport rectangle.

LineWidth
Defines the viewport rectangle's border width.

ShadowWidth
Defines the width of shadows. If the value differs from 0, the shadow bevels are drawn around the borders of the viewport. The sign of the ShadowWidth controls the type of the bevels: raised shadows for positive values and depressed shadows for negative values. This attribute is inherited from the viewport's screen object described below.

DepthSort
The DepthSort attribute defines how to render overlapping objects inside the viewport by controlling hidden surface removal. A hidden surface is one whose view is fully or partially blocked by another object. For example, a drawing might consist of two circles. If you look at the circles from an angle where the position of one circle is between the viewer and the other circle, the blocked circle will not appear to be drawn if the objects are depth-sorted.

The algorithm used to sort objects is known not to work in some complicated cases, but provides much faster real time graphics than other techniques and works well for all the GLG Graph Widgets. However, since any depth-sorting algorithm slows down the update procedure for a drawing, use it only when necessary.

This attribute may be set to NO, YES, INHERIT, PARTS, or SPECIAL. Only NO, YES and SPECIAL can be applied to viewports and are used to turn depth sorting off and on. SPECIAL uses a faster but less precise depth sorting algorithm, described in more detail in Group. The other options have no meaning for viewports, but are used for other objects that use this attribute, such as groups. A viewport cannot inherit the DepthSort attribute.

Pan
The Pan attribute controls integrated scrolling. If panning is activated, the viewport displays scrollbars and handles scrolling when the drawing extends beyond the viewport's visible area. In the GIS Zoom Mode, the scrollbars control scrolling of the map displayed in the viewport's GIS Object.The possible values are GLG_PAN_X, GLG_PAN_Y or GLG_PAN_XY. The first two values enable only one X or Y scrollbar, while the last value enables both scrollbars.

When the scrollbars are enabled, they may be accessed as the GlgPanX and GlgPanY resources of the viewport. When both scrollbars are enabled, a viewport object named GlgPanSpacer is also created to cover the lower right corner area between the scrollbars.

 

ZoomEnabled
The ZoomEnabled attribute controls integrated zooming and panning. If it is set to YES, the viewport handles the following accelerator keys:

i - zoom in

o - zoom out

Shift-click-drag - ZoomTo (see details below)

t - start ZoomTo mode (click and drag the mouse to finish)

T - start custom ZoomTo mode (see details below)

e - abort ZoomTo mode

Control-click-drag - Drag the drawing or map with the mouse (see details below)

s - start dragging mode (click and drag the mouse to finish)

f - fit the drawing to the visible area of the viewport

F - fit the area of the drawing defined by an object named GlgFitArea to the visible area of the viewport

n - reset zoom. In the GIS zoom mode with map in the ORTHOGRAPHIC projection, resets zooming, but keeps the GIS center unchanged. In the RECTANGULAR projection, resets zooming and paning, but keeps the rotation angle unchanged.

N - reset zoom.

u - pan up

d - pan down

l - pan left

r - pan right

U - anchor on the upper edge of the drawing

D - anchor on the lower edge of the drawing

R - anchor on the right edge of the drawing

L - anchor on the lower edge of the drawing

A - rotate the drawing clockwise around X axis

a - rotate the drawing counterclockwise around X axis

B - rotate the drawing clockwise around Y axis

b - rotate the drawing counterclockwise around Y axis

C - rotate the drawing clockwise around Z axis

c - rotate the drawing counterclockwise around Z axis

g - If the mouse is located on top of a GIS Object, sets the viewport's GIS Zoom Mode and remembers the selected GIS Object. In the GIS zoom mode, the map displayed in the GIS Object is zoomed and panned instead of the viewport's drawing. Zooming, panning, ZoomTo and reset accelerators are supported in the GIS zoom mode.

G - Resets the GIS Zoom Mode.

p - in the GIS Zoom Mode, displays the lat/lon and X/Y coordinates of the point at the current cursor position. If the GLG_GIS_ELEVATION_LAYER environment variable is set to a valid elevation layer name, the point's elevation is also displayed.

In the Builder, the zoom and pan accelerators are active only in the Run mode. If ZoomEnabled is set to NO, the accelerators are disabled at run time, but the integrated zooming and panning may still be accessed programmatically via the GlgSetZoom method. The GlgSetZoom method takes accelerator keys listed above as its zoom type parameter.

There are two accelerators for the ZoomTo operation: t and T. The operation can be performed by pressing the `t' key, then using the left mouse button to click and drag the mouse to define the area to zoom to. The user can also zoom to an area by holding the Shift key and then using the left mouse button to click and drag the mouse to define a zooming rectangle. A custom zoom mode is started with `T' and displays the zooming rectangle without performing the zoom operation. It is used for applications that want to provide custom zooming or object selection logic using the selected rectangle as the input.

The s accelerator starts panning by dragging the drawing with the mouse. In the GIS Zoom Mode, the map is scrolled by dragging it with the mouse. To start, press the `s' key, then click and drag the mouse to scroll the map. The user can also use the Control-click-drag sequence. The s accelerator is primarily used for starting the dragging operation under the control of a programming API.

Performing zoom and pan actions on a viewport generates Zoom and Pan messages. Refer to Appendix B: Message Object Resources of the GLG Programming Reference Manual for details.

ZoomFactor
A read-only attribute of the viewport showing the current zoom factor; may be used to implement custom decluttering (turning layers on or off depending on the zoom factor) or icons of constant size. This attribute is not displayed in the viewport's Property dialog, but is accessible as a resource.

XYRatio
A read-only attribute of the viewport showing the current X/Y ratio of the viewport's window. It may be used to implement icons of constant X/Y ratio for a viewport with Stretch enabled, so that the icons will keep their X/Y ratio constant while other objects in the drawing will stretch. This attribute is not displayed in the viewport's Property dialog, but is accessible as a resource.

ProcessMouse
Controls processing of the mouse move and mouse click events by the viewport and may have the following values:

None (GLG_NO_MOUSE_EVENTS)
Disables event processing for the viewport. May be used to reduce consumption of the CPU's resources for the viewports that do not need to process any events.

Click (GLG_MOUSE_CLICK)
Enables processing of object selection, custom events and highlighting on the mouse click events in the viewport.

Move and Click (GLG_MOUSE_MOVE_AND_CLICK)
Enables processing of object selection, custom events, highlighting and the tooltips on mouse over events.

Move & Click (Named) (GLG_MOUSE_MOVE_AND_CLICK_NAMED)
Same as Move and Click, but causes object names to be used as the tooltips instead of the objects' TooltipString properties.

The value of the viewport's ProcessMouse attribute is inherited by any child viewports which have ProcessMouse set to None. For example, setting ProcessMouse to process mouse click events for the viewport will enable mouse click processing for all its children.

Refer to Integrated Features of the GLG Drawing on page 103 for details on custom events, highlighting and object tooltips.

Handler
A viewport may become an input widget (or control) by naming an input handler with this attribute. The Handler attribute identifies the style of control that is adopted, such as slider, knob, switch, and so on. The use of input handlers is described in Input Objects.

HandlerDisabled
Controls whether or not a viewport input handler reacts to input events. This attribute may be set to NO or YES.

Light
A slot for attaching an optional Light object to control the viewport's lighting and 3D shading. The Add/Edit Light button may be used to add a light object to the viewport or edit its attributes if it already exists. To delete the Light object, use the Delete Light button in the Light Object properties. See Light Object on page 90 for details.

When a Light object is added to all viewports in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added Light objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Rendering
A slot for attaching an optional Rendering object to control an expanded set of rendering attributes for the gradient fill. Other rendering attributes, such as cast shadows, fill level and arrow heads, are ignored for the viewport. The rendering object is accessible by using the Add/Edit Rendering buttons in the Object Properties dialog. To delete the rendering object, use the Delete Rendering button in the Rendering Object Properties. The attribute assumes the value of NULL if no rendering object is attached. See Rendering on page 83 for details.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Zooming and Viewing Transformations
Each viewport automatically creates a Matrix transformation, which is used for zooming when the viewport is edited in the Builder as well as for integrated zooming and panning at run-time.

User-defined viewing transformations (e.g. Scale , Move, Rotate, Shear) may also be added directly to the viewport to implement user-controlled zooming, panning or 3D rotating functionalities, which otherwise would require creating a group to contain all objects in the viewport and attaching the transformations to the group. Attaching the viewing transformations directly to the viewport makes it more convenient by eliminating an extra group.

To add a viewing transformation, move the focus inside the viewport, make sure no objects are selected, display the viewport's properties and press the Add Dynamics button to add a viewing transformation. Notice that selecting the viewport and adding dynamics adds a transformation to the viewport, transforming its control points, while adding dynamics with the focus inside the viewport adds a viewing transformation which affects the way the objects in the viewport are drawn.

After adding a viewing transformation, the default zooming transformation of the viewport can also be accessed in the Builder. This matrix transformation must always be present, and the Builder prevents it from being deleted or reordered.You can give this transformation a name to access it from a program as a named resource.

A viewport has a secondary screen object which is always attached to the viewport and controls its window-specific display attributes. Use the More button to display screen's properties.

Screen

The screen object is a mandatory child object of a viewport. It is designed to contain window specific attributes of a viewport, and is created automatically every time a viewport is created. It has the following attributes:

Double Buffering
Controls the usage of the double buffering for a screen. This may be set to NO or YES. When set to YES, screen updates are done incrementally off-screen, and all changed portions of the entire screen are updated at once. This usually creates a smoother illusion of motion than updating objects directly on the screen. Double-buffering is turned on by default. It can be useful to turn it off to see updates as they go in complicated drawings, such as a surface graph. If you have a lot of viewports, double buffering may turn to be an expensive resource, as it causes the window manager to allocate memory for the off-screen pixmaps. Turn it off if you want to decrease the amount of memory consumed.

Warning : Double buffering is known to cause problems when zooming with high zoom factors in a viewport that has other viewports in it. Zooming in the parent viewport increases the size of the child viewport. If the child viewport has double buffering set to YES, the excessive increase of the size causes the graphics server to exhaust memory trying to allocate a huge off-screen pixmap. The GLG Toolkit driver tries to catch this condition and disables double buffering, producing an error message if the viewport size becomes too big. But it may be too late in some cases. Turn double buffering off for the children viewports if planning to zoom into the parent viewport with big zoom factors.

When the OpenGL driver is used, the OpenGL's double buffering capabilities are used instead of the off-screen pixmap, which reduces memory consumption and increases rendering speed.

Resizable
Controls whether or not objects in the viewport are resized when the size of the viewport's window is changed. This attribute may be accessed programmatically using the CoordSystem resource name and may have the following values:

YES (WORLD) ( GLG_WORLD_COORD_SYSTEM API constant)
A default GLG coordinate system used to define the objects' geometry. The extent of the visible part of the viewport is [-1000;+1000] in the world coordinates, and all objects in the viewport are resized when the viewport's size is changed. The world coordinate system's origin is positioned at the center of the viewport, with the X axis pointing to the right, the Y axis pointing up and the Z axis pointing to the viewer. The exact coordinate mapping is affected by the screen's Stretch and PushIn attributes as described below. The SpanX and SpanY attributes of the screen object may be used to change the extent of the visible portion of the viewport for advanced use.

NO (SCREEN) ( GLG_SCREEN_COORD_SYSTEM API constant)
The screen coordinate system is used to define objects. In this coordinate system, coordinates are defined in screen pixels and objects' dimensions are not changed when the viewport is resized. The origin of the screen coordinate system is located at the top left corner of the viewport, with the X axis pointing right, the Y axis pointing down and the Z axis pointing away from the viewer to form a right-hand coordinate system for 3D rendering.

NO (GLG SCREEN) ( GLG_FLIPPED_SCREEN_COORD_SYSTEM API constant)
Same as the NO (SCREEN), but with the Y axis pointing up to preserve the X, Y and Z axis direction matching the default WORLD coordinate system.

NO (SCREEN CENTER) ( GLG_SCREEN_CENTER_COORD_SYSTEM API constant)
Same as NO (GLG SCREEN), but with the origin located in the center of the viewport.

When a new widget is created, the Resizable attribute of the widget's viewport is set automatically depending on the selected Stretch/Resize option used to create a new widget. For example, the GLG SCREEN setting is used for a widget created using the File, New, Widget (No Stretch/Resize) menu option.

Stretch
Controls mapping from view coordinates to window coordinates. If it is set to RESIZE, the original ratio of the viewport's height to width is not preserved and things may look distorted when the viewport is resized. If turned off (set to NO), the ratio is preserved. In this case PushIn attribute controls the rest of the mapping.The RESIZE AND ZOOM setting allows to stretch the viewport on both resizing and zooming. For more details about the mapping from view coordinates to window coordinates, see Coordinate Systems in Structure of a GLG Drawing.

PushIn
Controls which parts of the viewport are visible when Stretch is turned off. If PushIn is set to YES, the screen scaling factor is chosen in such a way that the viewport frame (a rectangle defined by two points with coordinates (-1000,-1000) and (1000,1000) ) is completely visible in the window. Some other parts of the drawing may be visible as well depending on the screen ratio. If PushIn is set to NO, the screen scale factor is chosen as an average of the horizontal and vertical scaling factors defined by mapping the viewport frame to the window's border. Depending on the screen ratio, some parts of the viewport frame may be clipped off.

OpenGLHint
If set to ON , the screen's viewport will use an OpenGL renderer if it is available. Otherwise, a native windowing renderer will be used. This flag is ignored in the Java version of the Toolkit, where the Java2D OpenGL renderer is always used.
Even if the OpenGLHint is set to ON , the OpenGL renderer may be disabled by the -glg-disable-opengl command-line option, setting the GLG_OPENGL_MODE environment variable to False , or setting the GlgOpenGLMode global configuration resource to 0. Refer to OpenGL or Native Windowing System Renderer on page 16 for details.

OpenGL
Read-only attribute for the programming use that provides the current status of the OpenGL renderer. It is set to ON if the OpenGL renderer is successfully initialized and is used for rendering objects in the screen's viewport.

ShellType
If this attribute is set to GLG_DIALOG_SHELL or GLG_APPLICATION_SHELL, the viewport appears in its own window, at the same level in the window hierarchy as the program operating it. The difference between the two is that the GLG_DIALOG_SHELL value always appears on top of other windows. The attribute may also be set to NONE (GLG_NO_TOP_SHELL), in which case, the viewport is simply a child window of a larger drawing.

WidgetType
The widget type may be selected from the list of possible widget types. For more information about widget types, see Native Widgets on page 136.

ShadowWidth
Defines the width of shadows. If the value differs from 0, the shadow bevels are drawn around the borders of the viewport. The sign of the ShadowWidth controls the type of the bevels: raised shadows for positive values and depressed shadows for negative values.

ExactColor
When using widget types besides Drawing Area on X Windows, this boolean attribute instructs the native widget to use the exact value specified by the FillColor attribute rather than take the closest available entry from the color table.

GridValue
Defines the grid spacing, in "world" coordinates. A viewport's corners are mapped to (-1000; -1000) and (1000; 1000) in this coordinate system. If it is zero, the grid is not drawn.

SpanX, SpanY
Define the mapping of the world coordinate system to the visible area of the viewport. The default value of the SpanX and SpanY attributes is 1000, which causes the corners of the visible area of the viewport to correspond to the coordinates (-1000, -1000) and (1000, 1000) in the absence of zooming and panning and with Stretch set to YES. The SpanX and SpanY attributes may used to change the mapping.

FonttableFile
Specifies a GLG drawing file containing a font table to use. This attribute may also be set at run-time to customize fonts used in the drawing. It needs to be set only on top-level viewports, since children viewports inherit the font table from a parent. If a custom font table was defined using the Add Font Table button, it takes priority over the font table defined by the FonttableFile attribute.

If a relative filename is used, it is interpreted relatively to the load path of the drawing first and then relatively to the current directory. For C/C++ and ActiveX deployment options, the GLG_PATH is also searched before the current directory.

The drawing specified with FonttableFile may contain a font table saved using the Save Fonttable button in the font table object Properties. For the convenience of editing in the Builder, the drawing may also contain a $Widget viewport, in which case the viewport's font table will be used.

Add/Edit Font Table
A custom font table that lists the fonts available for use in the viewport. If not defined, the font table defined by the FonttableFile is used. If the FonttableFile is not defined, the font table is inherited from the parent viewport, or the default GLG font table is used if no parent exists.

The Add/Edit Font Table button may be used to add a custom font table to the viewport or edit fonts in the font table if it already exists. To delete the font table, use the Delete Table button in the font table properties. See Font Table on page 88 for details.

When a font table is added to all viewports in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added font tables (the attributes are constrained if the Constrained Clone, the default, setting is used).

Add/Edit Color Table
The color table defines the colors available for use in a viewport. If not defined, the color table is inherited from the parent viewport, or the default GLG color table is used if there is no parent. On TrueColor systems with more than 256 colors (and in Java) the color table is not used for rendering: it is used only to define the number of colors in the Graphics Builder's color palette.

The Add/Edit Color Table button may be used to add a custom color table to the viewport or edit color table parameters if it already exists. To delete the color table, use the Delete Table button in the color table properties. See Colortable on page 86 for details.

When a color table is added to all viewports in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added color tables (the attributes are constrained if the Constrained Clone, the default, setting is used).

Screen Transformation
The screen transformation is used by the screen object to adjust the drawing when the screen size changes. The parameters of the transformation are automatically set by the screen object, but they may be used for constraining purposes to obtain offsets in screen pixels. For example, the top part of the resource browser in the Builder has constraints that make it non-resizable, keeping a constant pixel size when the resource browser window is resized.

To obtain such an effect, a MoveX or MoveY transformation may be used, with the Divide transformation attached to its Factor attribute. The divisor of the Divide transformation is then constrained to the corresponding X or Y Scale of the screen transformation. This annuls the result of the screen size changes, making the move transformation maintain its offset in pixels rather then the world coordinates.

To get access to the parameters of the Screen Transformation , edit the attributes of the viewport object and press the More button to access the screen's attributes, then press Edit Dynamics to edit the screen's transformation.

Group

A group is a container object used to keep a set of simpler objects together. The group object does not have any control points nor any geometry. The geometry of the group is completely defined by the objects it contains. A group may contain any other objects, including other groups.

Though its most common use is to collect graphical objects into composite objects, the group is not really a graphical object. It can be used to collect data objects into lists and arrays. For example, a group is used to keep an array of Custom Data Properties attached to an object. The group object is included in this list because most users will encounter the group in trying to create composite graphical objects.

Groups may be used for creating layers, in which case the group's Visibility attribute may be used to control the visibility of its layer, rendering all objects in the group visible or invisible.

Aside from the name and other standard attributes (like HasResources and Visibility ), the group object has only one attribute. The DepthSort attribute controls hidden surface removal for the child objects in that group. It operates the same as the DepthSort attribute for a viewport object, except that a group may inherit the value of this attribute from its parent object.

The following list describes the values the DepthSort attribute may have:

NO (GLG_NO)
Depth sorting is disabled

YES (GLG_YES)
Depth sorting is enabled. Note that a group is sorted as a whole. This means that if there are two intersecting groups, one group is completely in front of another.

SPECIAL (GLG_SPECIAL)
Crude and fast depth sorting algorithm which uses objects' bounding boxes for determining the relative Z order of the objects.

INHERIT (GLG_INHERIT)
Inherit the value of the DepthSort attribute from the parent object. If the DepthSort attribute of some parent was set to YES and there were no intervening parents with the attribute set to NO, the inherited value of the attribute is YES, otherwise it is NO. The DepthSort attribute is not inherited across viewports, so the parent from which the YES value must be in the same viewport or the viewport itself.

PARTS (GLG_BY_PARENT)
This is the same as YES or SPECIAL, but instead of sorting a group as a whole, elements of the group are sorted by a parent object with the DepthSort attribute set to a value different from NO. If there are two groups with the DepthSort attribute set to PARTS, and the DepthSort of the parent object containing these groups is set to YES or SPECIAL, the elements of these groups may be intermixed when drawn, based on their position in 3D space.

If a group's DepthSort is set to PARTS, the Visibility attribute of the group has no effect on the objects the group contains, since it is the group's parent who is drawing them. If you need to use the group's Visibility attribute to control the visibility of all objects in the group, constrain the Visibility attributes of all objects in the group to the group's Visibility .

In addition to the DepthSort attribute, the group's properties dialog also contains buttons for selecting and editing objects contained in the group, as well as adding and deleting objects from the group. The EditAll button starts editing the attributes of objects in the group by using the first object in the group to select a set of attributes for editing, which is a convenient option for fast editing of groups that contain objects of the same type.

For groups that contain objects of different types, the Edit All (Select) option allows you to select a set of attributes to edit. For example, if the group contains both the polygon and text objects, the Edit All (Select) option allows you to select the polygon or text attributes to be edited.

The rest of the buttons perform the same functions as the corresponding options of the Arrange menu, described on page 214.

Series

The series object is used to produce multiple copies of the object defined as its template .

A series object has a variable number of control points. One point controls the location of the first instance's origin, while the others control the location of the line along which the series instances are distributed. For a straight-line series, there will thus be three control points: two to define the line, and one at the first object's origin. Note that when a series is created in the editor, the object's origin point is constrained to one end of the series path.

There is another control point which is only visible while looking at the series template. This point controls the mapping of the template object onto the series constraint path. By default, this point is at the origin of the template object's coordinate system, so that the origin is mapped onto the path. It can be moved to another location to change mapping.

The series object has the following attributes:

DepthSort
Controls hidden surface removal. This is the same as the DepthSort attribute for a group, except that the SPECIAL value uses a fast depth sorting algorithm optimized for Series objects.

Factor
Defines a number of template copies to be created. Note that, strictly speaking, the Factor attribute of a series object defines not the number of copies produced, but the number of series object intervals. The actual number of copies may differ by one from the value of the Factor attribute. For example, for a vertical axis of a graph, the number of major ticks is greater than the factor by one, since an additional tick is placed at the end of the axis.
Every time the Factor attribute is changed, the old instances of the template are destroyed and the new number of instances is created. Any resource values set in the old instances are destroyed.

LogType
Defines how the template copies are positioned. If this attribute is set to NO, the copies are positioned linearly. If it is set to YES, they are positioned logarithmically. The base of the logarithm is equal to the value of the Factor attribute minus one.

Inversed
Controls how the instances are named. If the value is DIRECT, instance 0 is at the start of the series path. If the value is INVERSED, instance 0 is at the end.

CloneType
The clone type used to create instances of the template. It may be Full, Weak, Strong or Constrained . Refer to Cloning an Object of the Using the GLG Graphics Builder for details on using the clone type.

PathXform
PathXform defines the shape of the path used by the series. The type of the PathXform transformation (Move, Rotate, etc.) is defined when the series object is created. The path transformation's parameters may be edited at any time.

Though it has no default name, the series template is also an attribute of a series. This is the object to be replicated in the series and can be accessed for editing by traversing the hierarchy of the series object ( Traverse, Down or the Hierarchy Down button ). When finished, use Hierarchy Up to return back to the top level.

Instances of the template are created by the series after the drawing hierarchy has been setup. To differentiate the instances, a zero-based index is added as a suffix to the name of a template to construct the name of an individual copy. For example, if the name of a template is Label , the produced copies of it have names Label0 , Label1 , Label2 , and so on. Each of these names appears in the resource hierarchy, as does the name of the original, providing access to both the template and its instances. The instances may be accessed only after they've been created (after the drawing hierarchy has been setup).

The Global flag of the template's attributes may be used to constrain attributes of its instances. If an attribute's Global flag is set to GLOBAL in the template, changing this attribute will change all instances. If the flag is set to LOCAL, the attribute of each instance may be set independently, enabling independent dynamics. The constraining behavior of the series is also controlled by its CloneType attribute.

When the series object is used in GLG widgets, it may scale instances of the template. For example, if you increase the number of bars in a GLG bar graph widget, the bars become narrower so they will fit on the X axis. Series with this feature cannot be created in the GLG Graphics Builder (you can still use the square series, which scale their instances, to obtain a similar effect). However, you can use the Builder to edit graphs that use it. For a series with this feature enabled, a rectangle defined by points with coordinates (-1000,-1000) and (1000,1000) in the template object coordinate system is mapped to the size of one bar slot.

Square Series

The square series object is a special case of a series object used to position copies of a template object on a two-dimensional grid.

Like a parallelogram, the square series object has three control points that define a corner and two sides. These three points define a parallelogram. The first defined point is the center. Rows of the square series are parallel to the line through the center and the second defined point, and columns are parallel to the line through the center and the third defined point.

Created copies are scaled to fit the area outlined by the parallelogram. The viewport frame of the template is mapped to the size of one slot of the square series.

The square series object has the following attributes:

DepthSort
Controls hidden surface removal. Similar to the DepthSort attribute of a group, but the SPECIAL value uses a fast depth sorting algorithm optimized for series objects.

RowFactor
Defines a number of rows of template instances.

ColumnFactor
Defines a number of columns of template instances.

ColumnsFirst
Controls how instances of the template are numbered. If set to YES, they are numbered by the columns, or by the rows otherwise.

CloneType
The clone type used to create instances of the template. It may be Full, Weak, Strong or Constrained . Refer to Cloning an Object of the Using the GLG Graphics Builder for details on using the clone type.

Like a one-dimensional series, a square series has a template object that is replicated to form the series. Though it has no default name, the template is an attribute of the square series and can be accessed by traversing the hierarchy of the series object ( Traverse , Down or the Hierarchy Down button ). When finished, use Hierarchy Up to return back to the top level. As with the series, created instances of the template are differentiated by the zero-based index added to the name of the template. Instances are numbered using one sequential index, to refrain from using two separate row and column indexes.

The Global flag of the template's attributes may be used to constrain attributes of its instances. If an attribute's Global flag is set to GLOBAL in the template, changing this attribute will change all instances. If the flag is set to LOCAL, the attribute of each instance may be set independently, enabling independent dynamics. The constraining behavior of the square series is also controlled by its CloneType attribute.

Reference

The reference object may be thought of as a one-element series. There are two types of references that are used to implement two completely different types of functionality:

A container reference is used to hold a unique template object and preserve its coordinate system when the container is moved. If the container is copied, the contained template object is copied as well, so that each copied container has its own, independent template. A container draws its template directly, without creating any additional instances of it. It may be used to implement node/edge functionalities or preserve center of rotational dynamics when objects are moved. If a container is used as a node, it's template's control points are protected and a single control point is provided, which may be conveniently used for positioning or attaching connectors to.

A referenced reference object is used to replicate a template in different locations in the drawing. Its most important feature is that a copy of a reference refers back to the same template used by the original reference. This is useful when constructing drawings that contain many copies of a single object used as a sub-drawing or a model. By using the reference, you can make a drawing file smaller than it might be otherwise, since only one copy of the template is saved. The drawback of using references is that the resource settings for instances of the template can not be saved in the drawing and must be done programmatically at run time. This limitation can be avoided by using attribute binding described later in this section.

A template can be edited in one place to change all of its copies in the drawing. The template used by a particular instance can be changed dynamically to implement subdrawing dynamics. A reference object also provides an even more powerful mechanism for displaying different objects from the template - object dynamics, where the template is used as a palette of objects.

References provide three ways of using the template: referencing an object, referencing a drawing file, or referencing a palette object in the drawing. Like a container, the referenced reference may be used as a node.

To edit the template of a reference, use Traverse , Hierarchy Down (or ). For file references, traversing down loads the template file. For palette references, traversing down traverses down the palette object. When finished, use Traverse , Up to return back to the top level.

The reference object contains two objects:

Template
The original template object. It is analogous to the template of a series. For file and palette references, this resource is NULL until the drawing hierarchy is setup, after which it contains the template object loaded from a file or palette.

Instance
For a referenced reference, a copy of the template or of its subobject as defined by the ObjectPath . This copy is created dynamically after the drawing hierarchy is setup. Like a series, a user may edit its resources. However, when the drawing is reloaded or reset, the copy's attributes are recreated from the template again, erasing any changes a user might have made (except for rebound attributes as described in the Bindings section). The instance object is also visible in the Resource Browser as a resource using its name.

For a container reference, the template is displayed without any copying and both Instance and Template resources refer to the same object.

The reference object also has the following attributes:

ReferenceType
The subtype of reference object: GLG_CONTAINER_REF or GLG_REFERENCE_REF. This is a read-only attribute that is set at the time of creation.

Source
The source of the template object for the GLG_REFERENCE_REF reference. Possible values are GLG_USE_TEMPLATE, GLG_USE_FILE and GLG_USE_PALETTE. This attribute is usually set at the time of creation using the Reference or SubDrawing icons from the Object Palette . However, if the object is created using SubDrawing , the value of it's Source may be changed from GLG_USE_FILE to GLG_USE_TEMPLATE to permanently store the loaded template in the reference, without a need for a separate file. The Source attributes of several references may be constrained, enabling changing the template storage type of all references involved from the dynamic referencing of a file to including a static template object and back by setting just one Source resource. When Source is set to GLG_USE_FILE, the SourcePath attribute defines a name of the template drawing's file.

GLG_USE_PALETTE is a special setting of the Source attribute that allows embedding a palette of objects in the drawing for easy editing. When Source is set to GLG_USE_PALETTE, the SourcePath attribute defines the palette's resource path in the drawing. When the palette is used as a template, the template icons are visible when the drawing is loaded, which makes it easier to locate and edit them later.

SourcePath
For subdrawings ( Source=Template ), the attribute defines the location of the drawing file containing the template object. When the file is loaded, the object named $Drawing or $Widget is used as the template object. If neither named object is found, the whole drawing is used as a template.

If the SourcePath attribute defines a relative file name, the system tries to resolve it in the following order:
- attempting to load the file relative to the directory of the drawing
- trying to locate the file in one of the directories defined by the GLG_PATH
environment variable or the GlgSearchPath configuration parameter.
- attempting to load the file relative to the current directory

A List transformation may be attached to the SourcePath attribute to specify a list of drawing files for implementing subdrawing dynamics, changing the displayed drawing when the list's index changes. See the ObjectPath attribute below for more efficient object dynamics.

For palette references ( Source=Palette ), the attribute defines the resource path for accessing the palette inside the drawing. The palette may be a simple single object, or a collection of objects in either a group or inside of a viewport. If the SourcePath is not set, the default $Palette resource name is used. If an application loads the drawing using a LoadWidget method, the resource path must be relative to the $Widget viewport.

ObjectPath
A resource path of an object within the template to be displayed in the reference. The template may have several named objects, and changing the path to a different object name will display a different object. The path is relative to the template.

For file references, the template is loaded from a subdrawing file; if the file contains an object named " $Drawing " or " $Widget ", ObjectPath is relative to that object, otherwise it is relative to the whole template drawing.

This new attribute allows implementing subdrawing dynamics using just one template containing several objects, instead of placing each object into a different subdrawing and loading a new template every time the subdrawing changes. In other words, the subdrawing dynamics may now be replaced with more efficient object dynamics. It also enables implementing object dynamics without a separate subdrawing file by embedding the template into the drawing and attaching a list transformation to the ObjectPath attribute, changing the path to display a different object when list's index changes. Previously, such
dynamics could only be implemented via changing the DrawingFile attribute to load a different template drawing. The list of ObjectPath's values may include anchor paths described below.

The ObjectPath attribute may also contain a colon following a resource path to a control point to be used as an anchor when displaying the object. The anchor path may point to a named control point of an object, or to a control point of a marker outside of the object used to control object's position. For example, a template may contain a polygon object named Triangle with HasResources=YES and one of it's control points named Anchor . The Triangle:Triangle/Anchor setting of ObjectPath will display the polygon anchored at the Anchor point. The template may also contain an arc object named Arc and a marker object named ArcAnchor used to control the arc's display position. The Arc:ArcAnchor/Point setting may be used to display the arc anchored at the position of the ArcAnchor marker (the default Point attribute name is used to reference marker's point). The anchor values may be accessed via the CoordOrigin resource of the reference object. An object's anchoring is also affected by the value of the reference's Origin attribute described below.

If ObjectPath is not set (or if the portion of the string before the colon separator is empty), the whole template object will be displayed.

CloneType
The clone type used to create an instance of the original object. It may be Full, Weak, Strong or Constrained . Refer to Cloning an Object of the Using the GLG Graphics Builder for details on using the clone type. The default value is STRONG clone, which constrains attributes with GLOBAL and SEMI_GLOBAL settings of the Global flag.

FixedSize
Determines if a reference or container object can be resized. If set to YES, the object does not resize when the drawing is resized or zoomed in, otherwise it is resized with the drawing. The size of a reference or container object of a fixed size may be changed only by editing its template.

If the FixedSize is set to YES, the point coordinates of the object's template are interpreted as GLG screen coordinates. If the FixedSize is set to NO, the point coordinates of the object's template are interpreted as world coordinates of the drawing. Reference and container objects are created with the FixedSize initially set to NO, and the template's coordinates are interpreted in the world coordinate space. When the FixedSize is changed to YES, the visible size of the object changes since the template is now drawn in the screen coordinate space. The size of the fixed size reference object may be adjusted by traversing down into the object's template using the Hierarchy Down button and changing the template's size.

Bindings
A slot for attaching an optional array of rebound attributes (bindings). If any named attribute of the reference's template has its Global flag set to BOUND, a bindings array will be created and populated with copies of the bound attributes. The copies of the attributes in the array may be edited using the Edit Bindings button to change their values, transformations, names or tag names, or even constrain them to other objects in the drawing. The bindings are saved with the reference object. When a reference object with bindings is loaded and an instance of the template is created during the setup phase, template attributes with the Global flag set to BOUND are "rebound" - replaced with the corresponding local copy from the bindings array.

This allows reference and subdrawing instances to define local, different from the template, values for some of the attributes, modify behavior of the local template instance by attaching transformations to its rebound attributes, modify instance's resource hierarchy by renaming rebound attributes and assign different tag names to multiple copies of the reference object by specifying different tag names for the rebound attributes. If a name or tag name of a rebound attribute is changed, only the new resource name and tag name will be visible in the reference's instance, while the old resource name and tag will still be visible in its template.

The rebinding feature also allows to constrain rebound attributes to objects in the drawing, enabling different instances of the reference object to share the same template but have selected attributes constrained to different objects in the drawing.

To reset bindings, press the Reset Bindings button. This discards the old bindings and recreates the bindings array with the initial values copied from the template, so they may edited from scratch.

Origin
The geometrical attribute that controls anchoring of the reference object's template. With no anchoring defined in the ObjectPath , the template will be anchored at a position defined by the Origin . If an additional anchoring is defined in the ObjectPath , the template is further offset by the distance from the center of the template's coordinate system to the anchor defined by in the ObjectPath . Another way of looking at it is that the origin's anchoring offset is applied to all objects in the template on top of the individual object's anchoring defined in the ObjectPath .

The Origin attribute is not shown in reference object's properties - instead, its position is displayed as a round marker when the reference's template is edited using the Hierarchy Down button (the marker may be hidden behind the template). The value of the attribute is set when the reference is created to position the reference at the selected anchor point. The value may be reset to (0,0,0) by using resources or editing the template, or adjusted interactively by dragging reference's anchoring point using Ctrl-Shift-Left-Mouse-Move .

The special feature of referenced reference objects is that any number of copies of the object may be made, with all Reference attributes pointing to the original object data. This means that any number of reference objects can use the same template object. Thus, the reference becomes useful in any drawing where there are a large number of identical (or nearly identical) objects. Editing the original object will change all instances of it in the drawing. If the reference object is a subdrawing ( Source =GLG_USE_FILE), all instances of it may be changed by editing its template file. Rebinding may be used to modify the local copy of the template as described in the Rebindings section above.

The Global flag of a template's attributes may be used to constrain attributes of instances of the reference. If an attribute's Global flag is set to GLOBAL in the template, changing this attribute will change all instances in the drawing. If the flag is set to LOCAL, the attribute of each instance may be set independently, allowing for independent dynamics. The constraining behavior of the reference is also controlled by its CloneType attribute. If the Global flag is set to BOUND, the attribute is rebound and its value is taken from the rebinding table, as described above. Rebound attributes must be named.

When a container reference is copied, each copy will have its own independent copy of the template.

If reference objects are used to represent connected nodes, the reference's control point may be used for constraining connecting lines that represent edges.

Polyline

The polyline object is a special type of series that produces an open polygon with specified number of points or a specified number of line segments. It is often used for animated line graphs like the ones in the GLG widget set.

A polyline has a variable number of control points defining its location. It also has the following attributes:

Factor
Defines number of polyline control points to be created.

DrawMarkers
Controls the presence of polyline's markers. Markers are created if the attribute is set to YES.

DrawLines
Controls the presence of the lines between a polyline's points. These lines are drawn between each marker if the attribute is set to YES.

Segments
Enables the segments mode. If the value set to YES, separate polygon objects are used to render each segment of a polyline, allowing to use different colors and line attributes for each segment. In this case the Polygon attribute is used as a template for producing the segment instances. If the value is set to NO, one polygon is used, providing faster and more efficient rendering.

Marker
A template marker object. Copies of this marker appear on each control point if the DrawMarkers attribute is turned on. To access the marker template, traverse the hierarchy of the polyline (the Hierarchy Down button ). When finished, use Traverse , Up to return back to the top level.

Polygon
A template polygon object. The lines connecting polyline points inherit their graphical properties from this template. Therefore, you can modify the attributes of this polygon to change the line color and width. If Segments is set to YES, the polygon is used as a template for creating the segments. If Segments is set to NO, the polygon itself is used to render the polyline.

CloneType
The clone type used to create an instance of the polygon and marker templates. It may be Full, Weak, Strong or Constrained . Refer to Cloning an Object of the Using the GLG Graphics Builder for details on using the clone type.

In a manner similar to the series object, instances of markers and polyline segments are differentiated by the zero-based index added to the name of the corresponding template object. For example, for a three-point polyline, the resource hierarchy might include the template objects Mark and Poly , and the series instances Mark0 , Mark1 , and Mark2 , and Poly0 and Poly1 .

If markers are named, the polyline contains a group named Markers which in turn contains the instances of the marker template. If the template marker's conrol points are named, the polyline also contains a group called Points , containing the instances of the control points. If the template polygon is named, there is a group called Polygons , containing those instances, too.

The Global flag of a marker template's attributes may be used to constrain attributes of the marker's instances. If an attribute's Global flag is set to GLOBAL in the template, changing this attribute will change all instances. If the flag is set to LOCAL, the attribute of each instance may be set independently, allowing for independent dynamics. When the Segments mode is enabled, the GLOBAL flag of the polygon template's attributes may be used to constrain attributes of the segment polygons in the same way. The constraining behavior of the polyline is also controlled by its CloneType attribute.

Polysurface

The polysurface object is a special type of series object used to create a surface made of a number of surface patches. The number of patches is determined by the row and column factors of the polysurface. A patch is a polygon connecting four neighboring points of a surface. The polysurface is used in several three-dimensional graphs in the GLG Widget Set.

In addition to the three control points defining the boundary parallelogram, the polysurface also has the following attributes:

DepthSort
Controls hidden surface removal. Similar to the DepthSort attribute of a group, but the SPECIAL value uses a fast depth sorting algorithm optimized for polysurface objects.

RowFactor and ColumnFactor
Define a number of polygon patches used to form the surface.

DrawMarkers
Controls the presence of markers at the vertices of the polysurface. Markers are drawn only if the attribute is set to YES. Markers always appear on top of the surface patches.

Polygon
A template defining attributes of the polygon patches.

Marker
A template marker object defining attributes of the markers.To access the marker template, traverse the hierarchy of the polysurface (the Hierarchy Down button ). When finished, use Traverse , Up to return back to the top level.

CloneType
The clone type used to create an instance of the polygon and marker templates. It may be Full, Weak, Strong or Constrained . Refer to Cloning an Object of the Using the GLG Graphics Builder for details on using the clone type.

The naming of instances of template markers and polygon patches is analogous to the naming of the comparable objects for a polyline. See page 76.

The Global flag of a marker template's attributes may be used to constrain attributes of the marker's instances. If an attribute's Global flag is set to GLOBAL in the template, changing this attribute will change all instances. If the flag is set to LOCAL, the attribute of each instance may be set independently, allowing for independent dynamics. The GLOBAL flag of the polygon template's attributes may be used to constrain attributes of the polygon patches in the same way. The constraining behavior of the polysurface is also controlled by its CloneType attribute.

Connector

The connector object may be used to connect other objects in the drawing. It is useful when implementing node and edge functionalities or connecting objects in a diagram.

There are two types of connectors. A recta-linear connector connects objects with linear segments, maintaining right angles between adjacent segments, and an arc connector connects objects with an arc path.

The connector has a set of control points which define its geometry. When the positions of its control points change, the connecting path changes as well, maintaining its recta-linear or arc shape. The end points of the connector can be constrained to the control points of other objects, so that the connector adjusts its geometry when the objects move. A Reference and Container objects may be used as containers to hold objects, providing a control point for constraining the connector's end points to. A Diagram Editor demo shows examples of using different connector objects to connect nodes in a diagram.

The recta-linear connector also has a set of constrained points . These points can't be moved, since their position is defined by the connector's control points, but they may be used to constrain other objects to them, staying attached to the middle point of the connecting path. When the connector is selected, either its control or constrained points are highlighted depending on the state of the Toggle Frame Points toolbar icon, which may be used to access the constrained points.

A connector object inherits polygon attributes (EdgeColor, LineWidth and LineType) but also has the following attributes:

EdgeType
A read-only attribute defining the object type of the graphical object used to render the connector. It is set to GLG_POLYGON (for recta-linear connectors) or GLG_ARC.

Direction
Defines the orientation of the first segment of a recta-linear connector, GLG_VERTICAL or GLG_HORIZONTAL.

PointList
A list of a connector's control points (recta-linear connectors only). Allows changing the order of points in the connector as well as adding and deleting them.

Frame

The frame object is used to constrain the geometry of other objects. A frame has a number of control points defining its own geometry and position, and an array of constrained points (frame points) used for constraining the geometry of other objects. When the frame is selected, either its control or frame points are highlighted depending on the state of the Toggle Frame Points toolbar icon.

Frame constrained points can not be edited independently, since their position is determined by the frame's control points. The control points may be moved to change the position of the frame points, but the frame points themselves cannot be moved directly. Anything constrained to the frame points moves with the frame. To access the constrained points, use the Toggle Frame Points toolbar icon.

There are several types of frames:

1D Frame
has frame points positioned along the line defined by two control points.

2D Frame
has frame points positioned inside the parallelogram defined by three control points.

3D Frame
has frame points positioned inside the parallel prism defined by four control points.

Free Frame
is simply a collection of arbitrarily positioned frame points. A point frame is the special case of a free frame with one point.

Except for the free frame, the number of frame points is indirectly defined by the frame's factor. The factor defines a number of intervals between the frame's frame points along every frame's axis.

A frame object has the following read-only attributes:

FrameType
Defines the number of frame's dimensions and can be 1D, 2D, 3D, or FREE

FrameFactor
Defines the number of intervals between frame points along each frame's axis. The number of frame points is one more than the number of intervals.

Data

The data object is used to specify a data value. Most attributes of GLG objects use data objects to keep an attribute's value.The data objects are also used to attach Custom Data Properties to other objects.

The data object has the following attributes: the data type, the value, the transformed value and an optional tag. Of course, it also has a name, the Global and HasResources flags, and may have transformations attached to it.

A tag may be attached to the data object to mark it as a global resource to define database connectivity for the data value. Refer to Tag-Based Data Access and Database Connectivity on page 110 for details of using tag objects for data access.

If a transformation is attached to a data object, it will transform it causing the transformed value to differ from the original data value. Data objects are not affected by drawing and other transformations attached to their parents.

The attributes of the data object are as follows:

Type
Specifies the type of data stored. Possible data types are G, D, or S, for "geometrical", "double-precision," and "string", respectively. A G value contains three double-precision values. It usually represents a point in a Euclidean space, but it can be used for any data stored in triples (RGB color values, for example). A D value is a single number (also called a "scalar"), rendered in double-precision, and an S value is simply a standard character string.

Value
Where the actual data value is stored. Note that this name is not accessible through the resource mechanism. It is returned by accessing the name of the data object itself, or by using NULL as a name in the case of the object ID of the data object being used as the first parameter of the GlgGetResourceObject function.

XfValue
The data value as it was transformed by the transformation attached to the data object. If no transformations are attached to the object, the transformed value is the same as Value. The transformed value is valid only after the drawing hierarchy has been setup. For G data representing points, the transformed value is in world coordinates.

TagObject
An optional tag object that may be attached to the data object to mark it as a global resource or to define database connectivity for its data value. If a tag object is present, the data object inherits all tag attributes, such as TagName, TagSource and TagComment.

Note, that unlike most GLG objects attributes, the Value of the data object is not stored as an object. This avoids the infinite regression that might exist if an object's attribute was represented as a data object, whose data value was represented as another data object, whose data value was represented by still another data object, and so on. The same is true for the Name and the flags ( Global , HasResources , etc.).

Data objects may be used programmatically for attaching custom properties to other objects.When custom properties are attached to objects in the GLG Builder ( Add Custom Property button of the Object Menu), the data objects are used to keep the properties' values.

Attribute

The attribute object is a subclass of the data object used to specify an attribute value. The attribute objects are used to keep values of attributes, control points and values of list transformations. Polygons store their control points as an array of attribute objects.

The attribute object differs from the data object by its transformational behavior. Unlike the data object, it is transformed not only by the transformation attached to the attribute itself, but also by any related transformations attached to its parents. For example, consider a polygon's point with transformations attached to both the point and the polygon. The point is an attribute object and is transformed by both transformations, as well as by the drawing transformation of the viewport in which the polygon is contained.

The attributes of the attribute object are similar to the attributes of the data object:

Type
Specifies the type of data stored. Possible data types are G, D, or S, for "geometrical", "double-precision," and "string", respectively. A G value contains three double-precision values. It usually represents a point in a Euclidean space, but it can be used for any data stored in triples (RGB color values, for example). A D value is a single number (also called a "scalar"), rendered in double-precision, and an S value is simply a standard character string.

Role
Determines the type of transformations that will affect the object. This is a creation-time attribute whose possible values include GLG_GEOM_XR (geometrical) and GLG_COLOR_XR (color). The GLG_GDATA_XR, GLG_DDATA_XR and GLG_SDATA_XR values may be used with G, D and S attributes, respectively, for attributes other then points and colors.

Value
Where the actual data value is stored. Note that this name is not accessible through the resource mechanism. It is returned by accessing the name of the data object itself, or by using NULL as a name in the case of the object ID of the data object being used as the first parameter of the GlgGetResourceObject function.

XfValue
The attribute value as it was transformed by the transformations attached to the attribute. The transformed value is valid only after the drawing hierarchy has been setup. If no transformations are attached to the object, the transformed value is the same as Value (except for G attributes representing points). For G attributes representing points, the transformed value represents the screen coordinates of the point and includes the effect of the all transformations attached to the graphical object containing the point and all its parents, as well as drawing transformation of the viewport.

TagObject
An optional tag object that may be attached to the attribute object to mark it as a global resource or to define database connectivity for its data value. If a tag is attached, the attribute object inherits all tags attributes, such as TagName, TagSource and TagComment.

Data
The base data object used for storing the attribute's value.

Tag

The tag object may be attached to any attribute of an object to mark it as a global resource or specify the database field to use for updating the value of the attribute.

The tag object has three attributes:

TagName
A string used to identify the tag during browsing. Having a separate TagName attribute provides a persistent tag identification regardless of the changing TagSource attribute.

TagSource
Defines the database field to use as a datasource for the data object the tag is attached to. A typical application queries a list of TagSources defined in the drawing on application startup and uses it to subscribe for data updates from a process database. When data changes, the application sets the new data values by invoking the GlgSetTag method, passing the TagSource and the new data value for each tag as shown in the source code of the Tag Example.

TagComment
A string used to hold user-defined information related to the tag.

The Tag Object dialog in the Builder also shows the InLow and InHigh attributes. These attributes do not belong to the tag object itself, but to the attribute object the tag is attached to. If the tag is attached to a D attribute with a range transformation, the InLow and InHigh fields allow the user to edit the input range of the range transformation right in the tag editing dialog. These fields are disabled otherwise.

Refer to Tag-Based Data Access and Database Connectivity on page 110 for details of using tag objects for data access.

History

The history object is used to control the scrolling behavior of numbered resources. This is most useful for controlling series behavior in graphs, but is general enough to be useful in a variety of situations.

The history object uses an input resource name mask, a scroll type and an entry point . The scroll type determines the precise behavior of the object. Using the WRAPPED scroll type, each time the entry point attribute is changed, its value is written to the next resource that matches the input mask. The mask uses a percent symbol (%) as a wildcard character. Suppose the input mask is GraphBar%/Height . The first time the entry point is changed, the change is written to the resource GraphBar0/Height . The second time, the change is written to GraphBar1/Height , and the third time to GraphBar2/Height . This continues until there are no more matches for the mask, at which point it starts over again with GraphBar0/Height .

Setting the scroll type to SCROLLED creates similar behavior, but all changes are initially made to the first object in the series. However, each time the first object is changed, the second object takes the old value of the first, and the third takes the old value of the second and so on. The last data value in the series is discarded.

A history may be attached to an object in the Builder by using the Add History button in the Object Menu. The history object has four attributes:

ScrollType
Controls how changes are made to the resources that match the input mask. Using the WRAPPED type, changes in the entry point are made to each of the objects in the series in turn. Using the SCROLLED type, changes are only made to the first object in the series, but with each change in the entry point, the second object takes the old value of the first object, the third takes the old value of the second, and so on. The value of the last object in the series is discarded.

VarName
The input resource name mask. Use a percent symbol (%) for the variable position. For example, GraphBar%/Height will become GraphBar0/Height and GraphBar1/Height and so on in turn. All resource names are relative to the position of the history object itself. That is, if a history is attached to a series object, the resource name mask need not contain the name of the series itself. This attribute is not an object but a string ( char* ). If there is no percent symbol in the VarName string, it is added to the end.

EntryPoint
This is the entry point for the object. Each time this attribute is changed, its changes are propagated to the list of resources that match the VarName attribute.

Inversed
Determines whether the history object works in the order defined by the resource names (DIRECT) or in reverse order (INVERSED).

RollBack
Defines the number of iterations to "roll back" when the history gets completely filled with data. This attribute is used in conjunction with the WRAPPED scrolling type for implementing scrolling behavior which scrolls the graph only once every n iterations, as defined by the value of the attribute.

When the RollBack attribute is used in a graph, the RollBack attributes of the DataGroup object and the XLabelGroup object must be set to proper values to ensure their synchronous scrolling. For example, consider a graph with the WRAPPED scroll type, 200 datasamples, 10 X axis major ticks with labels, and 20 minor ticks per one major tick interval. Setting DataGroup/Rollback=40 and XLabelGroup/RollBack=2 will "roll" the graph back by 2 major tick and label intervals (which corresponds to 40 datasamples) when the graph gets completely filled with data.

The use of the RollBack limits the CPU-intensive scrolling operation to be performed only once on every 40th data update, compared with every data update in the regular scrolling graph with the SCROLLED scrolling type.

A special case of the rollback may be used to implement the graph which switches from the WRAPPED behavior to the SCROLLED behavior when the graph gets completely filled with data the first time. For example, for a graph with the WRAPPED scroll type, 200 datasamples, 10 X axis major ticks and labels, and 20 minor ticks per one major tick interval, the following settings may be used: DataGroup/Rollback=1 and XLabelGroup/Rollback=0.05 ( which corresponds to one minor tick - 1/20).

Alias

An alias object may be used to define logical names for arbitrary resource hierarchies. For example, it may define a logical "ValueHighlight" name for accessing the "Group1/Object3/FillColor" resource hierarchy. The application can then access the resource using the alias instead of a complete path name. The alias can also be used to create convenient shortcuts for long resource paths.

Aliases may be added in the Builder using the Add Alias button in the Object Menu. The alias object has the following resources:

Alias
Specifies a logical name to be assigned to the resource hierarchy pointed to by the alias.

ResPath
Resource path to the aliased resource.

Rendering

The rendering object is used to keep an extended set of optional rendering attributes. The rendering object is attached to the object, or accessed if it already exists, using the Add/Edit Rendering button in the Object Properties dialog. It has the following attributes:

GradientType
The type of the gradient fill, which determines both the gradient geometry as well as the colors used for rendering. The following types of the gradient geometry are supported:

LINEAR - a fill gradient with color changing along a line

SPHERICAL - a fill gradient in the form of a sphere

ELLIPTICAL - same as the SPHERICAL, but stretches with the object

CONICAL - a fill gradient in the form of a cone

LINE WIDTH - a line gradient for rendering 3D lines. The color gradient changes in the direction perpendicular to the direction of the line. Only the Gradient Color and Gradient Length

The gradient color usage can be DIRECT (the color changing from object color to gradient color) or INVERSED (from gradient color to object color). The LINEAR gradient can also be ACYCLIC (the color changing from the first color to the second color) or CYCLIC (from the first color to the second color and back to the first one). If the value of the gradient type is NONE, the gradient is disabled.

GradientColor
The second color for the gradient fill. For polygons and polygon subclasses, the gradient fill renders the object with a color smoothly changing from the object's FillColor to the gradient color, according to the gradient type. For text objects, the color changes from the text's TextColor to GradientGolor. For polygons with no LINE FILL and the LINE WIDTH gradient, the color changes from EdgeColor to GradientColor.

GradientAngle
The gradient angle for linear gradient, the start angle for conical gradient. The angle is measured counter-clock wise relative to the X axis. For example, an angle of 0 with the linear gradient type results in a horizontal left-to-right gradient fill.

GradientLength
The relative length of the gradient in the range of 0 to 1, controlling the percentage of the object to be rendered with a gradient fill (the rest of the object will be rendered with a solid color). For example, a value of 1 results in the whole object being rendered with a gradient fill, with the gradient starting on one side of the object and ending on the other. If the value is equal to 0.5, half of the object will be rendered with a gradient fill, and the other half will be filled with a solid color. If the Gradient Length is larger than 1, the gradient fill will extend beyond the boundaries of the object and will be clipped.

GradientCenter
This G type attribute defines the center of the gradient fill in relative coordinates, so that the [0;1] range of each of its coordinates corresponds to the object's boundaries in the specified direction, with the direction of each coordinate coinciding with the corresponding axis. The Z coordinate of the center is ignored. For example, a value of (0.5, 0.5, 0.5) centers the gradient inside the object. A value of (0, 0, 0) positions the gradient's center in the lower left corner of the object. Values outside of the [0;1] range will position the center of the gradient outside of the object and result in the gradient being partially clipped. The attribute is ignored for the LINE WIDTH gradient.

GradientResolution
The number of segments used to render the gradient fill. Increasing this number will increase the rendering quality for the price of slower performance. For environments with OpenGL support (OpenGL and Java versions of the Toolkit), linear and acyclic linear gradients are rendered natively using OpenGL and gradient resolution is ignored. The attribute is also ignored for the LINE WIDTH gradient.

On systems with a limited number of colors, the rendering quality is also limited by the number of colors available in the color table, and increasing the gradient resolution above a certain value will not further improve the rendering quality.

ShadowOffset
The cast shadow offset in pixels. The X and Y coordinates of the offset value define the shadow pixel offset in the corresponding direction. Negative values may be used to inverse the offset's direction. If the value is (0,0), no shadow is rendered.

The Z component of the offset value is interpreted as the shadow transparency. If the Z value is between 0 and 1, the shadow is rendered as transparent, with a greater transparency for the Z values closer to 0.

For environments with the OpenGL support (the OpenGL and Java versions of the Toolkit), the transparency is rendered as true alpha-blending. For non-OpenGL versions of the Toolkit, the transparency is supported only in the Unix environment, where it is simulated using dithering patterns.
Transparency is not supported in the Postscript output.

ShadowColor
The color of the cast shadow.

FillDirection
The angle defining the direction of the fill dynamics. The angle is measured counter-clock wise, relative to the X axis. For example, a value of 0 results in a horizontal fill from left to right. In the builder, the angle value may be entered in the Attribute Object dialog (ellipsis button ), or one of the predefined values (UP, DOWN, LEFT, RIGHT) may be selected from the option menu.

FillAmount
The relative value in the range of 0 to 1 defining the percentage of the object filled with the object's FillColor (or TextColor for text objects). The FillDirection attribute defines the fill direction. If the value is 1, the whole object is drawn. If the value is less then 1, only a portion of the object's fill will be drawn, as defined by the fill amount. The object's fill type must have FILL enabled in order to be rendered. The object's edge is not affected by the value of the Fill Amount. For text objects, only the text is clipped; the text box is not affected.

ArrowType
The type of arrow(s) attached to a polygon or any of its subclasses (spline, arc or connector). The arrow type is a composite attribute that determines both the arrows' type (EDGE, FILL or FILL & EDGE) and position (START, END, START AND END or MIDDLE). For arrows positioned in the middle of the polygon, the arrow type also determines an arrow's direction: DIRECT (from start to end point) or INVERSED (pointing from end to start). If the value is NONE, no arrows are rendered. The difference between FILL and FILL & EDGE arrow types becomes visible for lines with line width greater than 1. The geometry of the arrowheads is controlled by the ArrowShape attribute and is adjusted to match the line width for thick lines.

The value of the attribute contains bytes: the low order byte defines the arrow position and the high order byte defines the arrow fill type, which may have the same values as the polygon fill type.

ArrowShape
The shape of the arrow in pixels. The X and Y coordinates of the arrow shape value are used. The X coordinate defines the length of the arrow along the line, the Y coordinate defines the width of the arrow's one side in the direction perpendicular to the line. If null value is specified (0,0,0), the value of the GlgArrowShape global configuration parameter is used (see Appendices on page 281 of GLG Programming Reference Manual).

Delete Rendering
This button is present only in the Builder; it deletes the rendering object.

When a rendering object is added to all objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added rendering objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

BoxAttributes

The Box Attributes object is used to keep attributes of an optional box drawn around text object. The box is drawn only if the Box Attributes object is attached to a text object. The size of the box is determined by the text object and is expanded automatically to fit the text's string. The box attributes object inherits most polygon attributes like FillColor, EdgeColor, and FillType, and has the following additional attributes:

BoxOffset
Pixel offset between the text and the box's edge. Only the X and Y coordinates of the G-type offset value are used, defining the pixel offset in the corresponding direction.

BoxEdgeColor
Box's edge color: a more specific name for accessing box's edge color.

BoxFillColor
Box's fill color: a more specific name for accessing box's fill color.

Delete Box Attributes
This button is present only in the Builder; it deletes the Box Attributes object.

When a Box Attributes object is added to all text objects in a group using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added box attribute objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Colortable

A colortable object defines a set of colors allocated for a viewport and provides an efficient way to manage colors for non-TrueColor visuals. On TrueColor systems and in the Java version of the Toolkit, colortables are not used at run time. In the Builder, colortables are used even on the TrueColor systems to define the number of colors displayed in the Builder's color palette.

The color of an object in a viewport is defined by its three color coordinates, but the color that is actually displayed is the nearest neighbor in the color table to the point defined by those coordinates. This can yield surprising results in viewports with restrictive color tables on non-TrueColor systems.

Note that the total number of colors available is the number of colors defined by the ColorFactor attribute times the number of grades specified with GradeHint . If the product of the two numbers is greater than the number of colors your screen can display, the total number of available colors may be less than the number of colors in the color table. For example, you are limited to 256 different colors at any one time on an 8-bit color machine, and this hardware limitation takes precedence over the software color table definition. (Remember that the color limit also applies to other applications that may be running at the same time, and may have color tables of their own.) The results are not easily predictable if you try to define more colors than your machine can display.

The colortable object is created automatically every time a viewport is created and has the following attributes:

Type
Defines the type of the color distribution: STANDARD or RAINBOW. The STANDARD distribution allocates evenly distributed colors in the RGB color space. The RAINBOW distribution uses an algorithm that allocates colors in a rainbow-like palette and makes dithering nicer.

ColorFactor
Defines the number of colors for the STANDARD colortable or the number of hues for the RAINBOW colortable. If set to 0, a default value is used. A value equal to 1 may be used to simulate a greyscale or monochrome display. This is an index into a table of predefined values. For the STANDARD colortable, the values are:

Font Table

The font table object is a two-dimensional array of fonts that controls the selection of fonts available for use in a viewport. Each row of the array corresponds to a font of the same family, weight, and style, while the columns contain fonts sorted by size. It is created automatically every time a viewport is created and has the following attributes:

NumTypes
Defines the number of font types in the font table. Each combination of font family, weight, and style corresponds to a different style. For example, Courier, Bold, Italic represents a type.

NumSizes
Defines the number of font sizes in the font table.

Fonts
This is the actual font table. It is a container object containing a collection of font objects, described below.

It is the user's responsibility, when editing fonts in a table, to arrange them in such a way that all fonts in one row have the same font type and the sizes range from the smallest for the first font to the largest for the last font in the row. If the order is incorrect, text fitting for a SCALED text object may fail or yield odd results.

When a font table is added to a group of objects using the group's Edit All option, the Attribute Clone Type option of the Builder controls the constraining of the corresponding attributes of the added font table objects (the attributes are constrained if the Constrained Clone, the default, setting is used).

Font

The font object is used to keep information about one font. It is created automatically every time a font table object is created and has the following attributes:

MultiByteFlag
Specifies whether the font handles the characters as single-byte, multi-byte or UTF8. The attribute also controls the font usage as follows:

On Windows, setting the attribute to the UTF8 value also causes the wide character (Windows' UNICODE) version of the font to be used for rendering all text objects that use the font.

In the X Windows environment the attribute also controls the use of font sets. If the value of the attribute is set to SINGLE_BYTE, the XFontName attribute specifies a single font to use. Any other value causes the value of the XFontName attribute to be interpreted as a comma-separated font set containing one or more fonts. All the text objects that use the font will be rendered using the specified font set via the Xmb family of the text rendering functions.

For all fonts of the default font table and fonts with the font charset attribute set to DEFAULT_CHARSET, the MultiByteFlag may be set globally by setting the GlgMultibyteFlag global configuration variable. The attribute value is ignored in the Java version of the Toolkit.

Note: The multi-byte setting does not mean that each character has the same fixed length of more than one byte. Instead, it means the use of variable width characters where each character may consist of one or more bytes.

XFontName
Holds the name of the font to use when the drawing is displayed in the X Windows environment. If wild card characters are used, the first matching name is used. If the font name starts with the `$' character, the rest of the string after the `$' character defines the name of the environment variable that specifies the font name to use. This could be used as an escape mechanism for defining a special font at run time.

WinFontName
Holds the name of the font to use when the drawing is displayed in the Microsoft Windows environment. The environment variable escape mechanism described for XFontName is supported for WinFontName as well.

WinCharset
Specifies the font's charset. If the value of the attribute is set to DEFAULT_CHARSET, the version of the font with the first found charset will be loaded and used, otherwise the version of the font with the specified charset will be loaded.

For fonts whose charset attribute is set to DEFAULT_CHARSET (including the fonts of the default font table) the attribute may be set globally by setting the GlgFontCharset global configuration variable. The attribute value is ignored in X Windows environment and in the Java version of the Toolkit.

JavaFontName
Holds the name of the font to use when the drawing is displayed in the Java environment.

FontName
An alias for the used font name attribute for backward compatibility with pre-2.5 releases. It is dynamically mapped to the one of the above attributes at run time depending on the environment. For example, if the Java environment is used, the FontName resource name may be used to access the JavaFontName attribute.

In C/C++ and ActiveX environment, the GLG_DEFAULT_FONT_FILE environment variable may be used to specify the location of the file that contains the list of fonts for the default font table. In the X Windows environment, each entry of the file may contain either a font name a comma-separated list of font names comprising a font set (for font sets, the MultiByteFlag attribute will be set to an appropriate value automatically). The fonts defined in the file will override the fonts defined in the default font table.

PSName
Specifies the name of the PostScript font to use in place of the font when producing PostScript output.

By default, the PostScript Font Name attribute is set to match the Font Name attribute, which is sufficient for Times, Courier and Helvetica families of fonts. For other fonts or if a different font mapping is desired, it has to be set manually.

In C/C++ and ActiveX environment, the GLG_DEFAULT_PS_FONT_FILE environment variable may be used to specify the location of the file that contains the list of the PostScript fonts for the default font table. The fonts defined in the file will override the PostScript font names defined in the default font table.

Light Object

The light object is used by a viewport to hold the viewport's lighting attributes. In earlier versions of the Toolkit these attributes were part of each viewport. Starting with the 2.6 release of GLG, the light attributes are split into a separate light object to conserve space if lighting is not used by the viewport.

The light object has the following attributes:

LightType
Specifies a type of shading to be used in rendering three-dimensional objects. Currently available values are NONE (GLG_NO_LIGHT) and FLAT (GLG_FLAT_LIGHT). If the LightType is NONE, all lighting is ambient, and all polygons will be rendered in their original colors (as long as the LightCoef and AmbientCoef attributes add to one). The coloration of a polygon surface always depends on the total light intensity (sum of the ambient and point lights), and its FillColor attribute. If the LightType is FLAT, the actual color used to fill a polygon also depends on its position relative to the light vector. For more information about lighting, see Lighting in Structure of a GLG Drawing.

LightPoint and LightDirection
Define start and end points of the light vector. Light is directed from the LightPoint point to the LightDirection point. Note that these two points define the direction of the light source. The light itself appears to be infinitely distant.

LightCoefficient
Controls the proportion of a viewport's light cast by the light source at LightPoint . This is a scalar value, ranging from 0 to 1. The sum of the light coefficient and the ambient coefficient should be between 0 and 1, otherwise color distortion may occur. (Of course, setting the sum greater than 1 may be used to produce special effects.)

AmbientCoefficient
Defines the proportion of a viewport's light cast by ambience. In a sense, this controls how bright the completely shaded places are. The coefficient is a scalar value, which can range from 0 to 1.

When a light is added to a group of viewports using the group's Edit All option, constrained copies of light objects are added (controlled by the Attribute Clone Type Builder option). Changing attributes of any constrained light object will affect all light objects. Use the Unconstrain button of the Attribute Object dialog to unconstrain selected light object attributes in the constrained light object.

Geometrical Transformations

The geometrical transformations are those that can be applied to a point in three-dimensional space, or a data point of type G. Because graphical objects are described by a set of three-dimensional control points, these transformations can, by extension, be applied to entire three-dimensional graphical objects. (For information about the distinction between attaching a transformation to an object and to the object's points, see Transformations as Objects on page 31.)

Several geometrical transformations can be concatenated together into a list, with each transformation applied to the output of the previous transformation in the list.

When the rendering routines are attempting to draw a graphical object, they first look to see what transformations are attached to the object. If there are any, they are applied to the object before it is displayed.

The set of transformation objects available in GLG can be divided into matrix and parametric. The matrix stored by a matrix transformation may be directly applied to the graphical objects, while the parameters in a parametric transformation must first be used to create the transformation matrix before it can be applied. While the matrix transformations store information in a more compact way, they are static and can not be easily changed. The parametric transformations can be changed dynamically by changing the transformation's parameters. For more information about the structure of GLG transformations, refer to Transformations on page 30.

As a convenience, most of the parametric transformations include a scaling factor with their most commonly used parameters. This is to say that these parameters are actually the product of two attributes. For example, the distance moved in a MoveBy transformation object is the product of the Distance and the Factor attributes. A user might want the actual distance to range between 0 and 500 units, while the input data received is a number between 0 and 1. He or she could set the Distance attribute to 500, and use the resource-setting mechanism to control the Factor attribute with the actual data received. This also separates the input logic from the geometry of the drawing, as the Distance may be changed without affecting the input data. If the input data is in a range different from 0 to 1, a range transformation may be attached to the Factor attribute to handle input data in an arbitrary range.

Note that though the following sections describe the entire set of GLG transformation objects, a program can create more specialized or elaborate transformations simply by querying a drawing's control points, calculating new values within the program, and changing those resources. It is best to think of the list of transformations that follow as a list of those transformations for which additional programming is not necessary, rather than as a complete list of what is possible.

Scalar Transformations

There are several transformation objects designed to apply to simple scalar (D) values. A scalar transformation takes the value of the attribute it is attached to, transforms it according to the type of the transformation and sets the transformed value of the attribute to the resulting output. Scalar transformations cannot be concatenated, so you can't attach more than one scalar transformation to an attribute. However, you can "chain" transformations by attaching other scalar transformations to the parameters of a scalar transformation.

String Transformations

There are three special string transformations that can be applied only to string attributes. Note that transforming a string is not the same as transforming a text object. A string transformation can only change the text of a string, while a text object can be transformed like any other graphical object. String transformations cannot be concatenated, therefore only one string transformation can be attached to a string attribute.

Common Attribute Transformations

Common attribute transformations can be attached to an attribute of any type: D, S or G. They include the following types of transformations: