PREV NEXT

Generic Logic, Inc. www.genlogic.com


3 GLG Objects

In addition to being familiar with the overall structure of a GLG drawing, it is useful to know about the variety of objects you are liable to see in such a drawing. This chapter contains a description of most of the objects that make up a drawing.

Note that there are some objects that are not described here. Some of these are never seen by the user, and others are seen, but may not be available to the user. The objects can be easily divided into the graphical and the non-graphical objects.

The graphical objects are those objects that are readily visible to a user looking at a GLG drawing. They may be divided into two groups, the simple and the advanced objects. The simple objects are as follows:

Polygon
The basic graphical object, used for lines and shapes.
Parallelogram
Another sub-class of polygon, for parallelograms and rectangles.
Rounded Rectangle
A rectangle with rounded corners, a sub-class of polygon.
Arc
Represents shapes with round edges, such as arcs and circles. A sub-class of polygon.
Ellipse
An ellipse, rendered as a special case of a rounded rectangle.
Spline
A multi-point Bezier or Catmull Rom cubic spline, used to render free shape curves.
Text
For placing text in a drawing.
Marker
A small design for marking a point position.
Image
For placing GIF, JPEG, PNG and BMP images in the drawing.
GIS Object
An integrated map object for embedding images generated by the GLG Map Server into a GLG drawing and automatically handling Map Server requests and user interaction.
Viewport
This is the drawing surface for a GLG drawing, and a container for other objects. This object controls the view a user has of all the objects within it.
Screen
Controls aspects of a viewport's appearance.

You can use the simple graphical objects to create a wide variety of drawings that include elaborate animations. However, the simple objects do not use many of the advanced features of the GLG drawing structure. The advanced objects allow a user to define complex collections of simple objects, which can then be manipulated as if they were simple objects. This ability to add layers of complexity to a drawing is the key to the power of a GLG drawing. The list below shows the advanced graphical objects:

Group
Used to assemble a collection of simple objects into a complex one. The groups may be used to hold collections of graphical or non-graphical objects.
Connector
A recta-linear or arc path for connecting objects.
Reference
A Reference object is a wrapper around a group of objects used as a "template". The Reference object may be used to replicate the same template in multiple places in one drawing or in multiple drawings. It may also be used as a convenient wrapper for positioning a group of objects using a single anchor point. There are three flavors of the Reference object:

Chart objects are specialized objects used to render real-time charts and their subobjects:

Chart
A specialized object used to render real-time charts.
Plot
Represents individual plot lines in a chart.
Level Line
Displays a horizontal line representing a threshold value in a chart.
Axis
A specialized object for rendering axes in a chart as well as stand-alone ruler objects.
Legend
A specialized object for displaying chart legends.

GLG non-graphical objects are used to control the appearance and behavior of graphical objects. They are as follows:

Data
Used to hold a data value.
Tag
May be attached to a data object to mark it as a global resource or to define database connectivity for its data value.
Attribute
Similar to the data object, but used to hold an attribute value.
History
Used to control scrolling behavior in graphs.
Alias
Specifies an alternative, application-defined (logical) name for accessing arbitrary resource hierarchies.
Color Table
Controls the selection of colors available for display in a drawing
Font Table
Controls the selection of fonts available for use in a drawing.
Font
Specifies the font to use for a text object.
Rendering
Specifies an extended set of rendering attributes.
Box Attributes
Specifies attributes of a box drawn around the text object.
Line Attributes
Background Attributes
Specifies rendering attributes of plots, grids, level lines, time lines, cross-hair cursors and backgrounds of chart objects and light viewports, as well as tick attributes of axis objects. The Background Attributes does not represent an actual object type. It is an object type label used in the GLG Builder for the Line Attributes objects used to render an object's background.

The last section of this chapter describes the variety of available transformations used to implement dynamic behavior, as well as the alarm objects used to monitor data values. Though these are in the same category as the other non-graphical objects, they are complex enough that they merit their own section.

Transformation
Describes a transformation associated with the object.
Alarm
Describes an alarm associated with the data or attribute object; it is implemented as a special type of a transformation object.

The objects and their attributes are described in greater detail in the rest of this chapter.

NOTE: All attributes of GLG objects are stored as S (string), G (geometrical), or D (double-precision scalar value) data values. Where an attribute is described below as having a limited number of values, it is actually stored as a scalar (D) value, often as the index into an array of possible values.

Common Attributes

All GLG objects share a basic structure. That is, they are all sub-classes of the basic object class. This means that most objects share a few basic attribute types. Most of the common attributes are displayed in the separate area at the top of the respective properties dialogs in the Graphics Builder. Some of the most commonly encountered types are described in the list below.

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 the Hierarchy of Resources section on page 39 of 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.
HISetup (advanced)
This read-only attribute is set to TRUE when an object is set up. The attribute is not shown in the Object Properties dialog, but may be queried via the GLG API to determine if the object's hierarchy has been set up.
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 (and also Java, C#/.NET and JavaScript versions of the Toolkit), the transparency is rendered as true alpha-blending. For the GDI 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.
MoveMode
This attribute specifies how the object's control points are modified when the object is moved with the mouse and may have the following values:
GLG_MOVE_POINTS
Moves all controls points of the object, but does not move control points of geometrical transformations attached to the object, if any. For example, if the object has a rotate transformation attached, the center of rotation will not be moved with the object when the object is repositioned.
GLG_STICKY_CENTER_MODE
Moves all control points of the object as well as the control points of geometrical transformations attached to the object, if any. This setting may be used when the object has to rotate around its center: when the object is moved, the center of rotation will moved with the object to preserve its position relatively to the object. This is the default for newly created objects.
GLG_MOVE_BY_XFORM
Instead of moving the object by changing the spatial coordinates of its control points, the object is moved by creating a matrix move transformation and attaching it to the object. The transformation moves the object without reassigning coordinates of its control points, which is useful if it is needed to preserve the original coordinates of an object's points.
In addition to moving an object with the mouse, the attribute also controls how the object is modified using the Builder's Transform Object Points button or via the GLG API functions which move or transform an object.
CoordFlag
This advanced attribute specifies the coordinate system used for rendering the object and may have the following values:
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.
GLG_ABS_SCREEN_COORD_SYSTEM ("ABS_SCR" label)
The screen coordinate system of the viewport. For objects inside light viewports, it is the screen coordinate system of the parent viewport.
GLG_ABS_FLIPPED_SCREEN_COORD_SYSTEM ("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.
GLG_LVP_SCREEN_COORD_SYSTEM ("LVP_ABS" label)
The screen coordinate system of a light viewport (for objects inside a light viewport), or of a viewport if there is no light viewport.
GLG_LVP_FLIPPED_SCREEN_COORD_SYSTEM ("LVP_GLG" label)
The same as GLG_LVP_SCREEN_COORD_SYSTEM, but with 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.
HighlightFlag
This advanced attribute of drawable object is not shown in the Object Properties dialog and is used internally to implement object tracing functionality used by the entries in the Options, Trace/Highlight menu. The attribute may also be set to TRUE via the GLG API to highlight objects of interest in the drawing. The GlgHighlightPolygon global configuration resource described on page 423 of Appendix A: Global Configuration Resources of the GLG Programming Reference manual specifies the color, line width and other attributes of the outline rectangle used for highlighting.
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 the Rendering section on page 156 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone 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 method on page 181 of the GLG Programming Reference Manual.
The Global attribute also has two special values: BOUND and NONE. The BOUND value is used for rebinding attributes or reference objects (subdrawings and subwindows); refer to the Bindings section on page 112 for more information. NONE is used for some special attributes to prevent them from ever being constrained; refer to the GlgCloneObject method on page 181 of the GLG Programming Reference Manual 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.

Simple Graphical Objects

Simple GLG graphical objects can be directly viewed in a drawing. These are the simplest building blocks of a picture, and most of them will seem familiar to you. The following sections introduce the GLG objects in greater depth, and provide lists of the most commonly accessed object attributes.

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, rectangles, 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. The color RGB values are specified using the default 0-1 range, or using 0-255 range if the 255 Color Display option is activated.

An indexed color can be specified by using a negative value for the color's R component and setting the value of the G and B components to zero. The absolute value of the R component less 1 specifies the index of the indexed color to use, i.e. R=-1 specifies
color index=0, R=-2 specifies color index=1, and so on. Refer to the Indexed Colors section on page 218 for more information on using indexed colors.
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. The line width can scale depending on the setting of the LineWidthScaling attribute described later in the section.
OpenGL Note: If the OpenGL renderer is used in the Compatibility profile, the maximum line width is limited by the graphics card's hardware, which is equal to 10 for most of the graphics cards. The default OpenGL Core profile does not limit the line width, but requires OpenGL version 3.x or later. This limitation applies to the GLG editors as well as C/C++ and ActiveX deployment with the OpenGL driver enabled. GDI driver does not have this limitation. The Java, C# and JavaScript deployment options do not use OpenGL and do not have this limitation either.

Refer to
the OpenGL Versions, Compatibility and Core Profiles section on page 29 for information on the OpenGL profiles and enabling or disabling the OpenGL renderer.
LineType
The line pattern (solid, dashed, etc.) for rendering the edge of the polygon. GLG provides 32 predefined lines types shown in the Builder's Line Type palette.
OpenGL Note: The line type rendering is consistent between the GDI version of Builder, C/C++ library, ActiveX Control, Java, C#/.NET and JavaScript. However, rendering of some line types in viewports with OpenGL enabled in the OpenGL version of the Builder, C/C++ library and ActiveX control may differ due to the differences in the way line types are defined in OpenGL.
"Moving Ants" Dynamics Note: If LineType is greater than 32, the reminder of division of LineType by 32 is used as a line type, and the result of the division is used as a line type pattern offset in pixels. The length of the pattern is 32 for the GDI renderer, Java, C#/.NET and JavaScript, and 16 for the OpenGL renderer.
The line type pattern offset may be used for a "moving ants" animation of the line type pattern, as seen in the GLG Process Control Demo. The effect is achieved by repeatedly increasing the LineType value by 32, which causes the line type pattern to shift by one pixel. To avoid overflow, the LineType has to be periodically reset back to the initial line type value. Since the length of the pattern is 24 for the GDI renderer and 32 for OpenGL, resetting it after every 16 * 24 = 384 iterations makes it work regardless of the used renderer.
A predefined Flow dynamics may be attached to the LineType attribute for the line type pattern animation, see page 196.
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.
LineWidthScaling
Controls line width scaling, may have the following values:
GLG_NO_SCALING - the line width will not change when the viewport is zoomed or resized.
GLG_ZOOM_SCALING - the line width will increase or decrease when the viewport is zoomed in or out, or if the polygon size is changed via an attached scale transformation.
GLG_RESIZE_SCALING - the line width will change proportionally to the viewport horizontal extent.
Resize scaling is active only for resizable viewports and is ignored for the fixed size viewports. The viewport's BaseWidth attribute must be set to non-zero value and determines the initial viewport width that corresponds to the scaling factor of 1. When a viewport's width equals to BaseWidth, the rendered line width will be equal to the value defined by the polygon's LineWidth attribute and will increase or decrease proportionally to the viewport's new width when the viewport's size is changed. If BaseWidth is set to 0, the base width value will be inherited from the first parent viewport or light viewport with non-zero BaseWidth. Setting BaseWidth to -1 stops the inheritance.
GLG_ZOOM_AND_RESIZE_SCALING - combines the zoom and resize scaling.
If LineCaps is set to AUTO, the line width is changed in increment of two when it is scaled up or down to preserve the type of the line cap. The increment of 1 is used for other line cap values.
SelectionType
Controls polygon selection type, may have the following values:
GLG_DEFAULT_SELECTION_TYPE - selection is based on the polygon FillType. For polygons without fill, the polygon is selected only when the polygon edge is selected with the mouse.
GLG_SELECT_AS_FILLED - enables polygon selection by clicking on the inner (fill) area of the polygon even if the polygon is not filled.
Shading
Controls shading for an individual polygon. Shading is enabled for the viewport if it has a Light object added to it. The attribute may have the following values:
GLG_NO_SHADING - disables polygon shading
GLG_FILL_SHADING - enables shading of the polygon fill only (default)
GLG_FILL_EDGE_SHADING - enables shading of both the polygon's fill and edges.
AntiAliasing
Controls anti-aliasing 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. The default can be changed globally by using the GlgAntiAliasing global configuration resource.
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 and is used as a default setting for arcs, splines and rounded rectangles. It is also used for plot lines and bars of real-time charts to achieve smoother scrolling of charts with fast update rates.
For the C/C++ libraries and ActiveX, anti-aliasing is enabled only for the viewports that use the OpenGL renderer, which is activated by setting a viewport's OpenGLHint=ON when the OpenGL driver is used.
In Java, C# and JavaScript, anti-aliasing is always available and activated by default, regardless of the viewport's OpenGLHint setting.
The GlgAntiAliasing global configuration resource may be used to disable anti-aliasing by setting its value to zero.
LineCaps
Defines a line cap used at the end of lines and open polygons and may have the following values:
BUTT
Line ends with a flat edge (default).
ROUND
A rounded cap is added to each end of the line.
AUTO
The type of the line caps is determined by the line width, providing compatibility with the pre-4.1 releases. The BUTT line cap is used for even line width values, and the ROUND cap for odd values.
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 the Rendering section on page 156 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone 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.

Rectangle

A rectangle is a special case of the parallelogram object in which each pair of adjacent sides is perpendicular. A rectangle has two control points located at the end of the rectangle's diagonal and two constrained point at the end of another diagonal which are managed automatically.

Rounded Rectangle and Ellipse

An object of type ROUNDED is used to render both rectangles with rounded corners and ellipses. Same as a parallelogram, the rounded object is defined by three control points, but it is initially created in the Builder as a rectangle defined by two points.

Like the parallelogram, the rounded object is simply a sub-class of the polygon, so it has the usual polygon attributes, like LineType and FillColor. It also has the following attributes that control the object's rounded corners:

Radius1
Controls an extent of rounded corners along the side of the rounded rectangle defined by the first and second control point (Y dimension when originally created in the Builder).
Radius2
Controls an extent of rounded corners along the side of the rounded rectangle defined by the second and third control point (X dimension when originally created in the Builder). If set to -1, the value of Radius1 is used, and the size of rounded corners may be controlled with a single parameter - Radius1.
UnitType
Specifies units used for Radius1 and Radius2 attributes. The following options are available:
GLG_SCREEN_UNITS - corner radiuses are defined in screen coordinates; the size of the rounded corners stays constant.
GLG_WORLD_UNITS - corner radiuses are defined in world coordinates; the size of the rounded corners changes proportionally when the drawing is resized, but stays constant when the object is resized with the mouse.
GLG_RELATIVE_UNITS - corner radiuses are defined as coefficients in the [0;1] range relative to the extent of the rectangle's corresponding side. The size of the rounded corners changes proportionally when the drawing or the object is resized, maintaining a constant ratio between the size of the rounded corners and the length of the object's side in the corresponding direction. .
Resolution
The number of line segments used to render rounded corners. The default value for this is 7 for rounded rectangles (25 for ellipses). A larger value may be used for nicer rendering of rectangles with large corner radiuses.

If Radius1 and Radius2 are set to 1 in relative units, the object will render an ellipse. If UnitType is set to relative and Raduis2 is set to -1, the rounded corners will take the whole height of the object and an equal amount of space in the horizontal direction. This results in the object being drawn as a rectangle with a round left and right side, except when the object is too small in the horizontal direction.

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, GLG_SECTOR or GLG_BAND.
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.
MinRadius
Defines the inner radius of an arc band for arcs of the GLG_BAND type.
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

A 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 in a GLG drawing. There are several types of text object, which differ both in their behavior and in the number of control points.

All text types are scalable, adjusting the font size when the drawing is zoomed or resized. For most text types, scaling is controlled by the setting of the TextScaling attribute, but for FIT_TO_BOX and SPACED text types the scaling is controlled by the dimensions of the text's box defined by its control points. The FontSize attribute defines the base font size for scaling, which may be adjusted up or down to scale the text. The MinFontSize attribute controls the minimum font size allowed.

Setting MinFontSize to -1 may be used for automatic text label decluttering: the text will disappear if the drawing is zoomed out and there is not enough space to draw the text. Text scaling is not infinitely variable: different sizes of text are selected from the fonts in the font table to scale the text up or down. The viewport's font table can be edited to increase a number of available font sizes.

The following types of text objects are available:

FIXED
Has one control point defining its position and may be scaled when the drawing is zoomed or resized if requested by the setting of the TextScaling attribute.
FIT TO BOX
Text has two control points defining a rectangle to fit the text into. The text is always scaled by changing its font size to fit the text inside the rectangle.
TRUNCATED
Text has two control points defining a rectangle to fit the text into. If the text string does not fit, it is truncated, with an ellipsis displayed at the end of the truncated text lines that do not fit horizontally, and at the end of the text if all its lines do not fit vertically. The text may also be scaled when the drawing is zoomed or resized if requested by the setting of the TextScaling attribute.
WRAPPED
Text has two control points defining a rectangle to fit the text into. If the text string does not fit into the rectangle in the left to right direction, it is wrapped to the next line. The right to left direction is relative to the direction of the text as defined by the text's Direction attribute: it will be in the vertical direction for rotated text objects. The text may also be scaled when the drawing is zoomed or resized if requested by the setting of the TextScaling attribute.
WRAPPED & TRUNCATED
Text has two control points defining a rectangle to fit the text into. If the text string does not fit into the rectangle, it is wrapped to the next line; if it still does not fit, it is truncated and an ellipsis is displayed at the end of the truncated text lines. The text may also be scaled when the drawing is zoomed or resized if requested by the setting of the TextScaling attribute.
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, the third point controls the position of the text's lines. Similar to the FIT TO BOX text, the SPACED text is also always scaled by changing its font size to fit the text to the parallelogram defined by it's three control points.

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

TextColor
Defines the color of the text.
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 dialog, which is accessed by pressing the ellipsis button for the TextString attribute in the Properties dialog. A new line character ("\n") followed by the ellipsis is displayed at the end of multi-line text strings in the Properties dialog to annotate multi-line strings.
TextType
Defines the text type, can have the following values:
FIXED (GLG_FIXED_TEXT)
FIT TO BOX (GLG_FIT_TO_BOX_TEXT)
TRUNCATED (GLG_TRUNCATED_TEXT)
WRAPPED (GLG_WRAPPED_TEXT)
WRAPPED & TRUNCATED (GLG_WRAPPED_TRUNCATED_TEXT)
SPACED (GLG_SPACED_TEXT).
TextScaling
Defines how the text should be scaled when the drawing is zoomed or resized. It is applicable to all text types except the FIT TO BOX and SCALED, which are always scaled to fit to the text box regardless of the attribute setting. The attribute can have the following values:
NONE (GLG_NO_SCALING) to disable text scaling and always display the text using
the selected FontSize.
ZOOM (GLG_ZOOM_SCALING) to scale the text when the drawing is zoomed, but
not when it is resized.
RESIZE (GLG_RESIZE_SCALING) to scale the text when the drawing is resized, but
not when it is zoomed.
ZOOM & RESIZE (GLG_ZOOM_AND_RESIZE_SCALING) to scale the text on
both zooming and resizing.
The FontSize attribute defines the base font size for scaling, which is then adjusted up or down to scale the text. The MinFontSize attribute controls the minimum font size allowed. Setting MinFontSize to -1 may be used for automatic text label decluttering: the text will disappear if the drawing is zoomed out and there is not enough space to draw the text.
For the ZOOM scaling type, the zoom factor of the drawing's viewport is used to increase or decrease the text's font size. The font size will also change if the text object is scaled via an attached scale transformation.

For the RESIZE scaling, a ratio of the current width of the viewport to its base width is used to adjust the font size. The base width of a viewport is defined by the viewport's BaseWidth attribute. The font size will be increased to scale the text if the current viewport width is greater than the base width, and decreased if the current width is smaller.

Resize scaling is active only for resizable viewports and is ignored for the fixed size viewports. The viewport's BaseWidth attribute must be set to a non-zero value and determines the initial viewport width that corresponds to the scaling factor of 1. If BaseWidth is set to 0, the base width value will be inherited from the first parent viewport or light viewport with a non-zero BaseWidth. Setting BaseWidth to -1 stops the inheritance.

Text scaling is not infinitely variable: different sizes of text are selected from the fonts in the font table to scale the text up or down. The viewport's font table can be edited to increase a number of available font sizes. Refer to the Editing a Font Table section on page 163 for information on adding font sizes to the viewport's font table.
TextDirection
Defines whether text is GLG_HORIZONTAL, GLG_VERTICAL, GLG_VERTICAL_ROTATED_RIGHT or GLG_VERTICAL_ROTATED_LEFT.
Anchoring
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.
LineAnchoring
Defines horizontal alignments of text lines of a multi-line text object. If text lines have different length, Anchoring defines alignment of the text box (defined by the length of the longest text line) relatively to the text's control points, and LineAnchoring defines horizontal alignment of the text lines inside the box. LineAnchoring can be set to GLG_LLEFT, GLG_LCENTER or GLG_LRIGHT for the left, center or right alignment. It may also be set to GLG_LINHERIT to inherit horizontal alignment from the Anchoring attribute, which is a default. The alignment's left and right are relative to the left-to-right direction of the text, and become top and bottom for a rotated text.
AnchorOffset
Defines an additional offset to use for a FIXED text type with a single control point. The X, Y components of AnchorOffset define additional X and Y offsets between the text and its control point. A common use of the attribute is to define an additional offset for FIXED text objects whose control point is constrained to a marker. AncrorOffset can be set to a value slightly bigger than a half of the marker size to allow a small gap between the text and the marker.
FontType
Specifies the type of the font used to draw the text. FontType is a font family index in the viewport's font table. Refer to the Editing a Font Table section on page 163 for information on adding font types to the viewport's font table.
FontSize
Defines the font size of the FIXED text, or the maximum font size to use for fitting other text types. FontSize is a font size index to the viewport's font table. Refer to the Editing a Font Table section on page 163 for information on adding font sizes to the viewport's font table.
MinFontSize
Specifies the minimum font size to use when scaling the text. The MinFontSize is a column index to the viewport's font table. Setting MinFontSize to -1 activates automatic decluttering feature for scaled text: the text will not be drawn if there is not enough space to fit the smallest font (of size 0) into the text area.
SizeConstraint
This attribute is used to synchronize the fitting of FIT TO BOX and SPACED text objects. If more then 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 may be rendered using different font sizes, even if the boxes they are fit to have the same dimensions.

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' properties. The attribute assumes the value of NULL if no box attributes object is attached, in which case no box is drawn. See the BoxAttributes section on page 159 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 constraining of corresponding attributes of the added box attribute objects (the attributes are constrained if the default Constrained Clone 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 the Rendering section on page 156 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone 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.

A viewport's font table can be modified to add custom fonts, as well as increase the number of available font sizes to expand text scaling limits. Refer to the Editing a Font Table section on page 163 for details.

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, diamond 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.
SizeScaling
Controls marker size scaling, may have the following values:
GLG_NO_SCALING - marker size will not change on zoom or resize.
GLG_ZOOM_SCALING - marker size will increase or decrease when the viewport is zoomed in or out, or if the marker is scaled via an attached scale transformation.
GLG_RESIZE_SCALING - marker size will change proportionally to the viewport horizontal extent.
Resize scaling is active only for resizable viewports and is ignored for the fixed size viewports. The viewport's BaseWidth attribute must be set to a non-zero value and determines the initial viewport width that corresponds to the scaling factor of 1. When a viewport's width equals to BaseWidth, the rendered marker size will be equal to the value defined by the marker's MarkerSize attribute and will increase or decrease proportionally to the viewport's new width when the viewport's size changes. If BaseWidth is set to 0, the base width value will be inherited from the first parent viewport or light viewport with a non-zero BaseWidth. Setting BaseWidth to -1 stops the inheritance.
GLG_ZOOM_AND_RESIZE_SCALING - combines the zoom and resize scaling.
FillColor and EdgeColor
Define colors used to draw marker's components.
AntiAliasing
Controls anti-aliasing of the marker's edges and is the same as the AntiAliasing attribute of a polygon. In the OpenGL environment, the GLG_ANTI_ALIASING_DBL setting may be used for smoother scrolling of plots with markers in a real-time chart.
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 the Rendering section on page 156 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone setting is used).

Image

The image object is used to represent graphical images in GIF, JPEG, PNG and BMP formats. The GIF, JPEG and PNG formats are supported across all platforms, while the BMP format is supported only in the C/C++ on Windows, as well as in the Java and C#/.NET versions. TIFF images are also supported in the Java, C#/.NET and JavaScript versions of the Toolkit.

Transparent colors are supported via the TransparentColor attribute, and image transparency is supported via the Visibility attribute (by setting it to fractional values). In the C/C++ with OpenGL, Java, C#/.NET and JavaScript environments, an alpha channel transparency is also supported for PNG and TIFF images.

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.

In the Java and C# environments, an image may be loaded either synchronously or asynchronously, as controlled by the GlgAsyncImageLoading global configuration resource and the AsyncLoad attribute described below. In C/C++ (and ActiveX on Windows), an image is always loaded synchronously, and in JavaScript it is always loaded asynchronously due to the nature of JavaScript.

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 one of the supported image formats. In the Graphics Builder, as well as for the C/C++/ActiveX, the type of the file is determined by the file's extension:
.gif for a GIF file
.jpg for a JPEG file
.png for a PNG file
.bmp for a Windows bitmap (Windows only).
Note: When an image object is created in the Graphics Builder, a file browser is used to select an image file, and an absolute path is stored in ImageFile. To allow the application to be moved to a different directory or a different environment (Java, C# or web) without adjusting image paths, it is recommended to edit the stored ImageFile path to make it relative to the location of the drawing.
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 directory of the drawing
- trying to locate the file in one of the directories defined by the GLG_PATH
  environment variable or the GlgSearchPath global configuration resource
- attempting to load the file relative to the current directory as the last resort.
A List transformation may be attached to the ImageFile attribute to specify a list of image files for implementing image dynamics.
Cross-Platform Use Note: For cross-platform, Java and web-based deployment, use `/' as a path delimiter even on Windows. On Windows, the Builder converts `/' to `\' automatically when necessary.
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.
TransparentColor
Defines the image color to be rendered as transparent. This may be used for rendering icons with transparent background. The color RGB values are specified using the default 0-1 range, or using 0-255 range if the 255 Color Display option is activated. All image pixels with this RGB color value will be rendered as transparent. By default, the attribute is set to a value which disables transparency: (-1,-1,-1) in the default color mode, or
(-255,-255,-255) value in the 255 Color Display mode. The TransparentColor attribute is not supported in JavaScript.

When a transparent GIF image is deployed in a GLG drawing in Java and C# environments, both the transparent color defined by the TransparentColor property and the transparent color defined in the GIF image are enabled.

In the OpenGL, Java and C#/.NET environments, PNG images with an alpha-channel transparency may also be used with or without the use of the TransparentColor attribute.

Windows GDI Note: For transparent GIF images with the GDI driver on Windows, the TransparentColor setting overrides the transparent color defined in the GIF image. If TransparentColor is set to the disabled value described above, the transparent color defined in the GIF image is used.

Windows Note: the transparent color mode is supported on OS versions that support the TransparentBlt method.
EnableCache
Enables or disables the use of the image cache for this image object. If set to YES, image data are stored in the image cache to increase performance when several instances of the image are used in the drawing. It may be set to NO to avoid caching large background images that are used only once in the drawing.
AsyncLoad
Controls the image loading mode on per-object basis in the Java and C# environments. This attribute is available only in the Java and C# environments. In the C/C++ environment, images are local and are always loaded synchronously. In the JavaScript environment, images are always loaded asynchronously, due to the nature of JavaScript.

In Java and C#, images may be loaded either synchronously or asynchronously. The GlgAsyncImageLoading global configuration resource controls the image and GIS map loading mode for the entire application. It may be set to 1 to specify the asynchronous loading mode, or to 0 for the synchronous mode. An image's AsyncLoad attribute may be used to override the global application setting by setting it to 1 for the asynchronous and to 0 for the synchronous loading mode. If AsyncLoad is set to -1 (default), the image's loading mode will be controlled by the global setting.

In the synchronous loading mode, the rendering engine will wait for images to finish loading and will display the drawing when all images are ready. With the synchronous loading mode, the drawing will never be rendered without the image (unless the error occurred while loading the image).

In the asynchronous loading mode, the rendering engine will not wait for the image to finish loading. If the image has not been completely loaded at the time the drawing is rendered, the drawing will appear without the image, and the image will appear when it finished loading. When the image loading completes, the ImageLoad message is sent to the Input callback to notify the program, which may repaint the drawing using the Update method to display the just loaded image.
ImageLoaded
This read-only attribute may used to query an image loading status in Java, C# and JavaScript. It will return 1 if the image has been completely loaded and is ready to be drawn, or 0 otherwise.

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, transparently handling all low-level interaction with the Map Server. The GIS Object displays a map image in a selected GIS projection and automatically issues 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 Arrange, GIS Zoom Mode, Set as parent viewport's GIS Object menu option 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 84 and page 84 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 X and Y coordinates of the objects' control points are interpreted as degrees of longitude and latitude, and Z coordinate is interpreted as an elevation above the Earth surface in meters. 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).

Deploying GIS Object in Different Environments

The GIS Object integrates the map server in a GLG drawings and frees the application from handling low-level details of the map server.

When a drawing with the GIS Object is deployed in a C/C++ application (or an ActiveX control on Windows), the map server is deployed in the form of the map server library linked with the program executable.

When the drawing is deployed in a Java or C# application, as well as a JavaScript application in a web browser, the map server is deployed as a web-based map server. The map sever is set up as a CGI-bin executable on a web server, and the application internally uses a URL to request maps from the map server.

In either deployment, the GIS Object transparently handles all details of the map sever interactions, letting the application concentrate on the application logic.

Asynchronous Map Loading Mode

In the Java and C# environments, GIS maps may be loaded either synchronously or asynchronously, as controlled by the GlgAsyncImageLoading global configuration resource and the AsyncLoad attribute described below. In C/C++ (and ActiveX on Windows), a map is always loaded synchronously, and in JavaScript it is always loaded asynchronously due to the nature of JavaScript. Refer to the description of the AsyncLoad on page 81 for more information.

Asynchronous GIS Map Request

In both Java, C# and JavaScript, an asynchronous map loading request may also be used to better handle map zooming and panning. The asynchronous map request solves a problem of handling map zoom or pan operation which requires a new map image to be fetched from the server. With a synchronous map loading mode, an application will freeze until the new map is ready. With an asynchronous map loading mode, the dynamic symbols on the map would be displayed in the new map zoom state right away, but without the map in the background, with the new map appearing when it is received from the server. Both of these modes are undesirable, and the asynchronous GIS map request offers a solution.

The asynchronous GIS map request makes it possible for an application to issue a zoom or pan map request to the server, while continuing to operate in the old map state until the new map is ready. When the new map becomes ready, the display will switch to the new map zoom or pan state instantaneously.

With this feature, the application will never be frozen waiting for a new map or displayed without a map in the background. This is especially important for Java, C# and JavaScript applications, since they use a web-based GLG Map Server that introduces web-related delays compared to the embedded GLG Map Server used by the C/C++ applications.

An application has a complete control over the map loading request. The application is notified when the new map is ready, at which time it can decide to either install the new map, or discard it if it was superseded by another map request with a higher priority. The following Intermediate API methods may be used to request and process a map loading request:

RequestGISZoom
RequestGISMap
InstallGISRequest
AbortGISRequest
GetGISRequestInfo
SetScrollbarObserver
GIS Object Properties

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.

If the GIS object with a map in the RECTANGULAR projection is clipped by the viewport's visible area, the actual used center may be different from the value of the
GISCenter attribute. The actual used center may be queried at run time using the GISUsedCenter resource (G).
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 than the earth's diameter. The attribute is automatically adjusted when integrated GIS zooming is performed.

If the GIS object with a map in the RECTANGULAR projection is clipped by the viewport's visible area, or if the GIS object's
GISStretch is set to OFF, the actual used extent may be different from the value of the GISExtent attribute. The actual used extent may be queried at run time using the GISUsedExtent resource (G).

If a GIS object with a map in the ORTHOGRAPHIC projection is clipped by the viewport's visible area, its actual GISExtent is not adjusted to include only the visible area of the map. Instead, the original GISExtent defined in the GIS object is used to define the projection parameters without any adjustments, while the map image is generated only for the visible part of the map for efficiency. This makes it possible to generate zoomed images of the globe with a visible horizon line, as shown in the Trajectory demo. The demo uses a GIS object bigger than the viewport visible area to achieve the desired visual appearance of the map.
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 than 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.
Cross-Platform Use Note: Use a relative path instead of an absolute path to allow the application to be moved to a different directory or a different environment (Java, C# or web) without adjusting the paths. For cross-platform deployment, use `/' as a path delimiter even on Windows. On Windows, the Builder converts `/' to `\' automatically when necessary.
GISMapServerURL
Specifies the Map Server URL to be used by the Java, C#/.NET and JavaScript versions 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, C#/.NET and JavaScript versions 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 or 1002 to display tile extents. This attribute has no effect in the Java, C#/.NET and JavaScript versions of the Toolkit, where the map is generated by the web-based GLG Map Server, and its verbosity is controlled by the Map Server settings.
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, C#/.NET and JavaScript versions of the Toolkit.
AsyncLoad
Controls the map loading mode on per-object basis in the Java and C# environments. This attribute is available only in the Java and C# environments. In the C/C++ environment, GIS maps are rendered by the embedded GIS map server library and are always loaded synchronously. Due to the nature of JavaScript, GIS maps in the JavaScript environment are always loaded asynchronously from a web-based Map Server.

In Java and C#, GIS maps may be loaded from a web-based Map Server either synchronously or asynchronously. The GlgAsyncImageLoading global configuration resource control the image and GIS map loading mode for the entire application. It may be set to 1 to specify the asynchronous loading mode, or to 0 for the synchronous mode. The AsyncLoad attribute of a GIS object may be used to override the global application setting by setting it to 1 for the asynchronous and to 0 for the synchronous loading mode. If AsyncLoad is set to -1 (default), the GIS object's map loading mode will be controlled by the global setting.

In the synchronous loading mode, the rendering engine will wait for the map image to finish loading and will display the drawing when the map is ready. With the synchronous loading mode, the drawing will never be rendered without the map (unless the error occurred while loading the image).

In the asynchronous loading mode, the rendering engine will not wait for the map image to finish loading. If the map has not been loaded at the time the drawing is rendered, the drawing will appear without the map, and the map will appear when it finished loading. When the map loading completes, the ImageLoad message is sent to the Input callback to notify the program, which may repaint the drawing using the Update method to display the just loaded map.

An asynchronous map loading request described on page 79 may also be used for zooming and panning the map via the RequestGISZoom, RequestGISMap and SetScrollbarObserver Intermediate API methods. The asynchronous map loading request provides a way to use asynchronous map loading for the zoom or pan operations, but avoid displaying a drawing without a map while the asynchronously loaded map image is being loaded.
ImageLoaded
This read-only attribute may used to query a GIS map image loading status in Java, C# and JavaScript. It will return 1 if the map image has been completely loaded and is ready to be drawn, or 0 otherwise.

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 Arrange, GIS Zoom Mode, Set as parent viewport's GIS Object menu option. 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.

If a viewport is part of a group, the first Ctrl-Shift-click on a viewport selects it, and the second Ctrl-Shift-click moves 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 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 viewport borders. 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.
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. The type of the scrollbars is controlled by the ScrollbarType attribute. In the GIS Zoom Mode, the scrollbars control scrolling of the map displayed in the viewport's GIS Object, and in the Chart Zoom Mode, they control chart scrolling.

Possible values are:
NONE
Disables pan scrollbars.
PAN X
PAN Y
PAN XY
Enables either X or Y scrollbar, or both X and Y scrollbars.
AUTO PAN X
AUTO PAN Y
AUTO PAN XY
Automatically enables either X or Y scrollbar, or both X and Y scrollbars. The scrollbars will automatically appear only when the content of the viewport (or content of the chart in the Chart Zoom Mode) extends outside of the visible area and may need to be scrolled.
PAN X & AUTO PAN Y
PAN Y & AUTO PAN X
Enables a permanent scrollbar in one direction and an automatic scrollbar in another direction. The automatic scrollbar will appear as needed when the content extends outside of the visible area and may need to be scrolled.
For viewports that represent native controls (with WidgetType set to TEXT_EDIT or LIST), the Pan attribute controls the applicable scrollbars of the native widget. The AUTO PAN setting is ignored if it is not supported by the native widget on the run-time platform. For the TEXT_EDIT widgets, an absence of the PAN_X mask in the Pan setting activates text wrapping for long lines that extend past the width of the text box.
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.
ActivePan
Read-only attribute, contains a bit mask composed of the GLG_PAN_X and GLG_PAN_Y binary flags indicating which scrollbars are currently displayed.
ZoomEnabled
The ZoomEnabled attribute enables keyboard accelerators for integrated zooming and panning. When it is set to YES, pressing an accelerator key performs a corresponding zooming or scrolling operation. This setting is primarily used for quick interactive testing and prototyping in the Graphics Builder.

If the attribute is set to NO, keyboard accelerators are disabled, but zooming and panning operations can still be performed via the GlgSetZoom API function. This is the preferred method for a run-time application, where zooming and panning operations are performed via the interface buttons, while the keyboard accelerators are disabled to prevent accidental use.
The following accelerator keys are supported:
u - pan up
d - pan down
l - pan left
r - pan right
i - zoom in (zoom in in the X/Time direction in the Chart Zoom Mode)
I - zoom in in Y direction (Chart Zoom Mode only)
o - zoom out (zoom out in the X/Time direction in the Chart Zoom Mode)
O - zoom out in Y direction (Chart Zoom Mode only)
n - reset zoom.
In the Chart Zoom Mode, resets the Y ranges to fit all chart plots in the visible area of the chart in Y direction.
In the GIS Zoom Mode with a map in the ORTHOGRAPHIC projection, resets GISExtent, but keeps GISCenter unchanged. In the RECTANGULAR projection, resets both GISExtent and GISCenter, but keeps GISAngle.
N - reset zoom.
In the Chart Zoom Mode, resets the chart's X span to show all accumulated data samples in the visible area of the chart.
In the GIS Zoom Mode with a map in the RECTANGULAR projection, resets both GISExtent, GISCenter and GISAngle. In the ORTHOGRAPHIC projection, resets both GISExtent and GISCenter.
Shift-click-drag - ZoomTo, same as `t', see details below.
t - start generic ZoomTo mode (left-click and drag the mouse to finish)
In the Chart Zoom Mode, if the first point of the ZoomTo box is located within the X or Y axis area, zooming will be performed only in the direction of the selected axis. For example, if the user defines the ZoomTo box in the X axis area, the chart will be zoomed only in the X direction.
_ - start ZoomToX mode, which zooms only in the X direction and preserves the Y scale (left-click and drag the mouse to finish). It is especially useful in the Chart Zoom Mode.
| - start ZoomToY mode, which zooms only in the Y direction preserves the X scale (left-click and drag the mouse to finish). It is especially useful in the Chart Zoom Mode.
@ - start ZoomToXY mode (left-click and drag the mouse to finish)
T - start custom ZoomTo mode. A custom zoom mode lets the user define the ZoomTo area without performing the zoom operation. An application can use the selected ZoomTo rectangle as the input to implement custom zooming or object selection logic.
e - abort ZoomTo mode
Control-click-drag - Drag the drawing or map with the mouse, same as `s', see details below.
s - start generic dragging mode (left-click and drag the drawing with the mouse to finish).
In the Chart Zoom Mode, if the user clicks and drags the mouse within the X or Y axis area, scrolling will be performed in the direction matching the direction of the selected axis.
^ - start vertical dragging mode (left-click and drag the drawing with the mouse to finish). It is especially useful in the Chart Zoom Mode.
> - start horizontal dragging mode (left-click and drag the drawing with the mouse to finish). It is especially useful in the Chart Zoom Mode.
& - start XY dragging mode (left-click and drag the drawing with the mouse to finish).
f - fit the drawing to the visible area of the viewport (Drawing Zoom Mode only). The X/Y ratio is maintained depending on the setting of the Stretch attribute.
F - fit the area of the drawing defined by an object named GlgFitArea to the visible area of the viewport (Drawing Zoom Mode only). The X/Y ratio is maintained depending on the setting of the Stretch attribute.
U - anchor on the upper edge of the drawing (Drawing Zoom Mode only)
D - anchor on the lower edge of the drawing (Drawing Zoom Mode only)
R - anchor on the right edge of the drawing (Drawing Zoom Mode only)
L - anchor on the lower edge of the drawing (Drawing Zoom Mode only)
A - rotate the drawing clockwise around X axis (Drawing Zoom Mode only)
a - rotate the drawing counterclockwise around X axis (Drawing Zoom Mode only)
B - rotate the drawing clockwise around Y axis (Drawing Zoom Mode only)
b - rotate the drawing counterclockwise around Y axis (Drawing Zoom Mode only)
C - rotate the drawing clockwise around Z axis
(Drawing Zoom Mode or GIS Zoom Mode with the rectangular projection only)
c - rotate the drawing counterclockwise around Z axis
(Drawing Zoom Mode or GIS Zoom Mode with the rectangular projection only)
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. If the mouse is located on top of the chart object, sets the viewport's Chart Zoom Mode. In the GIS Zoom Mode, the map displayed in the GIS Object is zoomed and panned instead of the viewport's drawing, and in the Chart Zoom Mode, the chart is zoomed and scrolled. Zooming, panning, ZoomTo and reset accelerators are supported in the GIS and Chart Zoom Modes.
G - Resets the GIS or Chart Zoom Mode.
p - available only in the Graphics Builder in the GIS or Chart Zoom Mode.
In the GIS Zoom Mode, it displays the lat/lon and X/Y coordinates of the point at the current cursor position. If a valid elevation layer name is specified by either the GLG_GIS_ELEVATION_LAYER environment variable, the GlgGISElevationLayer global configuration resource or the -glg-elevation-layer command-line option, the point's elevation is also displayed.
In the Chart Zoom Mode, displays the X/Time value corresponding to the current cursor position, and the Y value in the range of the first Y axis.
q - available only in the Graphics Builder in the GIS or Chart Zoom Mode.
In the GIS Zoom Mode, displays information about the GIS selection. If GISVerbosity is set to 2000 or 2001, extended information is also written into the GLG error log file and printed to the terminal on Linux/Unix.
In the Chart Zoom Mode, it displays information about a data sample pointed by the cursor. The data sample is selected using the X mode of the chart's TooltipMode attribute.
Q - available only in the Graphics Builder in the Chart Zoom Mode.
It is the same as the `q' accelerator, but uses the XY selection mode.
Setting ZoomEnabled to YES enables accelerators in the Run mode of the Builder and at run time. If ZoomEnabled is set to NO, the accelerators are disabled, but the integrated zooming and panning may still be used at run time programmatically by invoking the GlgSetZoom method. The GlgSetZoom method takes accelerator keys listed above as its zoom type parameter.
The left mouse button is the default button for performing the ZoomTo operation, as well as for panning and scrolling the drawing by dragging it with the mouse. These defaults can be changed by setting the GlgZoomToButton and GlgPanDragButton global configuration resources. If the default is changed, the left-click used in the description of the affected operations changes to the click with the mouse button assigned to the respective ZoomTo or Pan operation.
There are several accelerators for the ZoomTo operation, allowing to activate zooming in only X, Y, or in both X and Y directions. To perform the ZoomTo operation, press one of the zoom accelerators (`t', `_', etc.), then left-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. Zooming in only X or Y direction is especially useful for real-time charts, allowing to zoom only along the time axis or the Y axis.
The are also accelerators for panning and scrolling the drawing by dragging it with the mouse. Several accelerators are provided, for panning and scrolling in only X, Y, or in both X and Y directions. In the GIS Zoom Mode, the map is scrolled by dragging it with the mouse, and in the Chart Zoom Mode, the chart is scrolled. To start, press one of the panning accelerators (`s', `>', etc.), then left-click and drag the mouse to scroll the content of the drawing. The user can also use the Control-click-drag sequence. Panning accelerators are primarily used for starting the dragging operation via the programming API at run time.
Performing zoom and pan actions on a viewport generates Zoom and Pan messages. Refer to the Appendix B: Message Object Resources section of the GLG Programming Reference Manual for details.
ProcessMouse
Controls the viewport's processing of the mouse events. The value of the attribute is formed by ORing binary masks to enable individual types of mouse events. Possible values may contain a combination of the following:
None (GLG_NO_MOUSE_EVENTS)
Disables processing mouse events for the viewport. May be used to reduce CPU consumption for viewports that do not need to process any events.
Tooltip (GLG_MOUSE_OVER_TOOLTIP)
Enables object tooltips. Use
Object, Add Tooltip menu option to add a tooltip to an object. Custom tooltip formatters can be supplied via the GlgSetTooltipFormatter method to generate dynamic context-based tooltip strings on the fly. Button tooltips are always active regardless of the setting of the ProcessMouse attribute.
Tooltip (Named Objs) (GLG_MOUSE_OVER_TOOLTIP | GLG_NAMED_TOOLTIP)
Enables tooltips for all named objects. The object's name will be used as a tooltip string.
Click (GLG_MOUSE_CLICK)
Enables processing of the mouse click events in the viewport. It activates processing of actions with
Trigger=MOUSE_CLICK, as well as object selection messages on the mouse click, which are passed to the Input callback at run time. It also activates the old-style (prior to v. 3.5) custom object selection events and mouse click feedback controlled by the MouseClickEvent, MouseClickState and MouseClickToggle properties of an object.
Move (GLG_MOUSE_OVER_SELECTION)
Enables processing of the mouse over events in the viewport. It activates processing of actions with
Trigger=MOUSE_OVER, as well as object selection messages on the mouse over, which are passed to the Input callback at run time. It also activates the old-style (prior to v. 3.5) custom mouse over events and mouse over feedback controlled by the MouseOverEvent and MouseOverState properties of an object.
Masks of a viewport's ProcessMouse attribute are inherited by its children viewports. For example, setting ProcessMouse to Click will enable mouse click processing for the viewport, as well as for all of its children viewports. If a viewport's ProcessMouse = Click, and the ProcessMouse of its child viewport is set to Move, the child viewport will process both the mouse click and mouse over events.
Refer to the Integrated Features of the GLG Drawing chapter on page 215 for details on custom events, mouse feedback and object tooltips.

Refer to the description of the GlgDisablePre35ObjectEvents global configuration variable on page 201 for information on disabling the old-style custom events and tooltips (prior to v. 3.5), which may decrease CPU load when moving the mouse over a large drawings.
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.
DisableInput
Controls whether or not a viewport and its input handler react to input events. Setting the attribute to YES disables all input events in the viewport; if the viewport has an input handler attached, it also disables the handler. The YES setting also disables all children viewports, except for the Java/Swing environment.
DepthSort
The DepthSort attribute defines how to render overlapping objects inside the viewport by controlling hidden surface removal. For example, in a solid cube, at most 3 of the 6 sides are visible at any one time. The rest of the back sides are obscured by the front sides and are not visible. If the cube rotates, different sides will be drawn or obscured.
If the OpenGL driver is used, setting the attribute to YES or SPECIAL activates the OpenGL depth buffer to perform hidden surface removal for objects in the viewport. Setting the attribute to NO or any other value disables OpenGL hidden surface removal. A group inside a viewport can disable hidden surface removal for its elements by setting its DepthSort=NO.
When hardware acceleration is provided by a graphics card, the OpenGL-based hidden-surface removal yields real-time 3D performance, making it possible to render complex 3D drawings in real time. The hidden-surface removal works on the pixel basis and properly renders intersecting objects.
The OpenGL driver can be used for the GLG Graphics Builder, the GLG HMI Configurator, as well as for GLG applications using the GLG C/C++ library. On Windows, the OpenGL driver can also be used for GLG applications that use the GLG ActiveX Control.
If nested groups (or other objects) with DepthSort=NO are encountered while a parent's OpenGL-based hidden surface removal is active, these objects will be drawn in a separate pass after all objects with DepthSort=YES have been rendered and will appear on top.
If OpenGL hidden surface removal is active, any semi-transparent objects must be rendered last, on top of all opaque objects, to achieve expected transparency effect, which is an established OpenGL technique. In GLG, this can be easily achieved by placing all semi-transparent objects in a group with DepthSort=NO, which will cause the group to be drawn last, on top of all other objects.
The GlgOpenGLZSort global configuration resource controls the number of passes used by the OpenGL hidden surface removal. The default setting of 2 enables two-pass technique which helps to eliminate pixel artifacts for polygons that have both fill and edges. The edges are rendered in a second pass using an offset defined by the GlgOpenGLDepthOffset global configuration resource (100 be default). If polygons have only fill or only edges, GlgOpenGLZSort can be set to 1 to use a single pass for increased performance. Setting the resource to 0 disables OpenGL hidden surface removal and resorts to the slower non-OpenGL depth-sorting technique. Refer to page 432 in Appendices for more information.
When the OpenGL hidden surface removal is active, the fill of polygons is not anti-aliased. To anti-alias polygon edges, use polygons with FillType=FILL_EDGE, and Shading=FILL_EDGE_SHADING. The two-pass technique described above helps eliminate polygon edge artifacts.
If the GDI driver is used, setting the attribute to YES or SPECIAL activates a depth-sorting algorithm that renders objects in the order which depends on their position in the 3D space. Setting the attribute to NO or any other value disables depth sorting.
If a viewport with DepthSort=NO contains several groups with different settings of the DepthSort attribute, the groups themselves will be drawn in the natural order, but the objects inside groups with DepthSort=YES will be rendered using the hidden-surface removal.
The SPECIAL setting uses a faster depth sorting algorithm which uses objects' bounding boxes for determining the drawing order of objects. The YES setting performs slower and more detailed tests. The algorithm used to sort objects is known not to work in complicated cases when objects intersect. Since any depth-sorting algorithm slows down the update procedure for a drawing, use it only when necessary.
The NO_GDI, PARTS and INHERIT settings of the attribute have no meaning for viewports and have the same effect as NO. This settings are used for other objects that use this attribute, such as groups. A viewport cannot inherit the DepthSort attribute from its parent.
In a program, the following constants correspond to the YES, NO and SPECIAL settings: GLG_ZS_YES, GLG_ZS_NO and GLG_ZS_SPECIAL.
KeepEditRatio
If set to YES, preserves the X/Y ratio of the viewport while editing its content in the Builder by going down into it using the Hierarchy Down button.
For example, the width of a viewport representing a toolbar is much bigger than its height. When Hierarchy Down button is used to go down into the viewport to edit its content, the viewport is extended to the entire drawing area, which stretches its content due to the different X/Y ratio of the drawing area. If KeepEditRatio=YES, the X/Y ratio of the viewport is maintained for the duration of editing by temporarily changing the SpanX and SpanY attributes of the viewport's screen. The span attributes are restored when going back up. The extent of the viewport's span is annotated by the round red markers in the corners of the default span area.
OwnsInputCB
Controls how the input callback is invoked for the input events occurring in the viewport. In an application code, an input callback is often attached to a top-level viewport. When an event occurs in a child viewport, the input callback is invoked with the viewport parameter set to the top-level viewport the callback is attached to.

However, the application may need to receive information about the actual viewport where the event occurred. In this case, the OwnsInputCB parameter of the child viewport may be set to YES, causing the input callback to be invoked with the viewport parameter set to the child viewport instead of the top-level viewport the input callback is attached to.

This makes it easier to handle commands in the application code, for example commands that display popup dialogs. These commands contain resource path to the dialog to be shown, and this path may be relative to the currently displayed page. To use a relative path when processing the command in the input callback, the application needs to know the viewport object of the current page. If each page has OwnsInputCB flag set to YES, the viewport parameter of the input callback will be set to the page's viewport object when the command is triggered. This avoids a need to attach an input callback to each page's viewport, as demonstrated in SCADA Viewer demo.

When the value of the OwnsInputCB is set programmatically, it follows the rules for attaching the input callback and must be set before hierarchy setup.
ScrollbarType
Specifies the type of the scrollbars to create:
NATIVE (GLG_NATIVE_SCROLLBAR)
Native scrollbars of the current run time environment.
VIEWPORT (GLG_VIEWPORT_SCROLLBAR)
Viewport-based GLG scrollbar widgets.
LIGHT VIEWPORT (GLG_LIGHT_VIEWPORT_SCROLLBAR)
Light viewport-based GLG scrollbar widgets.
DEFAULT (GLG_DEFAULT_SCROLLBAR)
Select scrollbar type depending on the type of the parent viewport:
- native scrollbars for viewport parent (or GLG viewport scrollbars for Qt integration)
- GLG light viewport scrollbars for light viewport parent.
Native and GLG viewport scrollbars are window-based. If they are used in a light viewport, they may bleed through other light viewports or graphical primitives that overlap them. To prevent that, light viewport scrollbars are used by default for light viewports.

The GlgNativeScrollbars global configuration resource and the corresponding environment variable described in Appendix A: Global Configuration Resources of the GLG Programming Reference Manual can be used to disable native scrollbars and use the GLG viewport-based scrollbars.

The GlgNativeScrollbarWidth and GlgScrollbarWidth global configuration resources may be used to control the width of the native and non-native scrollbars. An application can also supply custom scrollbar objects by setting the GlgVScrollbar and GlgHScrollbar global configuration resources using the GlgSetResourceObject function.

In the JavaScript environment, if an application uses integrated scrollbars for scrolling, it must preload scrollbars as assets as shown in the JavaScript demos and examples.
JavaScript File
Specifies an external JavaScript file that contains definitions of JavaScript functions used by the JavaScript transformations in the viewport. Use a path relative to the drawing location to avoid locking the application to an absolute path. This attribute is not supported in the JavaScript environment, where external JavaScript may be supplied by including the script file in the HTML page.
BaseWidth
Specifies a viewport's base width used to scale text and marker objects, as well as line width of polygons with the RESIZE scaling displayed in resizable viewports. If the viewport is resized and its current width becomes greater than the base width, the font size of the text objects, size of markers and line width of polygons with RESIZE scaling will be proportionally increased. If the current width becomes smaller than the base width, the size of objects will be decreased.

If a viewport's BaseWidth is set to 0, the viewport will inherit the BaseWidth setting of the first parent viewport or parent light viewport with non-zero BaseWidth. Setting BaseWidth to -1 disables base width inheritance.

The BaseWidth setting is ignored for the fixed size viewports.
Set BaseWidth
A button to set BaseWidth of the viewport to its current width.
InnerWidth
InnerHeight
Read-only attributes that may be queried to obtain the viewport's inner width and height. The inner width and height of the viewport is the same as the width and height of the viewport's window, less the width of the window border and scrollbars, if any. These attributes can be used as parameters of the pixel offset transformation to position objects at the right or bottom edge of a fixed scale viewport. To simplify the use of these attributes as offsets, their values are 1 less than the actual inner width and height.
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 XY enabled, so that the icons will keep their X/Y ratio constant while other objects in the drawing will stretch.
Set BaseWidth
A button to set BaseWidth of the viewport to its current width.
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 the Light Object section on page 166 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 constraining of corresponding attributes of the added Light objects (the attributes are constrained if the default Constrained Clone 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 the Rendering section on page 156 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone 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.
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 Properties dialog, but is accessible as a resource.

A viewport has a secondary screen object which is always attached to the viewport and controls its window-specific display attributes. Use the Screen Attributes button to display screen's properties. Screen attributes are inherited by the screen's viewport and may be accessed as resources of the viewport itself in an application.

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:

OpenGLHint
Controls the use of the OpenGL renderer for the screen's viewport. If set to OFF, a native GDI renderer is used, otherwise the OpenGL renderer is used if available. The flag is ignored in the Java, C#/.NET and JavaScript versions of the Toolkit.

The flag may have several ON values with different rendering priorities, from highest (1) to the lowest (3), which control the type of the OpenGL renderer to use: hardware or software. Viewports with higher priorities use hardware-accelerated renderer, while viewports with lower priorities may use software renderer. The software renderer may be used for icon buttons and other secondary windows with a small number of objects or infrequent updates. The use of the software renderer allows an application with a large number of viewports to use nice anti-aliased OpenGL rendering for all viewports without exceeding the graphics card's limit on the maximum number of OpenGL windows, which varies from card to card.

The runtime mapping of the OpenGL priorities to the type of the used OpenGL renderer is controlled by either command-line options, global configuration resources or environment variables. Refer to the Hardware and Software Renderers, OpenGL Priority section on page 29 for detailed description of the runtime mapping and all mapping options.

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 the OpenGL or GDI (Native Windowing System) Renderer section on page 27 for details.
OpenGL
Read-only attribute for the programming use that provides the current status of the OpenGL renderer. If the OpenGL renderer is successfully initialized and is used for rendering objects in the screen's viewport, the attribute will be set to the GLG_HARDWARE_OPENGL or GLG_SOFTWARE_OPENGL value, depending on the type of the OpenGL renderer used by the screen's viewport. If the GDI renderer is used, the attribute value will be set to GLG_NO_OPENGL. This attribute is not shown in the Properties dialog, but is available as a resource at run time.
XftFonts
Controls the type of X Windows fonts that can be used in C/C++ environment on Linux/Unix. Setting XftFonts=YES enables the use of XFT fonts for the viewport, if they are defined in the font table. The default font table uses XFT fonts by default to provide anti-aliased text rendering. Setting XftFonts=NO disables XFT fonts even if they are defined in the font table, and forces the use of core (XLFD) X fonts regardless of the setting of a font's XFontType attribute.

Setting XftFonts=NO can be used to maintain compatibility with the previous releases that did not support XFT fonts. The XFT fonts can also be disabled globally for all viewports using the GlgXftFonts global configuration resource, or the corresponding environment variable and command-line options. Refer to page 434 of the GLG Programming Reference Manual for more information.
LocaleType
Specifies locale type for rendering text strings in the viewport. It is used as a locale handling hint for XFT fonts, as well as a UTF8 locale hint for all fonts, and may be set to the following values:
Default (GLG_DEFAULT_LOCALE)
Use the current locale's encoding when rendering the viewport's text string using XFT fonts.
Inherit (GLG_INHERIT_LOCALE)
Inherit the parent's viewport locale type.
UTF8 (GLG_UTF8_LOCALE)
Assume all text strings in the viewport to be in the UTF8 locale regardless of the current locale type, for rendering with all font types.
XFT Latin1 (GLG_XFT_CHAR8_LOCALE)
Assume all text strings in the viewport to be in the Latin1 encoding when rendering them with XFT fonts.

The current locale is inherited from the system settings by default. This setting may be overridden by using the GlgLocaleType global configuration resource, or the corresponding environment variable and command-line options, refer to page 426 of the GLG Programming Reference Manual for more information.

Refer to the description of a font's XftFontName attribute on page 165 for information on how LocaleType is used with XFT fonts, as well as how to deploy drawings created in the UTF8-based locales on Linux/Unix to a Windows platform.
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 as a resource at run-time using the CoordSystem resource name and may have the following values:
YES (WORLD) (GLG_WORLD_COORD_SYSTEM)
A default GLG coordinate system used to define the objects' geometry. The extent of the visible part of the viewport for viewports with 1:1 aspect ratio is [-1000;+1000] in world coordinates in both X and Y directions, 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 XY 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 to match the viewport's aspect ratio. SpanX and SpanY are preset to 1000 and 1000 respectively for viewports created with the 1:1 aspect ratio, to 1200 and 900 for viewports with the 4:3 aspect ratio, and to 1600 and 900 for viewports with the 16:9 ratio.
NO (SCREEN) (GLG_SCREEN_COORD_SYSTEM)
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)
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)
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 (Fixed Scale) menu option.
Stretch X/Y (Stretch resource)
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 the Coordinate Systems section in Structure of a GLG Drawing.
PushIn
Controls which parts of the viewport are visible when Stretch XY 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.
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 the Native Widgets chapter on page 260.
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 for a viewport with 1:1 width/height ratio 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 XY set to YES. In the Builder, there are several options for creating resizable viewports with different width/height ratios. These options adjust SpanX and SpanY values to match the width/height ratio of the viewport. For example, creating a resizable viewport with 16:9 width/height ratio sets SpanX=1600 and SpanY=900 to avoid stretching objects inside the viewport when the viewport is displayed in a window with the 16:9 width/height ratio.
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.
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.
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.
PreciseSize
If set to NO, prevents the viewport from resizing for changes in size less than one pixel. This is used for improving scrolling performance of drawings that contain multiple viewports, such as palettes in the Builder. When a resizable drawing is scrolled, the size of children viewports may fluctuate by a fraction of a pixel due to the coordinate-to-pixel mapping, and the PresizeSize=NO setting prevents excessive repaint events due to viewport resizing.
ShadowWidth
Defines the width of shadows. If the value differs from 0, the shadow bevels are drawn around the viewport borders. 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 by the screen's viewport and is shown only in the viewport's properties dialog.
FonttableFile
Specifies a GLG drawing file containing a custom font table to use. A custom font table file can be shared between different viewports in multiple applications.

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.

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 attribute may 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.

Alternatively, an application can set a custom font table as a global Default Font Table by using the GlgDefaultFontTableFile and GlgDefaultFontTable global configuration resources described on page 436 of the GLG Programming Reference Manual. This custom font table will be inherited by all viewports that use a default font table.
FontTable
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. Refer to the Editing a Font Table section on page 163 for information on editing a font table.

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 constraining of corresponding attributes of the added font tables (the attributes are constrained if the default Constrained Clone setting is used).

On Windows, the default font table uses the charset of the current system locale or the charset defined using the GlgFontCharset global configuration resource. In the X Windows environment, the default font table provides fonts with the ISO Latin1 extended ASCII character set (ISO 8859-1). A custom default font table may be supplied by an external file specified by the GlgDefaultFontTabeFile global configuration resource, see page 434 of the GLG Programming Reference Manual.
Colortable
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 also in Java, C#/.NET and JavaScript) the color table is not used for rendering and is used only by the color palette widgets to define the number of colors in the color palette. The color palette of the GLG editors on TrueColor systems is defined by the color table settings in the glg_config and glg_hmi_config configuration files.

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 the Colortable section on page 160 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 constraining of corresponding attributes of the added color tables (the attributes are constrained if the default Constrained Clone 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 Screen Attributes button to access the screen's attributes, then press Edit Dynamics to edit the screen's transformation.
Screen Name
This resource may be used at runtime to supply a string to be displayed as a window title of top-level viewports.

The Screen object provides a number of additional resources that can be used at run time to position top level viewports, as well as query IDs and parameters of native widgets or windows used to render the viewport. Refer to the Screen Object Attributes section on page 468 of the GLG User's Manual and Builder Reference for more information.

Light Viewport

A light viewport is a lightweight version of a viewport. While a viewport object uses a native window as a rendering surface, a light viewport does not create its own native window and uses the window of its parent viewport as a rendering surface. This makes it possible to have semi-transparent light viewports, or to have light viewports with a transparent background. It also minimizes the number of OpenGL contexts used to render the drawing with the OpenGL driver, since the light viewport uses the OpenGL context of its parent viewport.

While a group object provides a simple container, the light viewport has its own coordinate system, may have a background and has an extended set of properties similar to the properties of a viewport. A light viewport may also have an attached interaction handler, making it possible to create GLG Widgets (such as dials and meters, sliders, buttons, etc.) that use light viewports to implement transparency. Any existing viewport-based GLG Widget can be converted to use a light viewport using the Builder's Arrange, Convert Viewport, Viewport -> Light Viewport menu option. The gconvert drawing conversion utility also provides options for converting between light viewports and viewports in batch mode, see Drawing File Conversion Utility on page 406 of the GLG Programming Reference Manual.

Since light viewports do not create their own native window, they comply to the drawing order when intermixed with other graphical objects. For example, polygon or text object can be reordered to be drawn on top of a light viewport, while they always appear behind the regular heavyweight viewports.

When a parent viewport needs to redraw an area that intersects a light viewport, the content of the light viewport will also be repainted. If a light viewport contains elaborate graphics with a large number of objects, it might be beneficial to use a regular heavyweight viewport in order to minimize expensive repainting.

Light viewports have a few limitations: since a light viewport does not create its own native window, it cannot be used as a top-level viewport of the drawing or to represent a native widget. However, it may contain regular viewports that use native widgets.

A light viewport has most attributes of the viewport and screen objects, except for the following attributes: OpenGLHint, DoubleBuffering, WidgetType, ShellType, ExactColor, XftFonts, LocaleType, FontTable and FontTableFile, JavaScript File, Light and ColorTable. See the Viewport section on page 82 and the Screen section on page 93 for a complete list of viewport and screen attributes.

A light viewport has an additional Background attribute object that contains rendering attributes of the light viewport's background, such as FillColor, EdgeColor, LineWidth, etc. The light viewport inherits FillColor, EdgeColor and LineWidth attributes from its Background object, and for convenience, these attributes are displayed both as light viewport properties and background properties.

The background's BoxFillType attribute controls rendering of the light viewport's background and border. Setting it to NONE will disable drawing of the background and the light viewport border. The bevel is controlled by the light viewport's ShadowWidth attribute, which may be set to 0 to disable the bevel.

The background's Opacity attribute controls transparency of the background in the [0;1] range. It does not affect transparency of objects inside the light viewport, which is controlled by the Visibility attribute of the light viewport.

Advanced Graphical Objects

The GLG advanced graphical objects are structures with which one can build complex relations between simpler objects. Any three-dimensional object in a GLG drawing, for example, is represented as an agglomeration of simple, two-dimensional, shapes. The advanced objects also provide a drawing designer with tools to designate an object to be a template for other objects. This can be done for simple two-dimensional objects, as well as for complex compound objects.

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 of a viewport object (page 88), 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_ZS_NO)
Hidden surface removal is disabled
YES (GLG_ZS_YES)
Hidden surface removal is enabled.
If the GDI driver is used, 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_ZS_SPECIAL)
If the OpenGL driver is used: same as YES, activates hidden surface removal.

If the GDI driver is used
: activates hidden surface removal using a faster but less precise depth sorting algorithm which uses objects' bounding boxes for determining the relative Z order of the objects.
INHERIT (GLG_ZS_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)
If the OpenGL driver is used: Keep the current hidden surface removal state.

If the GDI driver is used: Activates hidden surface removal, 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.
NO_GDI (GLG_ZS_NO_GDI)
Same as NO for the GDI driver. For the OpenGL driver, behaves as YES if hidden surface removal was already activated by a parent object, otherwise it behaves as NO. This setting is used to optimize performance of some 3D charts with the GDI driver.

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 372.

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 Options, Show Frame Points option, 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.

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. An arbitrary transformation may be used to position the series' instances instead of a linear path. 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 linear series is created in the editor, the object's origin point is constrained to the first point 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:

Template
The object used as a template replicated in the series. It 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. The Template resource is not visible in the Resource Browser by default, but will appear in the Resource Browser if it is named.
DepthSort
Controls hidden surface removal. This is the same as the DepthSort attribute for a viewport (page 88), except that the SPECIAL value uses a fast depth sorting algorithm optimized for Series objects when the GDI driver is used, and the NO_GDI value works the same way as for the group object (page 101).
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 the Cloning an Object section of the Using the GLG Graphics Builder for details on using the clone type.
Persistent
Controls persistency of attribute settings for the series' instances. If set to VOLATILE (default), only the series' template will be saved, and the instances will be created from the template on hierarchy setup performed at loading time. Any settings of the local attributes of the instances will be lost.
If the PERSISTENT setting is used, the instances will be saved in the drawing, preserving current settings when the drawing is loaded. If the number of instances is increased by changing the series' Factor, the additional instances will be created by copying the template. The existing instances and their attribute settings will be preserved, which may be used for setting line attributes of multi-line and other multi-set graphs in the Builder.
Recreate Instances
This button is present only in the Builder and may be used to discard the instances by recreating them from the template. To discard the instances at runtime, set the series' Factor to zero and call GlgUpdate.
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.

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, the second point defines the series X extent, and the third point defines the Y extent. 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 with the [-1000; +1000] coordinate extent is mapped to the size of one slot of the square series.

If some elements inside the series are made invisible, the square series can adjust the layout of the remaining elements using the policy specified by the HandleInvisible and FillSpace attributes.

The square series object has the following attributes:

Template
The object used as a template replicated in the series. It 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. The Template resource is not visible in the Resource Browser by default, but will appear in the Resource Browser if it is named.
DepthSort
Controls hidden surface removal. This is the same as the DepthSort attribute for a viewport (page 88), except that the SPECIAL value uses a fast depth sorting algorithm optimized for square series when the GDI driver is used, and the NO_GDI value works the same way as for the group object (page 101).
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 the Cloning an Object section of the Using the GLG Graphics Builder for details on using the clone type.
HandleInvisible
Controls the way the series adjusts layout of its elements when some elements are made invisible. Possible values are:
NO (GLG_SKIP_INVISIBLE_CELLS)
Doesn't adjust the layout; leaves an empty space when an element becomes invisible.
SHIFT_COLUMNS (GLG_SHIFT_COLUMNS)
Adjusts the layout by shifting visible elements within the same row to occupy empty space of the invisible elements.
SHIFT ROWS (GLG_SHIFT_ROWS)
Adjusts the layout by shifting visible rows to occupy empty space of the rows that contain only invisible elements.
SHIFT ROWS & COLUMNS (GLG_SHIFT_ROWS_COLUMNS)
Adjusts the layout by shifting columns first and then shifting rows. It doesn't combine elements from different rows into the same row, which may leave some rows not completely filled.
SHIFT_ALL_CELLS (GLG_SHIFT_ALL_CELLS)
Adjusts the layout by shifting elements across columns and rows to pack all rows to capacity, so that only the last row might not be completely filled.
FillSpace
Controls the way the series adjusts the size of its elements when some elements are made invisible. Possible values are:
NO (GLG_DONT_FILL_SPACE)
Doesn't adjust the element size.
ADJUST ROW HEIGHT (GLG_ADJUST_ROW_HEIGHT)
Adjusts the height of the series' rows to fill the empty space after the last visible row if the HandleInvisible attribute setting shifts rows.
ADJUST COLUMN WIDTH (GLG_ADJUST_COL_WIDTH)
Adjusts the width of the series' columns to fill the empty space if one or more columns at the end of all rows are empty, and the HandleInvisible attribute setting is different from NO.
KeepEditRatio
If set to YES, preserves the X/Y ratio of the template drawing while editing its content in the Builder by going down into it using the Hierarchy Down button.
Persistent
Controls persistency of attribute settings for the series' instances. If set to VOLATILE (default), only the series' template will be saved, and the instances will be created from the template on hierarchy setup performed at loading time. Any settings of the local attributes of the instances will be lost.
If the PERSISTENT setting is used, the instances will be saved in the drawing, preserving current settings when the drawing is loaded. If the number of instances is increased by changing the series' row and column factors, the additional instances will be created by copying the template. The existing instances and their attribute settings will be preserved. Keep in mind that the instances are numbered sequentially, and the row and column of the preserved instances may change if the ColumnsFirst attribute or the series' row or column factors are modified.
Recreate Instances
This button is present only in the Builder and may be used to discard the instances by recreating them from the template. To discard the instances at runtime, set the series row or column factor to zero and call GlgUpdate.

Like a one-dimensional series, a square series has a template object that is replicated to form the series. 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

A Reference object is a wrapper around a group of objects used as a "template". The Reference object may be used to replicate the same template in multiple places in one drawing or in multiple drawings. It may also be used as a convenient wrapper for positioning a group of object using a single anchor point. Reference attachment points described in the Attachment Points section on page 114 provide a convenient interface for connecting linear objects representing pipes, connectors or wires.

Reference Subtypes

There are three flavors of the Reference object used to implement different functionality:

Attributes

A Reference object has the following attributes:

Template
The original template object shared by all copies. For file and palette references, this resource is NULL until the drawing hierarchy is set up. After the setup, the template contains the template object loaded from a file or palette.

To edit the template of any reference object (Container, SubDrawing or SubWindow), use Traverse, Hierarchy Down (or ). If the template is stored in a separate drawing file, traversing down loads the template drawing. If the template uses a palette, traversing down traverses down the palette object. When finished, use Traverse, Up (or )to return back to the top level.

The options in the Options, Subdrawing Traversal menu control the Builder's verbosity settings when returning to the subdrawing level after editing the subdrawing's template. The default Verbose option presents a prompt before saving the modified template drawing, providing the user with options for saving the drawing in a different file or discarding the changes. The Silent (Auto-Save) option automatically saves the modified drawing into the same file without displaying a prompt.
When a template is modified, the changes take effect when the drawing containing subdrawings is loaded and set up, causing subdrawings to create their Instances from the Template. In the GLG Builder, it happens automatically when the drawing is reloaded on Hierarchy Up after the template editing is finished. If the template drawing in an external file that was changed outside of the GLG Builder, use the Reset toolbar button to update the drawing. An application can reset drawing hierarchy at runtime to reload the template.
Instance
For the SubDrawing and SubWindow objects, contains a local copy of the template used for rendering. If the ObjectPath attribute is not NULL, the Instance contains not the whole template, but its subobject used for rendering as defined by the ObjectPath. The Instance is created dynamically after the drawing hierarchy is set up. A user may edit its resources, but the changes are volatile: when the drawing is reloaded or reset, the attributes of the instance are recreated from the Template again, erasing any modifications a user might have made (except for Global attributes that are shared between all instances, and rebound attributes described in the Bindings section on page 112).

For subwindows and subdrawings, the Hierarchy callback will be invoked when the Instance is created from the template, giving an application a chance to initialize it before it is drawn.

The Instance object is visible in the Resource Browser as a resource. For example, if the template object is named MyTemplate, both "Instance" and "MyTemplate" resources will be visible and refer to the same local copy, while the "Template" resource points to the original template shared by all copies.

For the Container object, the template is displayed directly without creating a local copy, and both Instance and Template resources refer to the same object.
ReferenceType
The subtype of a reference object: GLG_CONTAINER_REF, GLG_SUBWINDOW_REF or GLG_SUBDRAWING_REF. This is a read-only attribute that is set at the creation time and defines the reference as either a Container, SubWindow or SubDrawing.
Source
The source of the template object for the SubDrawing and SubWindow objects. Possible values are:
GLG_USE_FILE - uses a template stored in an external drawing file specified by the SourcePath attribute.
GLG_USE_INCLUDED - uses a template included in the drawing. The template is stored as a part of the subdrawing. When the subdrawing is copied in the same drawing, the template is shared between all copies. The template is not shared between subdrawings in different drawings.
GLG_USE_PALETTE - a special case of the included template that allows embedding a palette of objects in the drawing for easy editing. The palette object is specified by the SourcePath attribute, which defines the palette's resource path in the drawing. If the SourcePath is not set, "$Palette" is used as a default palette path, which assumes an object named $Palette at the top level of the drawing hierarchy.

An example of a palette is a viewport object containing several graphical objects used as icons in subdrawings. Using a palette makes it easier to locate the template's icons when they need to be edited.
The Source attribute is set at the creation time depending on the way the object was created, such as SubDrawing From File or SubDrawing From Object. If the object is created using SubDrawing From File, the value of its Source may be changed from GLG_USE_FILE to GLG_USE_INCLUDED to permanently store the loaded template in the subdrawing, as opposed to using an external file.

The
Source attributes of subdrawings may be constrained, making it possible to change the template storage type of all subdrawings (from the referencing a separate file to including a template object in the drawing and back) by setting the Source attribute of a single SubDrawing object.
SourcePath
For subdrawings that use a template stored in an external file (Source=File), the attribute defines the location of the drawing file containing the template. 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.

Note: When a subdrawing is created in the Graphics Builder, a file browser is used to select the subdrawing file, and an absolute path is stored in SourcePath. To allow the application to be moved to a different directory or a different environment (Java, C# or web) without adjusting subdrawing paths, it is recommended to edit stored SourcePath to make it relative to the location of the drawing.
If SourcePath 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 global configuration resource
- attempting to load the file relative to the current directory as the last resort.
Cross-Platform Use Note: For cross-platform, Java, C# and web-based deployment, use `/' as a path delimiter even on Windows. On Windows, the Builder converts `/' to `\' automatically when necessary.
To implement subdrawing dynamics, a List transformation may be attached to the SourcePath to specify a list of drawing files. If the index of the List transformation changes, a different template drawing will be displayed. The ObjectPath attribute described below may be used for even more efficient object dynamics.
For subdrawings that use a palette (Source=Palette), the attribute defines a resource path for accessing the palette inside the drawing. The palette is usually a viewport that contains a collection of objects used for object dynamics. 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
Defines an object to be displayed in the subdrawing by specifying a resource path of the object within the template. If ObjectPath is set and points to an object inside the template, only that object will be displayed in the subdrawing. The template may have several named objects, and changing ObjectPath to a different object name will display a different object. The ObjectPath is relative to the template. If ObjectPath is not set, the whole template will be displayed.

For subdrawings that use an external file (Source=File), 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.

The ObjectPath attribute makes it possible to implement subdrawing dynamics using just one template containing several objects, instead of placing each object into a different drawing file and loading a new template drawing every time the subdrawing changes its shape. In other words, the subdrawing dynamics implemented via the SourcePath attribute may now be replaced with more efficient object dynamics via the use of ObjectPath. The the object dynamics also works with included subdrawings.

To implement object dynamics, a list transformation is attached to the ObjectPath attribute to define a list of resource paths pointing to different objects in the template. When the index of the list transformation changes, a different object path is used and a different object from the template is displayed in the subdrawing. Each value in the list may include an anchor path as described below.

The ObjectPath attribute may also contain two resource paths separated by a colon. The second path specifies the anchor path: 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 SubDrawing object. An object's anchoring is also affected by the value of the subdrawing's Origin attribute described below. Set Origin to (0;0;0) to anchor the subdrawing at the exact position of the anchor object specified by the anchor path.

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 when copying the template. It may be Full, Weak, Strong or Constrained. Refer to Cloning an Object on page 308 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. CloneType has no effect if EnableCache is set to NO.
FixedSize
Determines if a SubDrawing 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 SubDrawing 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. Subdrawing 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 subdrawings and containers may be adjusted by traversing down into the object's template using the Hierarchy Down button and changing the template's size.
EnableCache
Enables or disables template cache for subdrawings and subwindows that use template stored in an external file. If set to YES, template is cached for reuse by subdrawings that use the same template file. Instead of loading the template multiple times, each subdrawing creates a copy of the cached template.

If set to NO, template caching is disabled, each subdrawing loads its own copy of the template, and the CloneType attribute has no effect (attributes are not constrained). EnableCache may be set to NO to increase performance for SubWindows that are used to switch drawings: since only one copy of the drawing is loaded into the SubWindow, it is more efficient to load it directly instead of loading it in the cache and then copying it to create a local copy of the template.

EnableCache has no effect for subdrawings and subwindows that use included or palette template.
KeepEditRatio
If set to YES, preserves the X/Y ratio of the template drawing while editing its content in the Builder by going down into it using the Hierarchy Down button. If set to NO, the template drawing may appear stretched.
Attachment Points
An optional array of the reference's attachment points (AttachmentArray attribute). Refer to the Attachment Points section on page 114 for more information.
Bindings
A slot for attaching an optional array of rebound attributes (bindings) which enable the user to define local settings for instances of subdrawings and subwindows. Resource settings of bound attributes are persistent and are saved with the drawing, which allows the user to customize each instance by assigning unique resource settings in the GLG Builder. For example, bindings may be used to assign unique data tags to individual subdrawing instances to animate them with data from different sources.

SubDrawing
and SubWindow objects instantiate a copy of their template, which means that all instances of a SubDrawings or SubWindow with the same template will use the same initial attribute values taken from the template. For example, if a subdrawing represents a tank filled with liquid, and the drawing contains several such tanks, the initial liquid color for all tanks will be the same when the drawing is loaded. Bindings may be used to define a different liquid color for each tank that overrides the color defined in the template. Bindings may also be used to constrain a color in the subdrawing to the color of another object in the drawing. For example, the color of the tank may be constrained to the color of pipes connected to it.

Bindings for an attribute, such as the liquid color in the previous example, are activated by naming the attribute in the template and setting its Global flag to BOUND. If an attribute is BOUND, the attribute is stored in the drawing, instead of using the attribute from the subdrawing's template. When the subdrawing is loaded, the attribute from the template is replaced with (bound to) the attribute stored in the drawing.

When a subdrawing with named BOUND attributes is placed in a drawing, it will have a Bindings array containing local copies of the bound attributes. These attributes may be edited to define unique settings for each subdrawing instance. Bindings are saved with the subdrawing. When a subdrawing is loaded, all named bound attributes of its Instance will be "rebound", i.e. replaced with the corresponding local copies stored in the Bindings array.

The local copies of the attributes in the Bindings array may be edited using the Edit Bindings button in the subdrawing's Properties dialog. The user can change the values of the attributes and add unique tags to each of the subdrawing instances. The user can also change the names of the rebound attributes, constrain them to attributes of other objects in the drawing or add dynamics to them to modify behavior of the subdrawing's instance. These changes will affect only the instance of the subdrawing the Bindings are attached to. If a name, tag name or tag source of a rebound attribute is changed, only the new values will be visible in the subdrawing's Instance, while the old resource name and tag will still be visible in its Template.

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.

If an application uses several levels of nested subdrawings (or subwindows), a subdrawing may be used as a template by its parent subdrawing. When a BOUND attribute is rebound to a local copy stored in the
Bindings array, the Global flag of the local copy is reset to LOCAL by default, which disables further rebinding by any parent subdrawings or subwindows. To enable attribute rebinding across several levels of nested subdrawings, the Global flag of the local copy in the Bindings array can be set to BOUND again to enable rebinding by the parent subdrawing.
Origin
The geometrical attribute that controls anchoring of the template for SubDrawing and Container objects. The Origin attribute is not shown in the object's Properties dialog, but is visible as a resource in the Resource Browser. For containers and subdrawings with an included template, its position is also displayed as a round marker when the object's template is edited using the Hierarchy Down button (the marker may be hidden behind the template's objects).

For Containers and SubDrawings with no anchoring defined in the ObjectPath, the template will be anchored at a position defined by the Origin: the control point of the subdrawing will be at the same location as indicated by the Origin marker in the Template. For example, if Origin is set to (100;0;0), the subdrawing's single control point will coincide with the (100;0;0) position in the template. When a Container or a SubDrawing is created, the value of the attribute is set based on the user input. The value may be changed or reset to (0,0,0) by setting the Origin resource, moving the Origin marker in the template, or by dragging the subdrawing's anchor point using Ctrl-Alt-Left-Mouse-Move.

If an additional anchor path is specified in the ObjectPath attribute, the template is further offset by the distance from the center of the template's coordinate system to the anchor object defined in the anchor path of the ObjectPath attribute. 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.
TemplateLoaded    (JavaScript only)
In JavaScript, subdrawing and subwindow templates are loaded asynchronously. On initial appearance or after changing a reference object's SourcePath, the reference object will be ready to be drawn only after its template has been loaded. The TemplateLoaded read-only attribute is available in the JavaScript API to query a template loading status of the SubDrawing and SubWindow objects. It will return 1 if the template has been loaded and a copy of it is set up as the reference's Instance, or 0 otherwise.

If the template has not yet been cached, the reference object will be ready for drawing only after its template gets loaded and will not display anything until then. When the reference's template gets loaded, the TemplateLoad message will be sent to the Input callback to notify the program, which may repaint the drawing using the Update method to display the changed reference object. If the template has already been cached, the reference object will be ready to be drawn right away after hierarchy setup, and no additional messages will be sent to the Input callback. In either case, the Hierarchy callback will be invoked when the reference's Instance is being set up from the template.

The GetPendingTemplates and GetPendingInstances methods of the JavaScript API may be used to query the number of templates being loaded and the number of reference object instances waiting for their templates to be loaded.

A special feature of the SubDrawing objects is that any number of copies of the object may be made, with all copies using the same template object. Thus, subdrawings become useful in any drawing where there are a large number of identical (or nearly identical) objects. Editing the template will affect all instances of it in the drawing. If a subdrawing uses a template stored in an external file, all instances of the subdrawing 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 individual instances. 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 object 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 is copied, each copy will have its own independent copy of the template.

If SubDrawing or Container objects are used to represent connected nodes, the objects' single control point may be used to constrain connecting lines that represent edges. Attachment points described in the next section can also be added to the reference objects to define additional points that can be used for connecting lines representing edges, pipes or wires.

Attachment Points

Reference attachment points can be used for attaching other objects, for example, attaching pipes to tanks or valves that are defined as subdrawing or container objects. When using attachment points, the end of a pipe will stay connected to the exact position defined by the attachment point, with no need to precisely position the end of the pipe to coincide with the desired position in a subdrawing.

For example, if a valve with a pipe attached to the attachment point is moved, the end of the pipe will move with it. If the pipe is moved, the valve will move with it as well. All process control, electrical and electronic widgets have attachment points, which makes it easier to use these widgets in a drawing.

The Options, Selection Options, Show Attachment Points menu option controls if the attachments points are displayed in addition to the object's control points when the object is selected in the Graphics Builder or HMI Configurator. Displaying attachment points of the selected object is disabled by default to avoid interfering with control points editing, and the attachment points will become visible only when they could be used by the current editing operation for attaching other objects. The default may be changed by using the ShowAttachmentPoints variable in the glg_config file.

Attachment points can be added to the container and subdrawing reference objects using the Edit, Add Attachment Point menu option of the Enterprise Edition of the Graphics Builder. When adding attachment points, the Point Creation Mode menu underneath the Object Palette can be used to change the way anchor points are positioned. In the Position mode, an anchor point will be placed at the position defined by the mouse click. In the Use Point mode, control points inside the reference object will be shown when the mouse moves over it regardless of the selection of the Show Attachment Point option, and each control point will be highlighted when the mouse moves close to it. If a mouse is clicked near a highlighted control point, the attachment point will be positioned at the exact position of the control point.

The attachment points are "glued" to the object and maintain their relative position when a reference object is resized. The Attachment Points button in the reference object's Properties dialog provides access to the list of the object's attachment points, where a user can edit or delete attachment points as needed.

By default, when the attachment point is moved in a Graphics Builder, it moves the reference object it is attached to. For example, if a pipe line is attached to a valve symbol's attachment point, moving the pipe will move the valve together with the pipe.

To adjust the attachment point's position relatively to the reference object, the default behavior can be changed by using the Edit, Move Attachment Point menu option. In this option is selected, moving the attachment point will not move the reference object: instead, it will change the attachment point's position relatively to the reference object.

Using Attachment Points in the Graphics Builder

The Highlight Mode of the Graphics Builder is active by default and highlights all control and attachment points of an object under the mouse in the Constrain To Point and Use Point creation modes.

When creating a new object, such as a polygon, these modes are activated by clicking on the C or U buttons in the Point Creation Mode menu underneath the Object Palette. When a mouse is clicked on a highlighted point, the new control point added to a polygon is either constrained to the point in the Constrain To Point mode, or placed at the exact position of the point in the Use Point creation mode. The Options, Highlight Control Points menu option can be used to enable or disable the Highlight Mode. The Highlight Mode default can be changed using the HighlightControlPoints variable in the glg_config file.

Using Attachment Points in the HMI Configurator

In the HMI Configurator, Magnetic Mode is enabled by default to assist the user in connecting pipe and wires to the corresponding attachment points of process control and other widgets, such as tanks, valves, electric switches or transformers.

When a new pipe, wire or other object is drawn in the Magnetic Mode, the Configurator highlights all available connection points of an object (including its control points and attachment points) when the mouse moves over the object. When the user clicks on any highlighted point, the end of the polygon representing the pipe or the line is constrained to it.

The user can use Control-click to position the polygon point in the vicinity of a connection point without constraining. The Options, Magnetic Connection Points menu may be used to disable Magnetic Mode, as well as modify it to use the position of a highlighted connection point without constraining to it. The Magnetic Mode default can also be changed using the MagneticMode variable in the glg_hmi_config file.

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 the Cloning an Object section 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. This is the same as the DepthSort attribute for a viewport (page 88), except that the SPECIAL value uses a fast depth sorting algorithm optimized for polysurface objects when the GDI driver is used, and NO_GDI value works the same way as for the group object (page 101).
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 the Cloning an Object section 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 117.

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.

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 Options, Show Frame Points option.

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 Options, Show Frame Points; see page 418.

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.

Chart Objects

Chart

The Chart object is used to render real-time charts with large number of data points and fast update rates. A real time chart is highly optimized to handle hundreds of thousands of data points and update the display hundreds times per second. The chart supports integrated zooming and scrolling, chart tooltips, cursor feedback and data sample selection.

A chart object has two control points that define the geometry of its data area. The chart object is a composite object that contains a number of subcomponents, such as plots, axes and other auxiliary objects. The chart creates a required number of plots and axes and manages their layout. The chart object also handles chart tooltips, point selection and cross-hair cursor. The AxisType attribute of the chart's X axis defines the type of the chart: a scrolling strip-chart or an XY scatter.

A chart object has the following attributes:

Number of Plots
Specifies a number of plots in the chart. The chart automatically adds or deletes plots when the value of the attribute is changed. When plots are added or deleted via the GlgAddPlot or GlgDeletePlot API methods, the chart adjusts the value of the attribute to match the new number of plots.

When new plots are added, they are assigned default names formed by appending the plot's index at the end of the "Plot#" string, i.e. "Plot#0", "Plot#1" and so on. When plots are reordered, default names change to reflect the new order; a persistent custom name can be assigned to each plot.
Number of Y Axes
Specifies a number of Y axes in the chart. The chart automatically adds or deletes Y axes when the value of the attribute is changed.

When new Y axes are added, they are assigned default names formed by appending the axis's index at the end of the "YAxis#" string, i.e. "YAxis#0", "YAxis#1" and so on. When axes are reordered, default names change to reflect the new order; a persistent custom name can be assigned to each Y axis.
Orientation
Controls chart orientation: HORIZONTAL or VERTICAL. Chart orientation is the direction of its time axis for scrolling charts, or the direction of the X axis for XY Scatter charts. If the value of the attribute is changed, the position of other elements of the chart would need to be adjusted as well. The Real-Time Charts palette of the GLG editors provides pre-configured horizontal and vertical charts.

Note: In a chart with VERTICAL orientation, X and Y letters in resource names, attribute names and attribute value constants refer to the logical meaning and not to the actual X or Y direction. For example, in a VERTICAL chart, XAxis refers to the scrolling axis that is vertical. This makes it possible for an application to transparently access resources of HORIZONTAL and VERTICAL charts regardless of the setting of the chart's Orientation attribute.
Common Range
Controls whether or not the chart ranges are shared across the elements of the chart. If set to YES, all plots and level lines in the chart, as well as the first Y axis, share the same Low/High range. If set to NO, each plot and level line may have a different set of High/Low ranges.

When set to YES, the following attributes are also shared: the Low and High range of all chart's level lines and annotations, the RangeLock attribute of all objects in the chart, as well as the AutoScaleLow, AutoScaleHigh and AutoScaleDelta attributes of all chart's plots.
Auto Scroll (scrolling charts only)
Controls the automatic scrolling mode. If set to YES, every time a new sample is pushed into the chart, the chart will automatically scroll to accommodate the new sample at the end of the chart. If set to NO, the chart can be scrolled as needed by changing EndValue of its X axis.
Auto Scale
Controls the chart's automatic scaling and may have the following values:
DISABLED
Disables auto-scaling.
SCALE UP
Automatically adjusts the YHigh and YLow ranges of the plot and its linked axis when a newly pushed data sample is outside of the current Y range of the plot.
SCALE UP & DOWN
In addition to scaling up, it also automatically shrinks the YHigh and YLow ranges of the plot and its linked axis when the range of data in the chart buffer decreases. The AutoScaleLow and AutoScaleHigh plot attributes may be used to define limits for downscaling. Auto-scaling down consumes more CPU resources compared to auto-scaling up.
SCALE VISIBLE
This is the most CPU-intensive type of auto-scaling that adjusts YHigh and YLow ranges of the plot and its linked axis based on the data range of the visible portion of the chart. This setting automatically adjusts the range to ensure that the visible part of the chart is displayed using the full vertical extent of the chart area, which may result in excessive jumping when the chart scrolls. The AutoScaleLow, AutoScaleHigh and AutoScaleDelta plot attributes may be used to minimize jumping.
A plot's AutoScaleDelta attribute controls the amount to increase or decrease the range by for all autoscale types.
Draw Grid
Enables or disables the X and Y grid lines. Possible values are NONE, X, Y and XY.
Draw Cross-Hair
Enables or disables the cross-hair lines that follow the mouse when the mouse moves over the chart, can have the following values:
NONE
Disables the cross-hair cursor
X
Enables the X axis cross-hair cursor
Y
Enables the Y axis cross-hair cursor
XY
Enables both the horizontal and vertical cross-hair lines.
Tooltip Format
Specifies a custom format for a chart tooltip. The tooltip format can contain ordinary characters as well as conversion specifications. The conversion specifications contain a source keyword and a conversion format separated by the `:' character, and are surrounded with angle brackets. For example: "<plot_name:%s>".

Depending on the type of the conversion specification source, one of the following matching format types can be used:
double format: some variant of the "%f" format
string format: some variant of the "%s" format
time format: uses the same notation as the TimeFormat attribute described on page 140.
The following conversion specifications are supported:
plot_annotation
Replaced with the selected plot's annotation formatted with the supplied string format.
plot_name
Replaced with the selected plot's name formatted with the supplied string format.
plot_string
Replaced with the plot annotation of the selected plot, or with the plot name if the selected plot has no plot annotation. The final string is formatted with the supplied string format.
input_x
Replaced with the value corresponding to the cursor position on the X axis and formatted with the supplied double format. For charts with time axes, the value represents a number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
sample_x
Replaced with the time stamp or X value of the selected sample formatted with the supplied double format. For time stamps, the value represents a number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
input_x_string
input_x_text
Replaced with a string showing the time or X value corresponding to the cursor position on the X axis in the format of the X axis major tick labels. The final string is then formatted with the supplied string format. The input_x_string also removes any line breaks to form a single-line string.
sample_x_string
sample_x_text
Replaced with a string showing the time or X value of the selected sample in the format of the X axis's major tick labels. The final string is then formatted with the supplied string format. The sample_x_string also removes any line breaks to form a single-line string.
input_time
Replaced with a string showing the time or X value corresponding to the cursor position on the X axis in the format of the X axis tooltip. The final string is then formatted with the supplied string format.
sample_time
Replaced with a string showing the time or X value of the selected sample in the format of the X axis's tooltip. The final string is then formatted with the supplied string format.
input_x_time (time charts only)
Replaced with a string showing the time corresponding to the cursor position on the X axis formatted with the supplied time format.
sample_x_time (time charts only)
Replaced with a string showing the time stamp of the selected sample formatted with the supplied time format.
input_x_time_ms (time charts only)
Replaced with the value showing the number
of fractional seconds in the time corresponding to the cursor position on the X axis. It is formed by formatting the number of milliseconds with the supplied double format.
sample_x_time_ms (time charts only)
Replaced with the value showing the number
of fractional seconds in the time stamp of the selected sample. It is formed by formatting the number of milliseconds with the supplied double format.
input_y
Replaced with the Y value corresponding to the cursor position on the Y axis (in the Low/High range of the selected plot) and formatted with the supplied double format.
sample_y
Replaced with the Y value of the selected sample formatted with the supplied double format.
sample_valid
Replaced with the "yes" or "no" strings depending on the Valid flag of the selected sample. The final string is formatted with the supplied string format.
A chart's tooltip is activated by adding a tooltip action to the chart object using the Object, Add Tooltip menu option, setting the action's Tooltip property to "$ChartTooltip" and setting the ProcessMouse attribute of the chart's parent viewport to include the Tooltip mask. This is the default for all charts in the Real-Time Charts palette. The content of the chart's TooltipFormat attribute is then used to format the tooltip. If the value of TooltipFormat is not set, the following value is used as a default:
		<axis_string:%s> axis value= <axis_value_string:%s>
  
Edit Plots
A button in the Properties dialog for editing the chart's plots. It activates the Plot List dialog as well as the Properties dialog for the selected plot. A plot's Opacity attribute can be set to 1or 0 to turn individual plots on or off without losing accumulated samples.

The Plot List dialog has buttons for adding, deleting and reordering plots in the list. When plots are reordered, plots with default names (such as "Plot#0", "Plot#1", etc.) are assigned new default names that match their new position in the list. A persistent custom name can be assigned to each plot.
Edit X Axis
A button in the Properties dialog for editing properties of the chart's X axis. The AxisType attribute of the X axis determines the scrolling behavior of the chart: setting it to RANGE changes the chart type from a scrolling chart to the XY Scatter chart. The axis's Visibility attribute can be used to turn the X axis on or off.
Edit Y Axes
A button in the Properties dialog for editing the chart's Y axes. It activates the Y Axis List dialog as well as the Properties dialog for the selected Y axis. An axis's Visibility attribute can be used to turn individual Y axis on or off.

The Y Axis List dialog has buttons for adding, deleting and reordering axes in the list. When axes are reordered, axes with default names (such as "YAxis#0", "YAxis#1", etc.) are assigned new default names that match their new position in the list. A persistent custom name can be assigned to each Y axis.
Edit Background
A button in the Properties dialog for editing attributes of the chart's drawing area. To disable the background, set its FillType to NONE or set its Opacity to 0.
Edit Grid
A button in the Properties dialog for editing attributes of the chart's X and Y grid lines. Use the chart's DrawGrid attribute to enable or disable the grid.
Persistent
If set to PERSISTENT, the chart will keep the data accumulated in its plots when the chart is reset, or when the plots are deleted and then added to the chart again. The plot can be referenced to prevent it from being destroyed when it is deleted from the chart, so that it can be added to the chart again. The data will be deleted only when the chart or the plots are destroyed. If set to VOLATILE, the accumulated data will be deleted when the chart is reset; if a plot is deleted from the chart, the plot's data will be deleted right away as well.
Sort Input
If set to YES, the chart will find the proper insertion place for the new sample based on its time stamp to ensure that all time stamps are in the increasing order. It may be useful when data samples have time stamps, but some samples may be delayed in transmission and arrive out of sequence. If set to NO, the chart will always insert the new sample at the end.
Buffer X Span (scrollable charts only)
Controls the time span (in seconds) of the chart's data history buffer and is used to define a data buffer larger than the chart's visible span on the X axis. For example, if Span of a scrolling time chart is set to 600 and its BufferXSpan is set to 3600, the chart will show data for the last 10 minutes but will keep all samples for the last hour in the data buffer, allowing the user to scroll the chart. Samples older than one hour will be automatically discarded when the new samples come in.

If
BufferXSpan is set to 0 (default), the chart will maintain all samples visible in the chart's Span and will discard samples which scroll out and become invisible. This is equivalent to BufferXSpan having a value equal to the value of the chart's Span attribute.

If
BufferXSpan is set to -1, the chart will not discard samples based on their time stamp. The number of samples kept in the chart's buffer can still be controlled by the chart's BufferSize attribute.

The value of the attribute is ignored for non-scrollable XY Scatter charts.
For non-time based scrolling charts, BufferXSpan is defined in the units of the X axis.
Buffer Size
Controls the maximum number of samples per plot stored in the chart's data history buffer. When new samples are pushed into the chart and the size of the data buffer is exceeded, the oldest samples are discarded to maintain the requested maximum number of samples in the buffer.

The
BufferSize may be used to limit the size of the data buffer with or without BufferXSpan. For example, if the BufferXSpan is set to 3600 to keep all samples for the last hour, the number of data samples in the buffer may exceed 3600 if new samples are pushed into the chart faster than once per second. BufferSize may be set to, let's say, 7200 to limit the maximum number of samples kept in the buffer.

If
BufferSize is set to 0, the chart will not limit the maximum number of samples in the data buffer, and the number of samples in the buffer will be limited only by the settings of the BufferXSpan attribute. If BufferSize set to 0 and BufferXSpan is set to -1, the data buffer will accumulate an unlimited number of samples, which can cause an application to run out of memory and should be used with caution.

The samples accumulated in the chart's data buffer are discarded when the chart is reset. To discard the samples accumulated in the chart's data buffer at run time without resetting the whole chart, an application can set BufferSize to -1 and invoke the GlgUpdate or GlgSetupHierarchy methods to flush the buffer, then set BufferSize to a previous or new value.
Y Axes Offset
Specifies an offset used for the layout of multiple Y axes. A negative value defines a pixel offset between the Y axes. A positive value defines an absolute pixel width used by each Y axis. If an axis's width exceeds this positive value, it may overlap the neighboring Y axis.

A negative value defining a pixel offset between the axes may be used to let the chart automatically lay out Y axes. However, it may cause a "jumping" effect if the change of the axis's ranges changes its labels, which in turn changes the width of the axis's box and cause other axes to move. To avoid this effect, an absolute axis width may be specified using a positive value.
Tooltip Mode
Specifies the sample selection priority when processing the chart tooltip or processing a chart selection via an API method. Possible values are:
NONE
Disables chart tooltips
X
Selects the data sample closest to the cursor in the direction of the X axis.
XY
Selects the data sample with the minimal distance from the cursor.
Note: The setting of the GlgTooltipEraseDistance global configuration resource affects tooltip selectivity: the new tooltip will be displayed only if the mouse moves by a distance that exceeds the tooltip erase distance (see page 424). The erase distance can be set to 1 for precise tooltip selection.
Draw Order
Defines the drawing order of the chart's elements, can have the following values:
Grid,Edge,Plot
Grid,Plot,Edge
Edge,Plot,Grid
Plot,Grid,Edge
The Edge refers to the outline of the chart's drawing area. For example, using the default Grid,Plot,Edge setting will draw the grid first, draw plot lines on top of the grid and then draw the outline on top of the plot lines. The chart's Level and TimeLine objects have their own DrawOrder attribute that controls if they are drawn before or after chart's plots.

The above DrawOrder values are shown in the Graphics Builder. The GlgChartElemDrawOrder enum contains corresponding bit masks that can be used to set the value of the attribute via the GlgSetDResource method of the GLG API.
Edit CrossHair Lines
A button in the Properties dialog for editing attributes of the chart's cross-hair cursor.
Edit SelectionMarker
A button in the Properties dialog for editing attributes of the Marker object used to annotate the selected data sample. The marker is displayed at the selected data sample when the sample is selected via the API call or by displaying a tooltip. Use the marker's Visibility attribute to enable or disable the display of the selection marker.
Levels & Annotations
A button in the Properties dialog for editing attributes of the chart's time lines, levels and annotations.
Number of Levels
Specifies a number of horizontal level lines in the chart. A level line object annotates a chart threshold by drawing a horizontal line at a specified height. The chart automatically adds or deletes level lines when the value of the attribute is changed.

When new level lines are added, they are assigned default names formed by appending the level's index at the end of the "Level#" string, i.e. "Level#0", "Level#1" and so on. When level lines are reordered, default names change to reflect the new order; a persistent custom name can be assigned to each level line. See the Level Line section on page 133 for more information.
Number of Time Lines
Specifies a number of vertical time lines in the chart. A time line object annotates a time stamp by drawing a vertical line at a specified time value. There are two modes of operation that are controlled by the value of this attribute:
If the value of the attribute is greater or equal to zero, it controls the number of persistent time lines in the chart. The chart automatically adds or deletes time lines when the value of the attribute is changed. When new time lines are added, they are assigned default names formed by appending the line's index at the end of the "TimeLine#" string, i.e. "TimeLine#0", "TimeLine#1" and so on. When time lines are reordered in the list, default names change to reflect the new order; a persistent custom name can be assigned to each time line. The Level attribute of each time line defines its position on the time axis and may be set to the time stamp of the event that needs to be annotated.
If the value of the attribute is set to -1, time lines can be added via the
GlgAddTimeLine API method at run time. Added time lines are automatically deleted when the data sample closest to the time line falls out from the history buffer (due to the settings of the chart's BufferSize or BufferXSpan attribute). The GlgDeleteTimeLine method can also be used to delete individual time lines.

See the Level Line section on page 133 for more information.
Number of Annotations
Specifies a number of chart annotations. An annotation object may be used to draw a custom annotation containing a text label with or without a marker at a specified position in the chart. It may be used to annotate a time line, a level line, or a data sample.

There are two modes of operation that are controlled by the value of this attribute:
If the value of the attribute is greater or equal to zero, it controls the number of persistent annotations in the chart. The chart automatically adds or deletes annotations when the value of the attribute is changed. When new annotations are added, they are assigned default names formed by appending the line's index at the end of the "Annotation#" string, i.e. "Annotation#0", "Annotation#1" and so on. When annotations are reordered in the list, default names change to reflect the new order; a persistent custom name can be assigned to each annotation. The Position X and Position Y attributes of each annotation define its position, and the Absolute X and Absolute Y attributes specify how to interpret the position values.
If the value of the attribute is set to -1, annotations can be added via the
GlgAddAnnotation API method at run time. Added annotations with AbsoluteX=NO are automatically deleted when the data sample closest to the annotation falls out from the history buffer (due to the settings of the chart's BufferSize or BufferXSpan attribute). The GlgDeleteAnnotation method can also be used to delete individual annotations.

See the Annotation section on page 135 for more information.
Edit Level Lines
A button in the Properties dialog for editing the chart's level lines. It activates the Level Line List dialog as well as the Properties dialog for the selected level line. A level line's Level attribute controls the level line's position, and its Enabled attribute can be set to 1 or 0 to turn the level line on or off. See the Level Line section on page 133 for more information.

The Level Line List dialog has buttons for adding, deleting and reordering level lines in the list. When level lines are reordered, level lines with default names (such as "Level#0", "Level#1", etc.) are assigned new default names that match their new position in the list. A persistent custom name can be assigned to each level line.
Edit Time Lines
A button in the Properties dialog for editing the chart's time lines. It activates the Time Line List dialog as well as the Properties dialog for the selected time line. A time line's Level attribute controls the time line's position, and its Enabled attribute can be set to 1 or 0 to turn the time line on or off. See the Level Line section on page 133 for more information.

The Time Line List dialog has buttons for adding, deleting and reordering time lines in the list. When time lines are reordered, time lines with default names (such as "TimeLine#0", "TimeLine#1", etc.) are assigned new default names that match their new position in the list. A persistent custom name can be assigned to each time line.
Edit Annotations
A button in the Properties dialog for editing the chart's annotations. It activates the Annotation List dialog as well as the Properties dialog for the selected annotation. An annotation's Position X, Position Y, Absolute X and Absolute Y attributes control the annotation's position, and its Enabled attribute can be set to 1 or 0 to turn the annotation on or off. See the Annotation section on page 135 for more information.

The Annotation List dialog has buttons for adding, deleting and reordering annotations in the list. When annotations are reordered, annotations with default names (such as "Annotation#0", "Annotation#1", etc.) are assigned new default names that match their new position in the list. A persistent custom name can be assigned to each annotation.

Charts with a time axis set the axis' EndValue attribute to an initial value depending on the axis type at the hierarchy setup time. For time axes that show LOCAL or UTC time, EndValue is initialized to the current time. For relative time axes, both the EndValue and TimeOrigin attributes of the axis are initialized to the current time.

The chart can be zoomed and scrolled in the X direction by setting the Span and EndValue attributes of its X axis. Zooming and panning in the Y direction is done by changing the Y ranges of the chart's plots and Y axes.

The GlgSetZoom function provides a simplified interface to the integrated zooming and scrolling in the Chart Zoom Mode, which is the default for charts in the Real-Time Charts palette. Refer to the GlgSetZoom section on page 96 of the GLG Programming Reference Manual for details.

The chart can also be scrolled using integrated scrollbars. The scrollbars are activated by setting the Pan attribute of the chart's parent viewport, see page 84.

All charts in the RealTime Charts palette have chart tooltips enabled. The chart tooltips display information about the data sample selected by the current cursor position. The type of the information displayed in the tooltips is defined by the chart's TooltipFormat attribute. The TooltipMode attribute controls the criterion for the data sample selection.

The chart generates messages when its cross-hair cursor is drawn or erased, see the Chart Message Object section on page 459 of the GLG Programming Reference Manual.

Plot

The Plot object is used to render individual lines in a chart. A required number of plot objects is automatically created by the parent chart. A plot object does not have any control points, since its geometry is completely defined by its parent chart. A plot object has the following attributes:

Plot Type
Defines the type of the graphics used to visualize the plot's data, can have the following values:
GLG_LINE_PLOT
GLG_STEP_PLOT
GLG_MARKERS_PLOT
GLG_LINE_AND_MARKERS_PLOT
GLG_STEP_AND_MARKERS_PLOT
GLG_BAR_PLOT
GLG_FLOATING_BAR_PLOT
In the GLG editors' Properties dialog, the line and step plot type are displayed as LINE OR FILLED LINE and STEP OR FILLED STEP. The plot fill type is defined by the FillType attribute of the plot's LineAttributes object, which also defines the plot's transparency via the Opacity attribute. The plot's LineAttributes object may be accessed via the Edit Line or Bar button in the plot's Properties dialog.

While a bar plot displays bars that start at the bottom of the chart, the bars in a floating bar plot start at the level defined by the plot's BarYLow attribute. If the plot's ExtendedData is set to YES, each floating bar can start at a different level supplied by the BarYLow attribute.
Plot Annotation
Specifies a label used to annotate the plot in a chart's legend.
Enabled
Enables or disables the plot. Disabled plots are not shown in a chart, but still keep data in their history buffers and accept new data samples, to be shown when the plot is enabled again.
Y Low
The low range of the plot. If the chart's CommonRange is set to YES, the range is shared by all plots in the chart.
Y High
The high range of the plot. If the chart's CommonRange is set to YES, the range is shared by all plots in the chart.
Value Entry Point
An entry point for supplying Y values for the plot's samples. The value must be supplied for each data sample pushed into the plot.
Time Entry Point
An entry point for supplying Time or X values for the plot's samples. These values define samples' placement in the horizontal direction. In scrolling charts with AutoScroll=YES, pushing a value into the time entry point also scrolls the chart horizontally to display the new data sample.
In charts with the ABSOLUTE TIME SCROLL horizontal axis, the entry point is used to push time stamps for the chart's samples. Supplying a time stamp is optional. If a time stamp is not supplied, the chart automatically generates a time stamp using the current time. A time stamp is supplied in the format of POSIX time (a number of seconds since midnight, January 1, 1970). Fractional values may be used to supply exact high-precision time stamps.
In charts with the RELATIVE TIME SCROLL horizontal axis, the entry point is used the same way, but the axis labels display the time elapsed since the moment defined by the TimeOrigin attribute of the axis.
In charts with the VALUE SCROLL horizontal axis, values pushed into the entry point are used to position data samples based on an arbitrary numerical value other than time.
In charts with the INDEX SCROLL horizontal axis, an application should not push values into the entry point since it is automatically filled with an incrementing sample index: 0, 1, 2 and so on.
In XY Scatter charts with the RANGE horizontal axis, the entry point is used to push X values of XY plots.
Valid Entry Point
An entry point for supplying a sample's VALID attribute (0 or 1). If it is not supplied, the value of 1 is used, making the sample valid by default.
AutoScale Delta
Enables auto-scaling of the plot if set to a non-zero value. Depending on the type of auto-scaling enabled by the chart's AutoScale attribute, the plot's range is automatically extended by an integer number of the AutoScale Delta intervals to accommodate out-of-range data, or shrunk when the data range decreases. If the attribute is set to a negative value, it defines the adjustment delta as a fraction of the current plot range. For example, for a value of 0.15, 15% of the plot range will be used as an adjustment interval.
The Linked Y Axis attribute of the plot may be used to link the plot with an axis, so that the axis range is adjusted synchronously with the plot when the plot is auto-scaled.
AutoScale Low
AutoScale High
These attributes limit auto-scaling and define the minimum and the maximum range which is always shown regardless of the actual data range. For example, AutoScaleLow may be set to 0 to always start the Y axis at 0 even if the minimum data value is greater than zero.
If AutoScaleHigh = 100, autoscaling will not shrink Y axis high value below 100 even if the maximum data value does not reach 100. If AutoScaleLow is bigger or equal than AutoScaleHigh, auto-scaling will be performed with no limits.
Linked Y Axis
This button is used in the Graphics Builder to associate the plot with a specific Y axis in a chart with multiple Y axes and CommonRange set to NO. When the plot range is changed, the range of the associated axis will also change to display the same range, and vice versa. The text box next to the button shows the label string of the associated Y axis.
The GlgSetLinkedAxis method of the GLG API may be used at run time to associate a plot with an axis programmatically.
Filter Type
Specifies the type of a filter to be used for plots with large number of data points. For example, when a plot shows 50000 data samples on a display that has only 1000 pixels in width, the plot will render 50 points per each pixel in the horizontal direction. In this case, a filter may be used to combine the values of the data samples that fall within the same pixel into a single data sample (or two data-samples for the MIN_MAX filter). Using a filter increases performance and decreases the CPU load by decreasing the number of plot segments and markers that need to be rendered. The following filter types are supported:
NONE
Disables data filtering to draw all data samples.
MIN_MAX
Combines multiple data samples into two data samples that hold the minimum and maximum values of the combined samples.
AVERAGE
Combines multiple data samples into a single data sample by averaging the values of the combined samples.
DISCARD
Plots the first encountered data sample, discarding any other samples that fall onto the same pixel in the horizontal direction.
BAR_MIN_MAX
For floating bar plots with ExtendedData=YES, combines multiple data samples into a single floating bar sample that shows the highest Y value and the lowest BarYLow value. For the rest of the charts, the filter behaves as a MIN_MAX filter.
CUSTOM
Allows the use of custom filters. A custom chart filter can be added to a plot via the GlgSetChartFilter GLG API method. Examples of the custom filter code for various programming environments are provided in the src subdirectory of the GLG installation. The examples demonstrate the implementation of the above filter types and may be modified to fine-tune filter behavior to suit the application requirements.
Filter Precision
A positive value specifies the horizontal interval in pixels for combining multiple data samples. The default is 2 pixels, which will cause all data samples in each 2 pixel interval to be combined in one or two data samples depending on the filter type. If a negative value is specified, its absolute value defines filter interval in the units of the X axis, i.e. in seconds for charts with a time X axis.
Filter Markers
If set to NO, disables filtering for data samples with markers. It may be used to let data samples with markers through for plots which use markers to annotate special events.
If a data sample with a marker is encountered, the data samples for the currently accumulated filter interval are flushed to draw the combined data sample(s), the data sample with a marker is drawn, and then the next filter interval is started.
If FilterMarkers=YES, the combined data sample(s) representing the output of the filter for this filter interval will show a marker if any data samples in the interval had a marker.
Include Zero
If set to YES, the plot's range queries always include 0 in the plot's range. For example, if a plot contains data samples in the range [20;100], the range will be reported as [0;100]. If the Y scrollbar is activated, it will scroll the plot from 0 to 100, instead of the [20;100] range. Resetting the chart's Y range via integrated zooming will reset the range to [0;100] as well.
For floating bar plots with ExtendedData=NO, the value of the plot's BarYLow attribute is used instead of 0 when IncludeZero= YES.
Extended Data
The ExtendedData attribute control the amount of information stored for each data sample. Storing an extended set of attributes is stored for each data sample makes it possible to annotate bars and markers in a chart with different colors, marker sizes or marker types.
If ExtendedData is set to NO, the datasamples stored by the plot in the GlgDataSample structure contain only limited information about each sample, such as its value, time stamp, sample validity and marker visibility. This minimizes memory consumption and optimizes update performance for plots with large number of data samples. The rest of the attributes, such as a bar fill color or a marker size, are global and used to render all data samples using the current attribute values. If an attribute value (such as a bar FillColor) is changed, all data samples will be redrawn with the new attribute value.
If ExtendedData is set to YES, the plot uses the GlgDataSampleExt structure to keep extended information for each data sample, such as edge color, fill color, marker type and marker size for plots with markers, or edge color, fill color, fill type, line width and bar width for bar plots. For floating bar plots, the BarYLow value is also stored.
If ExtendedData=YES, the marker and plot attributes listed above serve as entry points for supplying attributes to draw each sample. This may be used to draw markers and bars in different colors, and also to supply a different BarYLow value for each floating bar of a floating bar plot. If some attribute values are not supplied for some data samples, the last supplied values for these attributes will be used.
If transformations are attached to the bar attributes, attribute values can be supplied by setting the controlling parameter of each transformation. Transformations are not supported for marker attributes (other than marker visibility) in the extended data mode.
The value of the ExtendedData attribute can be changed to YES on the fly and then restored back to NO to provide extended data for only some data samples.
Cache Use
Controls the use of a datasample cache. Scrolling charts with large number of data samples need to access data samples in memory, making applications that use them memory-bound. Performance of such applications depends on the data samples memory layout: if adjacent data samples are located in continuous memory locations, it will minimize memory cache misses and will increase scrolling performance.

When an application uses multiple scrolling charts with a large number of datasamples updating in random order, it may cause data samples mixing up in memory. When the chart data buffer fills up, pushing a new data sample into the chart will cause a data sample at the other end of the buffer to fall out. Depending on the order in which charts are updated, data samples that are pushed out from one chart may be used in another chart. This will result in data samples in a chart being placed in non-continuous memory locations.

In a long-running application with multiple charts, the memory mix up will gradually increase, causing a lot of cache misses and resulting in gradual performance degradation over time, which is unacceptable in real-time applications. This effect is the most noticeable in C/C++ applications.

A chart data sample cache provides a solution by keeping data samples that fall out of a chart plot in a plot cache, to be used in the same plot when new data samples will be pushed in. A per-plot cache is implemented as a FIFO queue, which preserves the relative order of datasamples in a chart, minimizing memory cache misses and preventing performance degradation over time.

The attribute may be set to DISABLED for charts that display a small amount of data and/or are not continuously scrolled for a long time. Otherwise, it may be set to PREALLOCATED, which prefills a cache with data samples on start-up depending on the chart's buffer size (which must be set to a positive value), and places all data samples that fall out from the plot in the cache. The ENABLED setting is a compromise: the cache is not pre-allocated, but the data samples that fall out of the plot are still stored in the cache for reuse.

The GlgChartCacheUse global configuration resource or the corresponding environment variable described on page 426 of the GLG Programming Reference Manual may be used to provide a global cache setting for all application's charts, which will override the plots' CacheUse attribute setting. This provides a convenient way to test application performance with and without a cache.

The GlgChartCacheExtraSamples global configuration resource or the corresponding environment variable described on page 426 of the GLG Programming Reference Manual may be used to define a number of extra data samples created when a cache is prefilled. This number should be greater than the number of data samples pushed into each individual plot between GlgUpdate invocations used to display the changes. The size of the preallocated cache will be equal to the chart's buffer size plus the number of extra data samples.

When pre-filling charts that use chart cache, the GlgCreateDataSampleNode and GlgAddDataSampleNode methods should be used instead of the deprecated GlgAddDataSample methods. If a chart plot is provided as a parameter of the GlgCreateDataSampleNode method, the method will return a data sample node from a plot cache (if any).
Range Lock
If set to YES, prevents the plot's range from being changed when the chart is zoomed or scrolled in the vertical direction. It may be used for locking plots that display boolean ON/OFF data, so that other plots in a chart can be zoomed and scrolled in Y direction while the locked plot does not change its vertical scale and location. This makes it possible to zoom and scroll other plots vertically and view them in the context of the boolean ON/OFF data, as shown in the GLG Real-Time Strip-Chart demo.
Bar Y Low
Specifies the level of the lower edge of floating bars in the floating bar plot. If the Y value of a floating bar is less than the value of BarYLow, the bar will extend downwards from the BarYLow level.
If ExtendedData=NO, the lower edge of all floating bars starts at the level corresponding to the BarYLow value. If ExtendedData=YES, the BarYLow attribute serves as an entry point for supplying a different lower edge value for each floating bar of the floating bar plot.
Bar Width
Bar width in pixels for bar plots.
Number of Samples
A read-only attribute containing the number of samples accumulated in the plot. When the chart is reset, the samples are discarded and the number of samples is reset to 0.
Edit Line or Bar
A button in the Properties dialog to access a Line Attributes object that defines rendering attributes (such as EdgeColor, FillColor, FillType, LineWidth, etc.) for line and bar plots. Only applicable attributes are displayed depending on the plot type (line or bar). These attributes are inherited by the plot object and are visible as resources of the plot in the resource browser.
If ExtendedData=YES for a bar plot, the attributes (except for Opacity and AntiAliasing) can be used as entry points for supplying different attribute values for each bar in the plot.
Edit Marker
A button in the Properties dialog to access a marker object that defines rendering attributes of the plot's markers. The marker's Visibility attribute may be used as an entry point to switch visibility of individual markers on or off by supplying 0 or 1 Visibility values for each data sample to annotate selected data samples with markers. If the Visibility value is not supplied, the current value of the attribute will be stored as the marker visibility of the data sample.
If ExtendedData=YES for a plot with markers, the attributes (except for AntiAliasing and Rendering Attributes) can be used as entry points for supplying different attribute values for each marker in the plot.
Array
A resource of a plot that provides programmatic access to the list of data samples in the plot's history buffer. This attribute is not visible in the Builder, but can be used in a program via the GLG API. The GlgRTChartMarkers coding example provides an example of using this resource to toggle marker visibility of the data sample selected with the mouse.

A data sample value pushed into one of the entry points (for example, a value entry point) is buffered in order to wait for data to be supplied for other entry points, such as time or valid entry points. The buffered data sample is flushed and added to the plot when either the GlgUpdate or GlgSetupHierarchy method is called, or when data is repeatedly pushed into an entry point which already contains a previously buffered value.

To add a single sample to a plot, push a value into the ValueEntryPoint with the GlgSetDResource method, push values into the TimeEntryPoint and ValidEntryPoint if necessary, then invoke the GlgUpdate method to update the drawing. If ExtendedData=YES, additional attributes for rendering each data sample may be provided, refer to the Extended Data description above.

To add multiple samples (for example, when filling the whole chart with data), an application can repeatedly push values into the entry points and invoke the GlgUpdate method once at the end.

A plot can be erased without losing the accumulated data points by setting the value of its Enabled attribute to 0. To display the plot again, restore the attribute value to 1.

Level Line

Objects of type LEVEL LINE are used in charts to draw either horizontal or vertical lines that annotate thresholds or time stamps. A Level Line is a horizontal LEVEL LINE object that annotates a chart threshold by drawing a horizontal line at a specified height. A vertical version of the LEVEL LINE object is called a Time Line and is used to annotate a time stamp by drawing a vertical line at a specified time value. A band version of levels and time lines renders two lines with filled area between the lines.

A required number of Level Lines and persistent Time Lines is automatically created by the parent chart based on the values of the chart's Number of Levels and Number of Time Lines attributes. Dynamic time lines can also be added to a chart via the GlgAddTimeLine API method if Number of Time Lines is set to -1. A level line does not have any control points, since its geometry is completely defined by its parent chart. A level line object inherits LineAttributes such as EdgeColor, LineType, LineWidth, Opacity and AntiAliasing.

Level lines have the following attributes:

Level Type
Specifies the level type: LINE or AREA. AREA levels are rendered as bands containing two level lines with a filled area between the lines.
Draw Order
Specifies the level draw order: IN FRONT OF PLOT, BEHIND PLOT or SPLIT. The SPLIT value renders the level line in front of the plots, while the filled area of AREA plots is rendered behind the plots.
Level
Specifies the level of the horizontal level line, or the time stamp of the vertical time line.
Level End
Specifies the position of the second line for AREA-style level lines and time lines.
Y Low (horizontal level line only)
The low range of the level line. If the chart's CommonRange is set to YES, the range is shared with the chart's plots.
Y High (horizontal level line only)
The high range of the level line. If the chart's CommonRange is set to YES, the range is shared with the chart's plots.
Enabled
Enables or disables the display of the level line.
Range Lock (horizontal level line only)
If set to YES, prevents the level line's range from being changed when the chart is zoomed or scrolled. It may be used for locking the vertical position of level lines corresponding to the locked plots that display boolean data. If a level line is locked, its position does not change when the chart is scrolled or zoomed in the Y direction.
Linked Y Axis (horizontal level line only)
This button is used in the Graphics Builder to associate the level with a specified Y axis in a chart with multiple Y axes and CommonRange set to NO. The range of the level line will be automatically changed to correspond to the range of the associated Y axis when the range of the axis changes, and vice versa. The text box next to the button shows the label string of the associated Y axis.

The GlgSetLinkedAxis method of the GLG API may be used at run time to associate a level line with a Y axis programmatically.
Edit Line and Area
A button in the Properties dialog to access a Line Attributes object (described in the Line Attributes section on page 159) that defines rendering attributes (such as EdgeColor, FillColor, FillType, LineWidth, etc.) for line and bar plots. Only applicable attributes are displayed depending on the level type (line or area).

Line attributes of level lines and time lines can be reused as described in the Line Attributes section on page 160.

Annotation

The Annotation object is used to draw a custom annotation containing a text label with or without a marker at a specified position in the chart. It may be used to annotate a vertical time line, a horizontal level line, or a data sample.

A required number of persistent annotation objects is automatically created by the parent plot based on the value of the Number of Annotations attribute. Dynamic annotations can also be added to a plot via the GlgAddTimeLine API method if Number of Annotations is set to -1. The PositionX, PositionY, AbsoluteX and AbsoluteY attributes define position of the annotation's text and marker objects.

The annotation object has the following attributes:

Enabled
Enables or disables the display of the annotation.
AnnotationType
Defines the annotation type and may have the following values:
LABEL
MARKER
LABEL & MARKER
Absolute X
Defines the way the value of the Position X attribute is interpreted. If set to NO, the value is interpreted as a time stamp for charts with the Time X axis, or as an X value for charts with the Value X axis. In both cases, the annotation will move with the chart when it is scrolled or zoomed.

If set to YES, the value of the Position X attribute is interpreted as an absolute position within the chart in the range from 0 (left edge) to 1 (right edge), and the annotation position will not change when the chart is scrolled or zoomed. This may be used to add a text annotation to the chart's level lines at a fixed X position within the chart.
Absolute Y
Defines the way the value of the Position Y attribute is interpreted. If set to NO, the value is interpreted as the annotation's Y position in the range specified by the Y Low and Y High attributes, and the annotation will move with the chart when the range is changed or the chart is zoomed.

If set to YES, the value of the Position Y attribute is interpreted as an absolute position within the chart in the range from 0 (bottom edge) to 1 (top edge), and the annotation position will not depend on the range and will not change when the chart is zoomed. This may be used to add a text annotation to the chart's time lines at a fixed Y position within the chart.
Position X
Specifies the annotation's position relatively to the X axis.
Position Y
Specifies the annotation's position relatively to the Y axis.
Y Low
The low range of the annotation. If the chart's CommonRange is set to YES, the range is shared with the chart's plots.
Y High
The high range of the annotation. If the chart's CommonRange is set to YES, the range is shared with the chart's plots.
Range Lock
If set to YES, prevents the annotation's range from being changed when the chart is zoomed or scrolled. It may be used for locking the vertical position of annotations corresponding to the locked plots that display boolean data. If a level line is locked, its position does not change when the chart is scrolled or zoomed in the Y direction.
Linked Y Axis
This button is used in the Graphics Builder to associate the annotation range with a specified Y axis in a chart with multiple Y axes and CommonRange set to NO. The range of the annotation will be automatically changed to correspond to the range of the associated Y axis when the range of the axis changes, and vice versa. The text box next to the button shows the label string of the associated Y axis.

The GlgSetLinkedAxis method of the GLG API may be used at run time to associate a annotation with a Y axis programmatically.
Label Format
The format used to form the text string shown as an annotation's label. Similar to the chart's Tooltip Format, label format can contain ordinary characters as well as conversion specifications. The conversion specifications contain a source keyword and a conversion format separated by the `:' character, and are surrounded with angle brackets. For example: "<sample_time:%s>".

Depending on the type of the conversion specification source, one of the following matching format types can be used:
double format: some variant of the "%f" format
string format: some variant of the "%s" format
time format: uses the same notation as the TimeFormat attribute described on page 140.
The following conversion specifications are supported:
sample_x
Replaced with the time stamp or the X value supplied by the Position X attribute and formatted with the specified double format. For a time stamp, the value represents a number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
sample_time
Replaced with a string showing the time or X value of the Position X attribute in the format of the X axis's tooltip. The final string is then formatted with the supplied string format.
sample_x_time (time charts only)
Replaced with a string showing the time stamp of the
Position X attribute formatted with the supplied time format.
sample_x_time_ms (time charts only)
Replaced with the value showing the number
of fractional seconds in the Position X attribute. It is formed by formatting the number of milliseconds with the supplied double format.
sample_y
Replaced with the Y value of the Position Y attribute formatted with the supplied double format.

If no label format is specified, the TextString attribute of the annotation's text object will be displayed as a label.
Edit Label
A button in the Properties dialog for editing properties of the text object used to render the annotation's label. It activates the Properties dialog for the annotation's text object.
Edit Marker
A button in the Properties dialog for editing properties of the marker object used to render the annotation's marker. It activates the Properties dialog for the annotation's marker object.

Axis

The Axis object is used by a chart to draw X and Y axes. It may also be used as a stand-alone axis or ruler object. An axis object is defined by two points. For an axis that is a part of a Chart object, the axis's points are controlled by the chart and positioned in the diagonal corners of the chart's data area. The Visibility attribute of an integrated chart axis can be used to turn individual axes on or off.

An axis object supports integrated tooltips that can be used to display an axis value corresponding to the current mouse position. The content of the tooltip string is controlled by the axis's TooltipFormat attribute.

Axis attributes depend on the type of the axis: some attributes are common for all axis types, and other attributes are specific for a chosen axis type. In the Builder, the Properties dialog displays only the attributes applicable to the selected axis type. The following lists all attributes of the axis object:

Axis Type
Defines the type of the axis. The type is a combination of several constants that define the axis behavior:
RULER
Controls scaling of the axis's tick intervals. A ruler axis positions its minor and major ticks at pixel coordinates. When the length of the axis is increased or decreased, the axis keeps the pixel length of tick intervals constant and changes its displayed span to show a bigger or smaller number of ticks. The RulerStart and RulerScale attributes control the origin and the scale of the ruler.
If the RULER modifier is not present and the axis's length is increased or decreased, the axis preserves the visible span and proportionally changes the pixel length of tick intervals to maintain the number of displayed ticks constant.
RANGE
Defines a value axis controlled by the Low and High attributes.
SCROLL
Defines a scrollable axis with a visible span controlled by the EndValue and Span attributes.
TIME, VALUE or INDEX modifiers
Specify an interpretation and formatting of the values displayed in the scrolling axis's labels. Depending on the used modifier, the values are interpreted and displayed as either a time stamp, a double value or an integer sample index.
LOCAL, UTC or RELATIVE
Modify behavior of a scrolling time axis to display either an absolute date and time (LOCAL or UTC), or a time interval elapsed since the time specified by the TimeOrigin attribute (RELATIVE).
CENTER modifier
Controls positioning of the axis's major and minor ticks. If present, ticks are positioned in the middle of the tick intervals as opposed to being positioned at the end of each tick interval.
The actual axis type is a combination of the constants listed above. The following demonstrates a few common examples:
An ABSOLUTE TIME SCROLL axis type defines a scrolling time axis that displays a span of time defined by the Span attribute. The end position of the displayed time span is controlled by the EndValue attribute.
An ABSOLUTE TIME RULER SCROLL axis type defines a scrolling time axis that displays ticks and labels at fixed pixel intervals regardless of the axis's length. The RulerScale attribute controls the seconds-to-pixels mapping. For example, if RulerScale=1, each pixel will correspond to one second. If RulerScale=5, the length of one second interval will be 5 pixels.
A RANGE axis type defines a value axis with a range supplied by the Low and High attributes; this axis type is used for the Y axes of a chart.
A RULER axis type defines a ruler. The RulerScale attribute defines the ruler's unit-to-pixel mapping. If RulerScale is set to the DPI (Dots Per Inch) value of the monitor and the axis's MajorInterval=1, the axis will display major ticks at 1-inch intervals.
Axis Position
Specifies the axis placement relatively to a rectangle defined by the axis's two control points and may have the following values:
HTOP UP
HTOP_DOWN
A horizontal axis is positioned along the top edge of the rectangle defined by the control points, with ticks drawn in the direction specified by the UP or DOWN keyword.
HCENTER UP
HCENTER DOWN
A horizontal axis is positioned in the center of the rectangle defined by the control points, with ticks drawn in the direction specified by the UP or DOWN keyword.
HBOTTOM UP
HBOTTOM DOWN
A horizontal axis is positioned along the bottom edge of the rectangle defined by the control points, with ticks drawn in the direction specified by the UP or DOWN keyword.
VLEFT LEFT
VLEFT RIGHT
A vertical axis is positioned along the left edge of the rectangle defined by the control points, with ticks drawn in the direction specified by the trailing LEFT or RIGHT keyword.
VCENTER LEFT
VCENTER RIGHT
A vertical axis is positioned in the center of the rectangle defined by the control points, with ticks drawn in the direction specified by the trailing LEFT or RIGHT keyword.
VRIGHT LEFT
VRIGHT RIGHT
A vertical axis is positioned along the right edge of the rectangle defined by the control points, with ticks drawn in the direction specified by the trailing LEFT or RIGHT keyword.
When a chart's X or Y axis is edited in the Builder, only the options applicable to the selected axis type are included in the menus for editing the axis's position.
Inversed
If set to YES, inverts the axis direction. The default direction is left to right for a horizontal axis, and bottom to top for a vertical axis.
Draw Outline
Controls the drawing of auxiliary decorations, can have the following values:
NO_OUTLINE
No additional decorations are drawn.
AXIS_LINE
A line is drawn along the axis.
BOX_MINOR
Draws a box around minor ticks.
BOX_MAJOR
Draws a box around major ticks.
BOX_ALL
Same as BOX_MAJOR and BOX_MINOR used together.
LINE_MINOR
Draws a line along the outer ends of minor ticks.
LINE_MAJOR
Draws a line along the outer ends of major ticks.
LINE_ALL
Same as LINE_MAJOR and LINE_MINOR done together.
FillType and FillColor of the Ticks and Outline attributes may be used to draw filled outline boxes.
End Value (scrollable axes only)
Defines the value that corresponds to the end of a scrolling axis. An axis is scrolled by dynamically changing the value of this attribute. For the time axis, EndValue is set to an initial value depending on the axis type at the hierarchy setup time. For time axes that show LOCAL or UTC time, EndValue is initialized to the current time. For relative time axes used in a chart, both the EndValue and TimeOrigin attributes are initialized to the current time.
Span (scrollable axes only)
Defines the extent (in axis units) from the beginning of the axis to its end. For example, setting Span=60 for a chart's time axis will display 60 seconds worth of data, ending with the time specified by the EndValue attribute.
Low (range axes only)
Specifies the value corresponding to the axis start.
High (range axes only)
Specifies the value corresponding to the axis end.
Ruler Start (ruler axes only)
Specifies the value corresponding to the axis start.
Ruler Scale (ruler axes only)
Defines a scale factor for unit-to-pixel mapping. For example, if RulerScale=10, one unit of the ruler will be mapped to 10 pixel. To display an inch ruler, set RulerScale to the value of the monitor's DPI (Dots Per Inch). To display a metric centimeter ruler, set RulerScale to the value of the monitor's DPI divided by 2.54.
Time Format (time axis only)
Specifies a format for displaying time labels. The format string follows the convention of the POSIX strftime function and can contain ordinary characters as well as conversion specifications. The conversion specifications are two character sequences that start with the `%' character and are replaced by formatted time and date strings as described below.

The conversion specifications listed below are universally supported across Windows, Linux/Unix, Java, C#/.NET and JavaScript environments.
Escape sequences may be used to define native platform-specific formats for Windows and Unix platforms, as well as Java and C#/.NET environment, as described in the Scalar Formatting (Format D) section on page 183.
Some conversion specifications may not be supported on Unix platforms other than Linux, such as Solaris, HPUX, AIX, etc. Refer to the manual page of the native strftime function for information on the supported conversion specifications for these Unix platforms.
%a
The abbreviated weekday name according to the current locale.
%A
The full weekday name according to the current locale.
%b
The abbreviated month name according to the current locale.
%B
The full month name according to the current locale.
%c
The preferred date and time representation for the current locale.
%d
The day of the month as a decimal number (range 01 to 31).
%D
Equivalent to %m/%d/%y.
%e
Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space.
%F
Equivalent to %Y-%m-%d.
%h
Equivalent to %b.
%H
The hour as a decimal number using a 24-hour clock (range 00 to 23)
%I
The hour as a decimal number using a 12-hour clock (range 01 to 12)
%j
The day of the year as a decimal number (range 001 to 366).
%k
The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
%l
The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
%m
The month as a decimal number (range 01 to 12).
%M
The minute as a decimal number (range 00 to 59).
%n
A newline character.
%p
Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM".
%r
The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to
%I:%M:%S %p.
%R
The time in 24-hour notation (%H:%M). For a version including the seconds, see %T below.
%S
The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)
%t
A tab character.
%T
The time in 24-hour notation (%H:%M:%S).
%x
The preferred date representation for the current locale without the time.
%X
The preferred time representation for the current locale without the date.
%y
The year as a decimal number without a century (range 00 to 99).
%Y
The year as a decimal number including the century.
%z
The time-zone as hour offset from GMT.
%Z
The time zone or name or abbreviation.
%%
A literal `%' character.
The following conversion specifications are supported only in some environments:
%C
The century number (year/100) as a 2-digit integer. (Not supported on Windows.)
%P
Like %p but in lowercase: "am" or "pm" or a corresponding string for the current locale (except on Windows, where it is the same as %p).
%s
The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC (except on Windows where it is the same as %c).
%U
The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. (Not supported in Java, C#/.NET and JavaScript)
%w
The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u. (Not supported in Java, C#/.NET and JavaScript)
%W
The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. (Not supported in Java, C#/.NET and JavaScript)
For example, "Time=%X%nDate=%x" may display the following label in the US locale:
Time: 12:49:13 PM
Date: 02/06/2013
MilliSec Format (time axes only)
Specifies a double-precision C-style format for an optional display of fractional seconds in the form of milliseconds at the end of the axis labels. It may be set to an empty string to suppress milliseconds display.

For scrolling axes with relative time, the default setting is ".%03.0f", which will display 270.5 milliseconds as ".270".
For scrolling axes with absolute time, MilliSecFormat is set to an empty string by default and is not displayed in the Builder's Properties dialog. The attribute can still be accessed via the Resource Browser using the "MilliSecFormat" resource name.
Label Format (non-time axes only)
Specifies a double-precision C-style format for axis labels (non-time axes only). For example, the "x=%.0f" format will display 12.5 as "x=12".
Major Interval
Specifies an interval between major ticks. A positive value may be used to specify an interval in axis units. A negative value may be used to specify a fixed number of major ticks instead of an interval, which may be convenient for automatic tick positioning in cases when the axis range may change. A zero value may be used to disable major ticks and labels.

For example, if MajorInterval=3600 for a time axis, the major ticks and labels will be placed at 1-hour intervals. If the axis's Span is increased to display 7 days worth of data, the axis will display an excessive number of major ticks and labels. If MajorInterval=-5, the axis will always display 5 major ticks and labels regardless of the axis's Span.
Minor Interval
Specifies an interval between minor ticks. A positive value may be used to specify an interval in axis units. A negative value may be used to specify the number of minor ticks per one major tick interval. A zero value may be used to disable minor ticks.
AxisLabel String
Specifies an axis label that may be used to identify the axis, for example in a chart with multiple Y axes.
Edit Ticks & Outline
A button in the Properties dialog to access the LineAttributes object that defines rendering attributes of the ticks and the outline.
Edit Ticks Labels
A button in the Properties dialog to access a text object that defines attributes of the major tick labels.
Low Offset (non-time axes only)
High Offset (non-time axes only)
Decrease the visible part of the axis while keeping its Low/High ranges. This may be used to display only a part of the whole axis, as it is done for the axis of the boolean plot in the GLG Real-Time Strip-Chart demo. The axis for the boolean plot shows only a small part of the axis corresponding to the [0;1] interval.

The offsets are defined in relative units in the range from 0 to 1. LowOffset specifies an offset at the low end of the axis, and HighOffset at the high end. The sum of the low and high offsets should not exceed 1. For example, for a range axis with Low=0, High=100, LowOffset=0.1 and HighOffset = 0.2, only a part of the axis from 10 to 80 will be displayed. 10% at the low end of the axis and 20% at the high end will be truncated due to the settings of the low and high offsets.
The following lists the equations for determining the location of the visible ends of the axis when High is greater than Low:
visible_low = Low + LowOffset * ( High - Low );
visible_high = High - HighOffset * ( High - Low );
visible_interval = ( High - Low ) * ( 1. - LowOffset - HighOffset );
The following equations can be used to calculate the low and high offsets based the required values for the visible ends of the axis:
LowOffset = ( visible_low - Low ) / ( High - Low )
HighOffset = ( High - visible_high ) / ( High - Low )
Rounded Placement
If set to YES, the axis places major ticks and labels at positions corresponding to values that can be evenly divided by the major tick interval. If set to NO, the first major tick will be placed exactly at the start of the axis.

For example, for a range axis with RoundedPlacement=YES, MajorInterval=10 and Low=8, the major ticks and labels will be positioned at the following values: 10, 20, 30 and so on. If RoundedPlacement is set to NO with the rest of the attributes unchanged, the major ticks and labels will be positioned at: 8, 18, 28 and so on.

For a time axis with RoundedPlacement=YES and MajorInterval=3600, the major ticks and labels will be placed at exact hourly positions regardless of the value of the axis's EndValue attribute.

The rounded placement is most useful when the major tick interval is explicitly defined by setting MajorInterval to a positive number. When MajorInterval is negative, the result of the rounded placement may look confusing, since it defines a number of major ticks and labels displayed in the visible span of the chart. In this case the actual major interval may be non-integer, and the result of the rounded placement may look confusing.
Fix Leap Years (time axes only)
If set to YES, activates a leap year adjustment that improves the year display accuracy for axes that span a large multi-year period.
Major Tick Size
Specifies the length of the major tick in pixels.
Minor Tick Size
Specifies the length of the minor tick in pixels.
TickLabel Offset
Specifies a pixel offset between a major tick and its label.
Label Extent Relative (advanced)
Specifies an extent of a major tick label in the direction parallel to the axis. It is used for scaling tick labels with TextType set to SCALED. The extent is relative to the major tick interval: the value of 0.8 would allow tick labels to use 80% of the major tick interval. If a label does not fit, it is scaled down.
Label Extent Absolute (advanced)
Specifies a pixel extent of a major tick label in the direction perpendicular to the axis. It is used for scaling tick labels with TextType set to SCALED. If a label does not fit, it is scaled down.
Major Offset
Specifies an additional offset for positioning major ticks and labels. For example, for a range axis with RoundedPlacement=YES, Low=8, MajorInterval=10, setting MajorOffset=5 will position major ticks and labels at 15, 25, 35 and so on instead of 10, 20, 30 and so on.

If the value of MajorOffset exceeds major tick interval, a remainder of an integer division of MajorOffset by MajorInterval is used as the offset value.
Time Origin (relative time axis only)
Specifies the start time to be subtracted from the sample's time stamps. For example, if a relative time chart is used to display data of an experiment, it may be desirable to display the start time of the experiment as 00:00:00 and the time 12 minutes and 5 seconds after the start of the experiment as 00:12:05. There are two ways to accomplish this. An application can set TimeOrigin to 0 and supply relative time stamps as time intervals expired since the start of the experiment. Alternatively, it may set TimeOrigin to the time of the experiment's start and supply absolute time stamps: in this case, the axis will subtract the start time from the time stamps before displaying them in the major tick labels. If the X axis of a chart is a relative time axis, the chart will also subtract the start time from the time stamps when plotting the data points, while keeping the original absolute time stamps in the data buffer.

For relative time axes used in a chart, both the EndValue and TimeOrigin attributes of the axis are initialized to the current time at the hierarchy setup time.
Tooltip Format
Specifies a custom format for an axis tooltip. The tooltip format can contain ordinary characters as well as conversion specifications. The conversion specifications contain a source keyword and a conversion format separated by the `:' character, and are surrounded with angle brackets.

Depending on the type of the conversion specification source, one of the following matching format types can be used:
double format: some variant of the "%f" format
string format: some variant of the "%s" format
time format: uses the same notation as the TimeFormat attribute described on page 140.
The following conversion specifications are supported:
axis_label
Replaced with the axis label formatted with the supplied string format.
axis_name
Replaced with the axis name formatted with the supplied string format.
axis_string
Replaced with the axis label, or with the axis name if the axis has no label. The final string is formatted with the supplied string format.
axis_value
Replaced with the value corresponding to the cursor position and formatted with the supplied double format. For time axes, the value represents a number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
axis_value_string
axis_value_text
Replaced with a string showing the axis time (or the value corresponding to the cursor position for range axes) in the format of the axis's major tick labels. The final string is then formatted with the supplied string format. The axis_value_string also removes any line breaks to form a single-line string.
axis_time (time axes only)
Replaced with a string showing the time corresponding to the cursor position formatted with the supplied time format.
axis_time_ms (time axes only)
Replaced with the value showing the number
of fractional seconds in the time value that corresponds to the cursor position. It is formed by formatting the number of milliseconds with the supplied double format.
For integrated axis objects of a chart, the tooltip is activated by the chart's tooltip settings.
For a stand-alone axis, an axis's tooltip is activated by adding a tooltip action to the axis object using the
Object, Add Tooltip menu option, setting the action's Tooltip property to "$AxisTooltip" and setting the ProcessMouse attribute of the axis's parent viewport to include the Tooltip mask. . The content of the axis's TooltipFormat attribute is then used to format the tooltip. If the value of TooltipFormat is not set, the following value is used as a default:
		<axis_string:%s> axis value= <axis_value_string:%s>
  
AxisLabel Offset
Specifies additional X and Y offsets for the axis label. The Z offset is ignored.
AxisLabel Position
Specifies the anchoring of the axis label's control point relatively to the axis's bounding box.
AxisLabel Anchor
Specifies the anchoring of the axis label's string relatively to the label's control point.
Edit Axis Label
A button in the Properties dialog to access a text object that defines attributes of the axis label.

Legend

The Legend object provides information that helps identify data displayed in a chart. For each plot, the legend displays a label and a line that shows an example of the plot appearance. A label displays a string specified by the plot's Annotation attribute; if an annotation is not supplied, the plot name is used. Optionally, the label can also display the plot's value, if enabled by the Display Value legend attribute.

While the legend is tightly coupled with its chart, it is implemented as a separate object to allow developers to control its location and layout. A legend is attached to a chart by selecting it, marking it with the Arrange, Legend, Mark Legend menu option, then selecting a chart and using the Arrange, Legend, Set Chart Legend menu option. The Arrange, Legend, Reset Chart Legend menu option can be used to disconnect the legend from the selected chart.

The legend has two control points that define its bounding box. The legend content may extend beyond the box if it does not provide enough space to lay out the legend's entries. The legend may be placed in a separate viewport if it is desirable to clip the legend's content when it becomes too long. When a legend is placed in a separate viewport, that viewport and not the legend itself must be used for marking the legend with the Arrange, Legend, Mark Legend menu option.

The legend has the following attributes that control its appearance and layout:

Layout Type
Specifies the type of layout used for positioning legend entries, can be one of the following:
HORIZONTAL
Legend entries are laid out left to right along a single horizontal line.
HORIZONTAL WRAPPED
Legend entries are laid out horizontally. If the legend extends beyond the box defined by its control points, it is wrapped to start a new horizontal row below the previous one.
VERTICAL
Legend entries are laid out top to bottom along a single vertical line.
VERTICAL WRAPPED
Legend entries are laid out vertically. If the legend extends beyond the box defined by its control points, it is wrapped to start a new vertical line to the right of the previous one.
Auto Layout (wrapped legends only)
Controls row wrapping behavior of the legend. The term "row" is used for both horizontal and vertical lines of legend entries regardless of their direction.

If AutoLayout is set to YES (default), the legend wraps a row when the row extends beyond the box defined by the legend's control points. In addition, the MinRowSize and MaxRowSize attributes of the legend may be used to fine-tune the layout behavior. The MinRowSize may be set to a non-zero value to enforce the minimum number of elements in a row even if the row extends beyond the legend's box. The MaxRowSize may be set to a non-zero value to force the row to wrap when the number of items reaches MaxRowSize, even if it does not extend beyond the legend's box.

If AutoLayout=NO, the legend ignores the legend box and the layout behavior is based on the value of MaxRowSize, if it is set to a non-zero value. The legend ignores MinRowSize and wraps a row only when the row size reaches MaxRowSize, regardless of the legend's box. If MaxRowSize=0, the legend wraps the row if it extends beyond the legend's box.

If the legend's labels use scalable text, the legend may also use a smaller font for rendering labels if the legend's content does not fit the legend's box.
Anchor
Specifies the anchoring type of the legend's content relatively to the box defined by the legend's points.
Row Anchor
Specifies the anchoring type of individual rows of a multi-row legends with rows that have different pixel length.
Min Row Size
Specifies the minimum number of elements in a row for wrapped legends. If the number of elements in a row is less than the minimum, a new row will not be started even if the row does not fit into the legend's box.
Max Row Size
Specifies the maximum number of elements in a row for wrapped legends. If the number of elements in a row is more than the maximum, a new row will be started even if the row fit into the legend's box and can accommodate more entries.
Display Value
If set to YES, each labels will display the value of the corresponding plot.
Value Format
Defines a floating point C format used to display a plot value after the plot name. The default "\n%.2f" value format contains a new line character to display the value on the second line.
Edit Labels
A button in the Properties dialog to access a text object that defines attributes of the legend's labels.
Edit Background
A button in the Properties dialog to edit attributes of a background box drawn around the legend's content. To disable the display of the background, set its FillType to NONE or set its Opacity to 0.
Line Length
Specifies a length in pixels of a line element of a legend entry.
Min Line Width
Specifies a minimum line width of a line element of a legend entry.
Bar Height
Specifies the height of a bar element of a legend entry.
XOffset
YOffset
Specifies horizontal and vertical pixel offsets between the edge of the legend's background box and the legend content.
XSpacing
YSpacing
Specifies horizontal and vertical pixel spacing between the elements of the legend.
Label XOffset
Specifies a horizontal pixel offset between the line and label elements of a legend entry.
Label Max Width
Specifies the maximum pixel width for scalable legend labels with TextType=SCALED. If a label does not fit, it is scaled down.
Label Max Height
Specifies the maximum pixel height for scalable legend labels with TextType=SCALED. If a label does not fit, it is scaled down.

Non-Graphical Objects

While GLG non-graphical objects are not visible in a GLG drawing, they can control the position and a wide variety of visible features of the objects that do appear. These objects are for advanced usage and may be safely ignored until they are really needed.

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 Data Connectivity on page 232 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:

DataType
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 Value is omitted from a resource name when the value of the attribute represented by the data object is accessed. For example, "my_object/Angle" resource name is used to access an object's Angle parameter, and not "my_object/Angle/Value". NULL may be used as a resource name to access the value of a data object using its object ID, as shown in the following example:
		GlgObject data_obj;
		data_obj = GlgGetResourceObject( my_object, "Angle" );
		GlgSetDResource( data_obj, NULL, 90. );
  
XfValue
A read-only 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. The following example queries the transformed value of an object's attribute:
double xf_value; GlgGetDResource( my_object, "Angle/XfValue", &xf_value );
TagObject
An optional tag object that may be attached to the data object to define data connectivity for animating its data value. If a tag object is present, the data object inherits all tag attributes, such as TagName, TagSource and TagEnabled.
UTF8Encoding (data objects of S type only)
A boolean flag that defines the encoding used for storing the string. If it is set to YES, the string value will be stored using the UTF-8 encoding, otherwise it will be stored using the default encoding defined by the system locale. This flag is located next to the Value field in the Attribute dialog and shows "UTF" for the UTF8 encoding or "DEF" for the encoding of the system locale.

Alternatively, the UTF8 encoding can be used for all S data objects in a viewport by setting the LocaleType attribute of the viewport's screen to UTF8. The GlgLocaleType global configuration resource can also be set to 2 (the value of the GLG_UTF8_LOCALE constant in the GlgApi.h file) to enforce the UTF8 encoding for all S data objects in viewports with LocaleType=Default (or inherited from a parent viewport with UTF8 locale when LocaleType=Inherit).

For the text objects with the UTF-8 encoded strings to be rendered properly regardless of the system locale setting in C/C++, the text object should either use an XFT font (on Linux/Unix), or a UTF-8 font with MultiByteFlag set to UTF8 (on Windows or for an XFLD font on Linux/Unix). Refer to the Font section on page 164 for more information. If the UTF8 setting of the text string and the font used to render it do not match, the appropriate encoding conversion will be automatically performed. The characters that are not present in the font will be replaced with the default character.

In the Java, C#/.NET and JavaScript environments, the UTF8Encoding flag is used only for proper string decoding when a drawing is loaded. For drawings created in the UTF8 locale with all strings in the UTF8 encoding, a UTF8 encoding can be specified when loading the drawing in Java, C# or JavaScript. The UTF8 encoding is specified either by using an encoding parameter of the GLG API methods for loading drawings, or by setting the default encoding of the GLG Java Bean and the GLG Custom Control for C# via the corresponding SetCharsetName and SetEncoding methods. It may also be set globally by using the GlgDefaultCharset global configuration resource in Java, or GlgDefaultEncoding in C# and JavaScript.

If the UTF8 encoding was not specified, the S data objects with UTF8Encoding=YES will be interpreted as UTF8 strings, and the rest of the strings in the drawing will be assumed to be in the encoding of the current locale. Once loaded, the string is stored in memory in Java, C# or JavaScript internal representation, which is using the UTF-16 version of UNICODE. This ensures proper rendering of the string regardless of the system locale, and the MultiByteFlag of the font used to render the text is ignored.

The Options, Convert Strings to UTF8 on Save menu option may be checked to automatically convert all string attributes (such as TextString of a text object) from the current locale to UTF8 when the drawing is saved. This is especially convenient when using localized strings on Windows in a drawing that will be used on the web with the JavaScript, which uses UTF8 as a default character set. The Arrange, UTF8 Conversions menu provides options for converting all strings in the drawing from the current locale to UTF8 and from UTF8 to the current locale.

When the UTF8Encoding flag is changed in the Builder, the string's encoding is automatically converted from UTF8 to the system encoding or vice versa, depending on the flag's state. If some characters in an UTF8-encoded string can not be represented in the system locale, the conversion is non-reversible and UTF8Encoding flag is restored to its original state. Shift-click on the UTF8 toggle to proceed with a non-reversible conversion that results in a loss of information. If the string contains invalid multi-byte characters for the system locale, the conversion fails and the flag is restored to its original value as well. Ctrl-click on the UTF8 toggle may be used to change the flag without converting the string; this may result in an invalid character string and should be used only to fix UTF8-encoded strings in old drawings which did not have the UTF8Encoding flag.

When setting values of string resources at run time, it is an application's responsibility to set the
UTF8Encoding flag to a state matching the encoding of the string passed to the GlgSetSResource method. Setting the value of the flag at run time using the GlgSetDResource method does not re-encode the string.
AlwaysChanged
This advanced attribute is not shown in the Attribute dialog and is used internally to implement intelligent handling of the if_changed parameter of the SetTag and SetResourceIf methods of the GLG API. The if_changed parameter is used to optimize update performance. If it is set to TRUE, the drawing will be updated only if the resource or tag value has changed. It is common to use if_changed=TRUE when supplying data using tags.

Some resources, such as a chart entry point used to push data into the chart, need to be updated even if the data value did not change, since the chart has to scroll even when the plotted chart value doesn't change over time. This is accomplished by setting the
AlwaysChanged attribute of chart and history entry points to TRUE to suppress the if_changed parameter of the SetTag and SetResourceIf methods. The attribute is automatically set to TRUE at the hierarchy setup time, making sure that the chart will scroll regardless of the value of the if_changed parameter when the same data value is repeatedly pushed into the chart.

The attribute may be queried via the GLG API to determine if a data object is used as a chart entry point.

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.

To access attribute objects via resources, use default attribute names instead of named object attributes. For example, "my_polygon/LineWidth" may be used to access the LineWidth attribute (vs. "my_polygon/my_color"). For polygon points, the GlgGetElement function can also be used to access point's attributes.

The attribute object's properties are similar to the properties 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
The attribute value stored in its data object. Note that Value is omitted from a resource name when the value of the attribute is accessed. For example, "MyPolygon/LineWidth" resource name is used to access the line width of a polygon, and not "MyPolygon/LineWidth/Value". NULL may be used as a resource name to access the value of a data object from its object ID, as shown in the following example:
		GlgObject attr_obj;
		attr_obj = GlgGetResourceObject( polygon, "LineWidth" );
		GlgSetDResource( attr_obj, NULL, 2. );
  
XfValue
A read-only 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. The following example queries the transformed value of an object's attribute:
double xf_value; GlgGetDResource( polygon, "LineWidth/XfValue", &xf_value );
ExportTag
An optional export tag object that may be attached to the attribute object to mark it as an exported public property. It is used by the OEM version of the Builder; refer to the OEM Version of the Graphics Builder chapter on page 335 for details.
Data
The base data object used for storing the attribute's value.

The attribute object also inherits the TagObject and AlwaysChanged attributes of its data object, which may be queried as resources of the attribute object.

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:

TagType
Defines the type of a tag. The default DATA tag type is used for data connectivity.
The other tag types, EXPORT and EXPORT_DYN, are used by the OEM version of the Graphics Builder to define public properties of components for the GLG HMI configurator and properties of custom dynamics, respectively. The EXPORT_DYN tag type is also used to define public properties of action commands and action data sets. Refer to the OEM Version of the Graphics Builder chapter on page 335 for details.
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. The TagSource attribute is used only by the DATA tags.
TagAccessType
Specifies an access type of the tag, may have the following values:
INPUT
An input tag that may be updated with incoming data. This is the default.
OUTPUT
An output tag used to send data back to the process controller. The output tag is skipped and is not updated when the SetTag methods are used. Output tags may be used in an application to keep IDs of tags to be updated in the process database when user enters a new tag value.
INIT
Same as INPUT, used to indicate that an application needs to set the tag just once when the drawing is initially displayed.
TagEnabled
This D attribute may be set to FALSE at runtime to temporarily disable updates of the tag with the SetTag methods. The attribute may be used by an application to disable updates of a text input object from an attached tag while the user enters a new value. Disabling a tag does not affect other enabled tags with the same TagSource: they will still be updated with new values when the SetTag methods are invoked.
TagComment
A string used to hold user-defined information related to the tag.

The Data Tag 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.

The Browse button of the Data Tag dialog allows the user to browse custom data sources and select tag sources from a list of available choices. A custom data DLL may be provided to connect to the application-specific data sources, such as a process database or PLC controller.

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

Using Output Tags and Disabled Tags in a Program

The SetTag and GetTag methods of the GLG API skip tags that have TagEnabled=FALSE , generating an error if no enabled tags with the requested TagSource were found in the drawing. The SetTag method also generates an error if the only found tag with the requested TagSource is an OUTPUT tag.

When the QueryTags and GetTagObject methods are used in a single tag or unique tags modes, they return the best available tag(s): enabled INPUT and INIT tags have priority over the disabled and OUTPUT tags.

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 data samples, 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 data samples) 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 data samples, 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.
Path
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:

A rendering object may be reused by marking it with the Mark button at the top of the Properties dialog. Use the Edit, Add or Use Marked Object, Rendering Attributes menu option to add the marked rendering attributes to another 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 constraining of corresponding attributes of the added rendering objects (the attributes are constrained if the default Constrained Clone setting is used). When a marked rendering object is reused, constraining of corresponding attributes of the new copy and the original rendering object is also controlled by the Builder's Attribute Clone Type option.

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, such as FillColor, EdgeColor, LineWidth, LineType 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.
AnchorOnBox
Controls anchoring of text objects with an attached text box. If set to YES (default), the box extent will be used for anchoring the text object, otherwise the anchoring will be done using the extent of the text, without counting the extent of the box.
Delete Box Attributes
This button is present only in the Builder; it deletes the Box Attributes object.

The FillColor, EdgeColor, LineWidth, LineType and FillType attributes of the text box can be accessed as resources of the text object the box is attached to. More specific resource names (BoxFillColor, BoxEdgeColor, BoxLineWidth, BoxLineType and BoxFillType) are also supported to differentiate resources of a text box from resources of polygons and other objects with the same resource name.

A Box Attributes object may be reused by marking it with the Mark button at the top of the Properties dialog. Use the Edit, Add or Use Marked Object, Text Box menu option to add the marked box attributes to another text 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 constraining of corresponding attributes of the added box attribute objects (the attributes are constrained if the default Constrained Clone setting is used). When a marked Box Attributes object is reused, constraining of corresponding attributes of the new copy and the original object is also controlled by the Builder's Attribute Clone Type option.

Line Attributes

The Line Attributes object is used to keep attributes of lines and polygons used to render internal components of a chart or an axis. The Line Attributes object inherits most polygon attributes like EdgeColor, LineWidth and LineType. It may also contain FillType and FillColor attributes for filled polygons, and has the following additional attribute:

Opacity
Opacity in the range from 0 to 1. If set to 0, the line will be completely transparent.

A Line Attributes object may be reused by marking it with the Mark button at the top of the Properties dialog. Use options from the Edit, Add or Use Marked Object menu to add the marked line attributes to another object. The Edit, Add or Use Marked Object menu has several entries depending on the way the marked line attributes are used in the drawing: Axis Tick, Chart Grid, Chart Cross-Hair, Chart Background and Plot/Level Line.

When a Line Attributes 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 constraining of corresponding attributes of the added Line Attributes objects (the attributes are constrained if the default Constrained Clone setting is used). When a marked Line Attributes object is reused, constraining of corresponding attributes of the new copy and the original object is also controlled by the Builder's Attribute Clone Type option.

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, as well as in the Java, C#/.NET and JavaScript versions 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:
Color Factors for Standard Color Table
ColorFactor
Number of Colors
0
256 (default)
1
256
2
8
3
64
4
256 (maximum)

The ColorFactor values of 0 and 1 are mapped to 256 colors instead of 1, because it does not make any sense to have a colortable with just one color. If ColorFactor is greater than 4, the number of colors is still limited to 256 on 8-bit color machines. The ColorFactor mapping for the RAINBOW color table is:
Color Factors for Rainbow Color Table
ColorFactor
Number of Colors
0
19 (default)
1
1
2
7
3
19
4
37
5
61
6
91
7
127
8
169
9
217

NumColors
A read-only attribute that contains the actual number of colors used.
GradeHint
Defines a number of color intensities for every color hue for the RAINBOW colortable. If set to 0 or 1, the default value of six is used. A value of two indicates that each color shall have two grades: black and full strength.
NumGrades
A read-only attribute that contains the actual number of grades used.
PatternFactor
Defines a number of dithering patterns used to render color intensities. Using dithering increases the number of possible color intensities without increasing the number of allocated colors. A value equal to 0 causes only one pattern to be used, disabling dithering. Like the ColorFactor, this attribute is an index into a table of predefined values:
Dithering Patterns
PatternFactor
Number of dithering patterns
0
1
1
4
2
16 (default)
3
64
4
256 (maximum)

NumPatterns
A read-only attribute containing the actual number of patterns used.
RenderingColor
Defines a color used for simulating a monochrome or a greyscale display. Everything is rendered in different intensities of this color. This attribute has an effect only if the number of colors is equal to 1.
ColorCorrection
Controls the color correction for the colortable. If it is set to YES, color intensities are corrected to produce a bigger number of light colors in the colortable. If it is set to NO, there are more dark colors. Color correction affects only the RAINBOW color distribution.

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

Font Table

The font table object controls the selection of fonts available for use in a viewport. The font table contains a list of font families, and each family contains a list of fonts of different font sizes. A Text object in a drawing is rendered using fonts from the font table of the drawing's viewport. The text object's FontType attribute defines a font family index in the font table, and the FontSize attribute defines the font size index within the font family.

When a viewport is created, it inherits a default font table. A font table 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
A container object containing a list of font families. Each font family contains a list of fonts of different sizes. Each font is stored in a font object described below.

If a custom font table is not provided, GLG drawings use a default font table. A custom font table can be specified in one of the following ways:

The GlgDefaultFontFile, GlgDefaultXftFontFile, GlgDefaultNumFontTypes and GlgDefaultNumFontSizes global configuration resources and the corresponding environment variables described on page 436 of the GLG Programming Reference Manual may be used to define a list of fonts for the default font table using a plain text file. In the X Windows environment, each entry of the file may contain either a font name, or 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. The GlgDefaultPSFontFile global configuration resource may be used to specify the location of the file that contains the list of the PostScript fonts for the default font table. This method is inferior compared to the use of the GlgDefaultFontTableFile resource and is provided for compatibility with previous releases.

ADVANCED: the GlgDefaultFontTable global configuration resource can be used in a program to set the global font table default to an object ID of a loaded or created font table.

Editing a Font Table

A font table can be edited by changing the number of font types and font sizes, and editing the fonts defined in the font table. The dialog for editing fonts presents two lists: the list on the left displays font families, and the list on the right displays font sizes of the selected font family. The font Properties dialog on the far right displays properties of the selected font. A font browser for selecting a font can be started by clicking on the ellipsis button for the font name attribute (WinFontName on Windows, and either XFontName or XftFontName on X Windows). Refer to the Font section below for more information.

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

The font table's Properties dialog also contains buttons for reusing a font table. A font table may be reused by marking it with the Mark button at the top of the Properties dialog. Use the Edit, Add or Use Marked Object, Font Table menu option to add the marked font table to another viewport. The font table can also be reused by using the Mark Font Table and Use Marked Font Table buttons, or by saving it into a file and loading into another viewport by using the Save Font Table and Load Font Table buttons in the Properties dialog.

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 constraining of corresponding attributes of the added font tables (attributes are constrained if the default Constrained Clone setting is used). When a marked font table is reused, constraining of corresponding attributes of the new copy and the original font table is also controlled by the Builder's Attribute Clone Type option.

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 a non-XFT font handles the characters as single-byte, multi-byte or
UTF-8; the attribute is ignored for the XFT fonts on X Windows. The attribute also controls the font usage as follows:

Light Object

The light object is used by a viewport to hold the viewport's lighting attributes. 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)
All polygons will be rendered in their original colors regardless of the orientation (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 LightCoef and AmbientCoef attributes), and its FillColor attribute.
FLAT (GLG_FLAT_LIGHT)
The actual color used to fill a polygon also depends on its position relative to the light vector (directed from LightPoint to LightDirection). The light is infinitely distant and the light rays are parallel to one another.
POINT (GLG_POINT_LIGHT)
The actual color used to fill a polygon also depends on its position relative to the light vector. The position of the light source is defined by the LightPoint attribute.

Note: The POINT light setting is enabled only when the OpenGL driver is used. If the GDI driver is used, it behaves as the FLAT light option.
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.

A light object may be reused by marking it with the Mark button at the top of the Properties dialog. Use the Edit, Add or Use Marked Object, Light Object menu option to add the marked light object to another viewport.

When a light object is added to a group of viewports using the group's Edit All option, the Attribute Clone Type option of the Builder controls constraining of corresponding attributes of the added light objects (the attributes are constrained if the default Constrained Clone setting is used). When a marked light object is reused, constraining of corresponding attributes of the new copy and the original light object is also controlled by the Builder's Attribute Clone Type option.

A polygon's Shading attribute provides additional control over shading of individual polygons in the drawing.

For more information about lighting, see the Lighting section on page 53 of Structure of a GLG Drawing.

Transformation Object

The transformation object describes a transformation associated with a GLG object. A special type of a transformation object is also used to implement alarms.

The lists in the following sections describe the attributes of the GLG transformation objects. The default names of these attributes are XformAttr1 through XformAttr6. The attributes below are listed in the order given by their default names, but we have used more descriptive names to help explain their use. These names are also used in the GLG Graphics Builder.

Stock Transformations vs. Predefined Dynamics

There are two sets of dynamics options for object attributes: the stock transformations and predefined dynamics. The stock transformations are basic transformation types used as building blocks to implement dynamic behavior. Predefined dynamics are pre-created combinations of stock transformations that provide easy to use options for the most common dynamic actions in the GLG editors. Predefined dynamics may also be used by system integrators to extend GLG editors with elaborate application-specific dynamics.

Predefined dynamics represent a collection of several stock transformations wired together to implement a specific dynamic behavior. Most of the parameters of the transformations used to implement the predefined dynamics are hidden from the user, and only the essential parameters marked as public are presented to the user as a simple list of public properties. The Options, Dynamics Options menu of the Graphics Builder contains options that control how the predefined dynamics are displayed in the Builder's dialogs.

The following chapters list the available types of the stock transformations first, and list the predefined dynamics choices at the end.

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 the Transformations as Objects section on page 46.)

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 the Transformations section on page 45.

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.

Matrix

The Matrix transformation stores a 4x4 matrix with which to transform a geometrical value. This is the standard matrix transformation used in computer graphics, and the derivation is available in many texts on that subject. To use the GLG Toolkit, you need only understand that the matrix, when multiplied by a point in three-dimensional space, produces the coordinates of another such point. The mapping of input points onto output points by this matrix multiplication is a transformation. The matrix itself is the only attribute of a matrix transformation object. Its name is Matrix, and it is a read-only attribute. This is to say that once the matrix object has been created, it may not be edited directly, although it may be replaced.

Partly because of the read-only nature of the Matrix attribute, and partly because of the unwieldy nature of a matrix value, the matrix transformation is often called a static transformation. All the other geometrical transformation objects are dynamic objects, since they simply store the values necessary to create a transformation matrix on the fly. These values may be edited, and accessed, as resources like any others.

MoveBy

The MoveBy transformation object moves the input geometrical value a given distance along the X, Y, or Z axis. It has three attributes:

Direction
Specifies the direction of the motion, selected at the creation time. The available values are X, Y, or Z, or XYZ.
Distance
A scalar (double-precision) specifying the distance to move.
Factor
Normalized move parameter. The actual distance moved is the product of the Factor and the Distance attribute.

If the Direction attribute has the XYZ value, there are three Distance/Factor pairs, one for each dimension.

Move

The Move transformation, like the MoveBy transformation, is simply used to relocate a geometrical value. The difference is in how the move is specified. A MoveBy transformation moves a point a given distance in a predetermined direction. A Move transformation specifies the direction explicitly by using two points in the drawing.

The Move object has the following attributes:

StartPoint
The start point of the move vector, specified with a geometrical value.
EndPoint
The end point of the move vector, specified with a geometrical value
Factor
Normalized move parameter. The actual move vector is the product of the Factor and the vector defined by the Start and End points.
Rotate

The Rotate transformation specifies a point in space to rotate about, and a number of degrees to rotate.

Rotation Axis
Specifies the axis around which the object rotates and is selected at the creation time. The available values are X, Y, or Z.
Center
The center point, specified as a value.
Angle
Rotation angle in degrees counter-clockwise.
StartAngle
Start angle of rotation in degrees, measured counter-clockwise. The object is always rotated from its original position by the start angle even if the factor is 0. The start angle is convenient for defining the start position of rotation without actually rotating the object.
Factor
Normalized rotation parameter. Changing the factor from 0 to 1 changes the actual rotation angle from StartAngle to StartAngle + Angle.
Shear

The Shear transformation is like a rotation, except that each point of the shape being sheared is constrained to stay on a line parallel with the shear direction.

Direction
Specifies the direction of the shear and is selected at the creation time. Possible values are X, Y, and Z.
Center
The center point, specified as a geometrical value.
Shear
Scalar shear coefficients relative to the selected shearing axes.
Factor
Normalized shear parameter. The actual shearing coefficients are products of the Factor and the Shear coefficients.
Scale

The Scale transformation defines a center point and a factor. An input point is transformed by measuring its distance from the center point, and moving it along the line defined by those two points to a point whose distance from the center point is the original distance times the Scale value.

Center
The center point, specified as a geometrical value.
Scale
Scalar scale coefficient.
Start Scale
Start scale coefficient.
Factor
Normalized scale parameter. Changing the factor from 0 to 1 changes the object's actual scale factor from Start Scale to Scale.

There is no separate Mirror transformation object. You can create one in the editor, but it is just a convenience, like the rectangle. A mirror transformation is simply a scale transformation with the Scale attribute set to -1.

In addition to the simple scale transformation object, there are corresponding ScaleX, ScaleY, and ScaleZ transformation objects, each of which act only upon the indicated dimension. The type of the scale transformation is selected at the creation time.

Path

The Path transformation moves a point along a predefined path polygon.

Path
Array of the path points. This is a group object that contains points of the path.The points may be edited, added or deleted.
Factor
This is a scalar value, specifying the current position as a distance along the polygon's perimeter. The first defined point on the polygon is at Factor=0, and the last is at Factor=1.
Rotate Flag
Controls the way object rotates as it follows the path. The flag may have the following values:
DON'T ROTATE
Object does not rotate.
ROTATE
Object rotates to match the tangent of the path in the current position. This setting may be used to create an object that will rotate as it moves along a curved path.
ROTATE NO ORIGIN
Advanced setting, same as rotate, but the origin parameter is ignored. The object is not moved to the beginning of the path as defined by the origin parameter. The effect of this setting is visible only if the origin was moved to a position different from the beginning of the path.
Origin
A point that defines how the object must to be moved to the beginning of the path when the path factor is 0. The object is moved by the vector defined by the Origin as the start point and the first point of the path as the end point. By default, the Origin is constrained to the first point of the path and the object is not moved to the beginning of the path. To move the object, unconstrain the Origin and then define it's new value. For example, placing the origin in the center of the object will cause the object's center to be aligned with the path as the object moves along it. You can also constrain the Origin to some point of the object, which will permanently align that object's point to the path.
Discrete
If set to YES, changes the behavior of the transformation by interpreting the value of Factor as an integer 0-based point index. Setting Factor to 1 moves the object from the first to the second point of the path; setting it to 2 moves the object to the third point, and so on. The factor value of 0 corresponds to the first point and returns the object to the beginning of the path.
Offset
Defines an initial path offset which is added to the value of the Factor.
Wrap
If set to YES, the values of the Factor outside of the range ([0;1] for non-discrete path transformations, or from 0 to the number of path points for discrete paths) get "wrapped around" instead of being truncated.
Concatenate

The Concatenate transformation is used to build a list of geometrical transformations attached to a single object. This transformation object has only two attributes, that point to the first transformation on the list and the second. If more than two transformations must be attached to an object, then multiple Concatenate objects can be used. For example, to hold a list of three transformation objects, use two Concatenate transformations, as in the following diagram:




Using the Concatenate Transformation Object

To add another transformation to the list, replace Transformation3 with another concatenate transformation object, which holds Transformation3 as the first attribute and the new transformation as the second attribute.

Note that the GLG Graphics Builder does not explicitly manipulate concatenate transformation objects. The Builder uses concatenate transformation to build and edit lists of transformations attached to an object, but the overhead of keeping track of the concatenate objects is hidden from the user.

The concatenate transformation object has just two attributes:

Xform1
The first transformation object.
Xform2
The second transformation object.
G From D

The G From D transformation may be used to form a single data object of G type (such as an XYZ point or RGB color) from three D (double) data objects that define individual X, Y, Z or R, G, B components. The transformation has three attributes; each attribute supplies either a coordinate or an RGB color component.

This transformation may be attached only to a G attribute different from a control point. To achieve the same result for a control point, either an Offset or three MoveByX, MoveByY and MoveByZ transformations can be added to the control point to supply the X, Y and Z coordinates from independent double data values.

World Offset

The World Offset transformation may be attached to a point to maintain a constant offset from another point. This transformation may be attached only to an object's control point and not to the object itself. It has the following attributes:

Anchor Point
Specifies the coordinates of the anchor point. This attribute can be constrained to another point to use that point as an anchor.
X Offset
Offset along the X axis in the world coordinates.
Y Offset
World offset along the Y axis.
Z Offset
World offset along the Z axis.
Move Flag
When a point with an offset transformation is moved, the transformation's parameters are modified instead of changing the coordinates of the point. MoveFlag controls the way the transformation is modified when the control point it is attached to is moved. If the flag is set to GLG_CHANGE_OFFSETS, the transformation's offsets are adjusted when the control point is moved to reflect the new point position. If it is set to MOVE_ANCHOR POINT, the coordinates of the transformation's anchor point are modified.

To add the world offset transformation, use World X, World Y or World XY offset type options in the Add Dynamics dialog. All of them add the same type of the world offset transformation, the difference is that they initialize unused offsets to 0 for convenience.

Moving a point with the worlds offset transformation modifies X, Y and Z offset parameters of the transformation instead of changing the point's coordinates.

Fixed Offset

The Fixed Offset transformation is similar to the World Offset transformation and has the same attributes. However, the transformation offsets are specified in screen pixels, and neither the offsets nor the offset direction change when the drawing is zoomed, or when the object containing the transformation is scaled or rotated.

Same as World Offset, the Fixed Offset transformation may be attached only to an object's control point and not to the object itself. To add the fixed offset transformation, use Fixed Pixel X, Fixed Pixel Y or Fixed Pixel XY offset type options in the Add Dynamics dialog. All of them add the same type of the fixed offset transformation, initializing unused offsets to 0 for convenience.

Moving a point with the fixed offset transformation modifies X, Y and Z Offset parameters of the transformation instead of changing the point's coordinates. The fixed offset transformation is not allowed inside a GIS object, except when it is used inside icons implemented as reference objects of a fixed size.

Pixel Offset

The Pixel Offset transformation is similar to World Offset and Fixed Offset, but allows the user to define an offset in either the world coordinates or screen pixels. If a pixel offset is used, the transformation maintains a constant pixel offset when the drawing is resized. Unlike the fixed offset of the Fixed Offset transformation, the pixel offset is still a subject to other transformations and will change together with the drawing when the drawing is zoomed, or when the object containing the transformation is scaled or rotated.

Same as the World Offset, this transformation may be attached only to an object's control point and not to the object itself. It has the following attributes:

Anchor Point
Specifies the coordinates of the anchor point. This attribute can be constrained to another point to use that point as an anchor.
X Offset
Offset along the X axis.
Y Offset
Offset along the Y axis.
Z Offset
Offset along the Z axis.
X Offset Type
Y Offset Type.
Z Offset Type
Units of the corresponding X, Y or Z Offset:
WORLD
Offsets are interpreted as world coordinates.
INVERSED_WORLD
Offsets are interpreted as world coordinates, but signs of the offsets are inversed.
PIXEL
Offsets are interpreted as screen pixels.
INVERSED_PIXEL
Offsets are interpreted as screen pixels, but signs of the offsets are inversed.
RATIO
Offsets are interpreted as world coordinates, which are then adjusted by the corresponding screen scale ratio (the X/Y ratio for the X offset, the Y/X ratio for the Y offset, or a ratio of Z scale to the geometric mean of X and Y scales for the Z offset). The X or Y screen scale is an absolute value of the scale factor used to convert world coordinates to screen pixels in the corresponding direction at the current viewport size. This is useful for creating advanced resizing behavior.
INVERSED_RATIO
Same as RATIO, but uses the reciprocal of the corresponding screen scale.
Move Flag
When a point with an offset transformation is moved, the transformation's parameters are modified instead of changing the coordinates of the point. MoveFlag controls the way the transformation is modified when the control point it is attached to is moved. If the flag is set to GLG_CHANGE_OFFSETS, the transformation's offsets are adjusted when the control point is moved to reflect the new point position. If it is set to MOVE_ANCHOR POINT, the coordinates of the transformation's anchor point are modified.

The Pixel Offset transformation allows the user to mix a world offset in one direction and pixel offset in another by using different offset types for different axes.

To add a pixel offset transformation, use Pixel X, the Pixel Y or the Pixel XY offset type options in the Add Dynamics dialog. All of them add the same type of the pixel offset transformation, initializing unused offsets to 0 for convenience.

Moving a point with the pixel offset transformation modifies X, Y and Z Offset parameters of the transformation instead of changing the point's coordinates. The pixel offset transformation is not allowed inside the GIS object, except when it is used inside icons implemented as reference objects of a fixed size.

Screen Scale (ADVANCED)

The Screen Scale transformation is similar to the Scale transformation, but it automatically adjusts its scale factor to maintain an object's dimensions constant in the selected direction when the drawing is resized. The transformation is used by some of the graphs for implementing desired layout behavior and has the following attributes:

Center
The center point, specified as a geometrical value.
Factor
Scalar scale coefficient. The actual scale factor is a product of the Factor and the automatically adjusted scale factor used to compensate the change of the window size.

To add the screen scale transformation, use ScaleScrX, ScaleScrY or ScaleScrZ scale type options in the Add Dynamics dialog.

Scalar Transformations

There are several transformation objects designed to apply to simple scalar (D) values; these transformations can be attached to attributes of D type, such as LineWidth or Visibility. A scalar transformation takes an input value, transforms it according to the type of the transformation and assigns the resulting output to the attribute's transformed value. What is used as the input value depends on the type of the transformation.

Some scalar transformations use the value of the attribute they are attached to as the input value, and set the transformed value of the attribute to the output. For example, the Divide transformation takes the value of the attribute, divides it by the transformation's Divisor parameter and sets the transformed value of the attribute to the resulting output. In the Graphics Builder, the attribute's value and the transformed value are shown in the Attribute dialog as Value and XfValue; the attribute's text field in the Properties dialog shows the attribute's Value and allows in-place editing.

Other scalar transformations ignore the value of the attribute and use one or more transformation parameters as input values. For example, the Range Conversion transformation ignores the value of the attribute, uses its Input Value parameter as an input and sets the transformed value of the attribute to the resulting output. In the Graphics Builder, if an attribute that has a transformation that ignores the attribute's value, the Value field in the Attribute dialog will be disabled; the Properties dialog will display the attribute's transformed value (XfValue) which also will be disabled for editing. Any changes of the attribute should be done by changing the input value of the attached transformation.

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.

Refer to the Common Attribute Transformations section on page 186 for additional transformations that can be attached to scalar attributes.

Range Conversion

The Range Conversion transformation maps a range of input data values into a different range of output values. For example, if the transformation is set up to map the input values 12 through 20 to the values 0 to 1, an input value of 16 would produce an output value of 0.5.

By default, the two sets of bounds set up the mathematical relation between input and output; they do not impose limits. That is, the input bounds merely set the ratio of input to output. An input value outside the given bounds is mapped to a comparable output value outside the output bounds. That is, if the range transformation is set up to map the interval from 0 to 1 to the output interval 100 to 200, than an input value of 5 will map to an output value of 600. Similarly, the low and high bounds of the input range can be flipped, with the low higher than the high. In this case, the mapping, too, will be flipped. The transformation's Truncate parameter may be set to force the values inside the bounds.

The transformation ignores the attribute's Value and uses the transformation's Input Value parameter as input. The converted output value is assigned to the attribute's transformed value (XfValue). The attributes for this transformation are as follows:

In Low
The lower bound of the input data range.
In High
The upper bound of the input data range.
Out Low
The lower bound of the output data range.
Out High
The upper bound of the output data range.
Truncate
If set to YES, the output value outside the OutLow-OutHigh range will be adjusted to fit inside the range.
InputValue
The input value to be converted to a new range.

Backward Compatibility Note: A Range transformation was used in releases prior to 3.4. The Range transformation had the same parameters as Range Conversion, except for Input Value: instead, it was using the attribute's Value as input. The Range transformation was deprecated, but it is still supported for backward compatibility with old drawings.

RangeCheck

The range check transformation sets the attribute's transformed value (XfValue) depending on the input value being inside or outside of the specified range. The transformation may be used to activate blinking when the value goes out of range. The transformation ignores the attribute's Value and uses the transformation's Input Value parameter as input.

The attributes for this transformation are as follows:

High High
The high high input data range.
High
The high input data range.
Low
The low input data range.
Low Low
The low low input data range.
Input Value
The input value.
Equal Flag
Controls how input values equal to the range limits are handled. When set to ALARM_ON_EQUAL, input values equal to the limits are handled as alarms. When set to NO_ALARM_ON_EQUAL, values equal to the limits are handled as normal.

If the input value is outside of the HighHigh-LowLow range, the output value is set to 2. If the input value is outside of the High-Low range, the output value is set to 1. If the input value is within the High-Low range, the output is set to 0. To disable the HighHigh-LowLow check, set both of these attributes to 0.

Timer

The Timer transformation periodically changes a value of a scalar attribute, which can be used to implement various types of blinking or to perform run-time animation. The output value of the timer transformation is multiplied by the attribute's Value before being assigned to the attribute's transformed value (XfValue).

The timer transformation has the following attributes:

Update Type
The type of periodic updates to perform, may have one of the following values:
SAWTOOTH
A linear update type where the value gradually increases from the minimum to maximum value and then jumps back to the minimum:
TRIANGLE
A linear update type where the value gradually increases from the minimum to maximum value and then gradually decreases back to the minimum.
CIRCULAR
An update type for animating rotating objects. It is similar to the SAWTOOTH update type, except that the maximum value is never reached: instead, the value jumps back to the minimum value. This is used for animating rotational angles with the 0-360 degrees interval and makes sure that the rotating object does not "stutter" at the beginning and end of each of the rotational revolution, where the angle value of 360 degrees produces the same result as the value of 0 degrees.
SINE
A update using sine function.
Period
The number of value intervals it takes to change the value from the minimum to maximum value and back. The actual number of iterations for the whole period is bigger by one. For example, for the default period value of 2 the value alternates between the minimal and maximum value. The complete period takes 3 iterations: value=MinValue (iteration 0), value=MaxValue (iteration 1), value=MinValue (iteration2), but the number of intervals is equal to two (see the picture below)
.


The period may be set to a positive or negative value. The sign of the period value defines the timer's behavior when it is disabled. The detailed description is provided below.
Interval
The interval of periodic updates in seconds (default value is 1 second).
MinValue
The minimum data value.
MaxValue
The maximum data value.
Enabled
Disables the timer if set to 0, enables the timer if set to 1.

The timer is active only at run-time or in the prototyping mode. It is disabled in the editing mode for convenience. Internally, the timers are cached for efficiency and only one native timer is used for each collection of timers with the same period. This also synchronizes blinking of objects with the same timer intervals. When the drawing is initially loaded or reset, the timer always starts with the minimum value.

For timers with a positive Period, the timer is always set to the minimum value (MinValue) when disabled. For inversed behavior, simply switch the maximum and minimum values. For example, if MinValue=1 and MaxValue=0, the timer will start from 1 and will also stay at this value when disabled. When the timer is enabled again, it will continue updating in sync with the other timers that have the same period and are not disabled. This synchronizes blinking of objects with the same timer intervals after the timer was disabled and then enabled again.

For timers with a negative Period, the timer keeps its current state when disabled, instead of resetting to the minimum value. When the timer is enabled again, it will continue from the state where it was stopped, which may not match the state of other timers with the same period value.

Divide

The Divide transformation divides the attribute's Value by the value of a scalar divisor and assigns the result to the attribute's transformed value (XfValue). Its only attribute is the divisor itself, called D Parameter.

Linear

The Linear transformation has six attributes called M, A, X, B, Y, and D. The transformation ignores the attribute's Value and sets the attribute's transformed value (XfValue) to the result of the following expression:

M * ( A * X + B * Y ) / D

where M, A, X, B, Y and D are the value of the six transformation attributes.

Compare/Min/Max

A Compare transformation ignores the attribute's Value and sets the attribute's transformed value (XfValue) to the result of the comparison of two input parameters of the transformation. For boolean comparison operations, the output value is set to 1 if the result of the comparison is True, otherwise the output value is set to 0. For min / max comparisons, the output value is set to the smallest or the largest value from the two input parameters.

The transformation has the following attributes:

OP
The comparison operation, may be one of the following:
==
!=
<
<=
>
>=
min
max
A and B Parameters
The input parameters to be compared.
Boolean

A Boolean transformation ignores the attribute's Value and sets the attribute's transformed value (XfValue) to the result of the boolean function of three input parameters of the transformation. If the result of the boolean function is True, the output value is set to 1, otherwise the output value is set to 0. The transformation has the following attributes:

Function
The boolean function, may be one of the following:
 A ||  B ||  C
 A || !B ||  C
 A ||  B || !C
 A || !B || !C
!A ||  B ||  C
!A || !B ||  C
!A ||  B || !C
!A || !B || !C
( A ||  B ) &&  C
( A ||  B ) && !C
( A || !B ) &&  C
( A || !B ) && !C
 A &&  B &&  C
!A &&  B &&  C
 A && !B &&  C
 A &&  B && !C
!A && !B &&  C
!A &&  B && !C
 A && !B && !C
!A && !B && !C
A &&  B ||  C
A && !B ||  C
A &&  B || !C
A && !B || !C
!A
A
A, B and C Parameters
The input parameters of the boolean function.
Boolean Converter ( Bool( var) )
The type of boolean conversion function used to convert double input values to boolean, may be one of the following:
var != 0.                 - True if the input value is not zero
var > 0.                  - True if the input value is positive
var > 0.5                - True if the input value is greater than 0.5
ABS( var ) > 0.5    - True if the absolute value of the input value is greater than 0.5
Bitmask

A Bitmask transformation ignores the attribute's Value and sets the attribute's transformed value (XfValue) to the value formed by interpreting the states of four input parameters as bits of a 4-bit integer (from 0 to 15). A value of each input parameter is converted to a boolean True or False; if the result is True, the corresponding bit in the 4-bit integer output is activated. For example, the following combination of input parameters yields the output value of 13:

Bit 3 = 1
Bit 2 = 1
Bit 1 = 0
Bit 0 = 1

If input parameters are binary signals that represent a state of a device, a bitmask transformation can be used to change an object's color depending on the combination of the input signals. This can be accomplished by attaching a bitmask transformation to an the Index attribute of a list transformation attached to an object's FillColor, and arranging a list of colors to handle all combinations of inputs, depending on the number of used input parameters (2, 3 or 4).

The transformation has the following attributes:

Bit 3
Bit 2
Bit 1
Bit 0
The input parameters of the transformation.
Boolean Converter ( Bool( var) )
The type of boolean conversion function used to convert double input values to boolean, may be one of the following:
var != 0.                 - True if the input value is not zero
var > 0.                  - True if the input value is positive
var > 0.5                - True if the input value is greater than 0.5
ABS( var ) > 0.5    - True if the absolute value of the input value is greater than 0.5
D From G

The D From G transformation extracts an X, Y or Z coordinate (or an R, G or B color value) from a G data object containing a triplet of XYZ or RGB values. It has the following attributes:

Coordinate
The coordinate to extract: X, Y or Z (R, G or B for RGB values).
G Value
The G data object containing an XYZ or RGB triplet.
Screen Factor (ADVANCED)

The Screen Factor transformation may be used to proportionally increase or decrease a scalar attribute depending on zooming and resizing of a parent viewport. It has the following attributes:

Scaling Type
Controls the scaling, may have the following values:
GLG_NO_SCALING - no scaling will be performed on zoom or resize.
GLG_ZOOM_SCALING - the resulting scaling factor will increase or decrease when the viewport is zoomed in or out, or if a parent object is scaled via an attached scale transformation.
GLG_RESIZE_SCALING - the resulting scaling factor will change proportionally to the viewport horizontal extent.
Resize scaling is active only for resizable viewports and is ignored for the fixed size viewports. The BaseWidth attribute of the viewport (or its parent viewport) must be set to a non-zero value which determines the initial viewport width that corresponds to the scaling factor of 1. The resulting scaling factor will increase if the current viewport width is greater than the BaseWidth, and decrease if the current width is smaller. If BaseWidth is set to 0, the base width value will be inherited from the first parent viewport or light viewport with a non-zero BaseWidth. Setting BaseWidth to -1 stops the inheritance.
GLG_ZOOM_AND_RESIZE_SCALING - combines the zoom and resize scaling.
Start Scale
The starting scale to be applied to the effective scaling factor.
Factor
An additional scaling factor to be applied to the effective scaling factor.
Inversed
Inverses the scaling effect to decrease the attribute value when the effective scaling factor increases, and vice versa.

This transformation may be used to scale scalar attributes the same way the zoom and resize scaling works for scaling polygon line width, as well as marker and text sizes.

The effective scaling factor corresponding to the selected scaling type is multiplied by StartScale and Factor before being applied to the attribute value.

String Transformations

There are four string transformations that can be applied only to string attributes. All string transformations ignore the attribute's Value and assign the transformation's output to the attribute's transformed value (XfValue).

String transformations cannot be concatenated: only one string transformation can be attached to a string attribute. However, string transformations can be chained by attaching a string transformation to an attribute of another string transformation.

Refer to the Common Attribute Transformations section on page 186 for additional transformations that can be attached to string attributes.

String Formatting (Format S)

The string formatting transformation formats the string value of the Data attribute according to the formatting instructions in the Format attribute.

Format
A character string specifying how the Data attribute value is to be displayed. The format is specified with the standard C language printf format for strings, for example: "String=%10s". Using formats other than the variants of the %s format is not allowed and may result in a crash.
Escape sequences may be used to define native platform-specific formats for Windows and Unix platforms, as well as Java and C#/.NET environment, as described in the the Scalar Formatting (Format D) section below.
Data
The string data value to write into the text string.
Scalar Formatting (Format D)

The scalar formatting transformation formats the scalar value of the Data attribute with the formatting instructions in the Format attribute. If you constrain the Data attribute to the output value of a slider, you can produce a real-time display of the current slider value.

Format
A character string specifying how the Data attribute is to be displayed. The format is specified with the standard C language printf format. The type of the format specification must match the Format Type attribute. For example, the following format can be used to display a double value:"Value=%.2f".
The following formats are supported:
double formats: %f, %F, %g, %G, %e, %E
integer formats: %d, %x, %X, %o
Using format types that do not match the Format Type attribute is not allowed and may result in a crash.
Escape sequences may be used to define native platform-specific formats for Windows and Unix platforms, as well as Java and C#/.NET environment. The platform-specific formats may be specified by surrounding them with HTML-style brackets:
		<platform>native format</platform>
  
where platform may be one of the following: java, c#, c_unix or c_windows. One or more platform-specific formats may be specified before the generic platform-independent format that will be used for the remaining platforms. For example, the following format uses different native format specifications for C#, Java and C/C++/ActiveX environments:
<c#>{0:N2}</c#><java>%,2f</java>%.2f
In Java, the native format is passed as a format parameter to the format method of a Formatter object. In C# it is passed as a format parameter to the String.Format method for double, integer and string formats, and as a format parameter to the ToString method of a DateTime object for time and data formats.
Data
The scalar data value to write into the text string.
Format Type
The type of the format to use: DOUBLE or INTEGER. If an integer format is used, the data value is first cast to an integer type, with no rounding performed.
Time Format

The time formatting transformation formats the supplied time value with the requested time format.

Time Format
A character string specifying a desired time format ("%X %x" by default). Refer to the description of the axis object's Time Format attribute on page 140 for information on the supported time formats.
Escape sequences may be used to define native platform-specific formats for Windows and Unix platforms, as well as Java and C#/.NET environment, as described in the the Scalar Formatting (Format D) section above.
MilliSec Format
Specifies a double-precision C-style format for an optional display of fractional seconds at the end of the time string in the form of milliseconds. For example, ".%03.0f" will display 270.5 milliseconds as ".270". It may be set to an empty string to suppress milliseconds display.
Time Input
Supplies the time to be displayed measured as the number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC. When the drawing is loaded (or reset), the attribute value is set to the current time and then stays constant until the value of the attribute is set using GlgSetDResource. To display current time, use a negative value: the display will be updated with the current time every time the property is set to a negative value. To automatically update display with current time, use the Time Display and Date Display predefined transformations described on page 195.
Time Display
Specifies how to interpret the value of the Time Input attribute. If set to RELATIVE, the value of the Time Origin attribute will be subtracted from Time Input to display time interval elapsed since the Time Origin. If set to LOCAL or UTC, the time will be displayed as a local or UTC time, respectively.
Time Origin
Specifies the start time to be subtracted from Time Input to display relative time. Refer to the description of the axis object's Time Origin parameter on page 145 for examples of relative time usage.
String Concatenation

The string concatenation transformation replaces the transformed string with the concatenation of the substrings provided as transformation parameters. The string concatenation transformation may be used to create a text object that displays a label, value and units, each controlled by a separate parameter. A Format D transformation may be attached to one of the substring parameters of the transformation to display a numerical value as a string. The transformation has the A, B, C, D, and E parameters that specify strings to be concatenated.

Color Transformations

Since the same G (geometrical) data objects are used to store both RGB color values and XYZ geometrical values, most of the geometrical transformations, such as Move or Scale described above, can also be used for the color attributes. Unlike geometrical transformations, color transformations cannot be concatenated: only one transformation can be attached to a color attribute. However, color transformations can be chained by attaching a transformation to an attribute of a color transformation.

There is one special Color Scale transformation that can be applied only to string attributes. This transformation ignores the attribute's Value and assigns the transformation's output to the attribute's transformed value (XfValue).

Refer to the Common Attribute Transformations section on page 186 for additional transformations that can be attached to color attributes.

Color Scale

The color scale transformation converts a specified base color by either increasing or decreasing its intensity and storing the result as the color attribute's transformed value (XfValue). For example, it can be used to define an object's gradient color as a derivative from the object's color, automatically adjusting the gradient color when the object color changes.

Base Color
Specifies the input color value.
Bright Adjustment
Specifies a scaling coefficient for adjusting bright base colors (colors with brightness higher than the minimum brightness). If a negative value is used, the base color intensity is decreased by that relative value (by 20% for the -0.2 value). Using a positive value increases the base color intensity.
Min Brightness
Specifies a brightness threshold for distinguishing between bright and dark colors. Colors with brightness higher than this value are considered bright, and colors with brightness lower than this value are considered dark. If minimum brightness value is less or equal to 0, all colors will be considered bright.
Dark Adjustment
Specifies a scaling coefficient for adjusting dark base colors (colors with brightness lower than the minimum brightness). If a positive value is used, the base color intensity is increased by that relative value (by 20% for the 0.2 value). Using a negative value decreases the base color intensity.
Preserve Hue
Specifies that the color hue should be preserved when the bright colors intensity is increased so much that some of the RGB component value becomes greater than 1 (maximum RGB value) and are truncated, causing the output color hue to be different from the input color. If Preserve Hue is set to YES, the colors will not be scaled above the threshold that would cause truncating, thus preserving the output color hue.

Common Attribute Transformations

Common attribute transformations can be attached to an attribute of any type: D, S or G. These transformations ignore the attribute's Value and assign the transformation's output to the attribute's transformed value (XfValue). The available types of the common attribute transformations are listed below.

List

The List transformation uses an integer index to select an attribute value from a list. For example, a list of colors may be attached to the Fill Color attribute of an object and the list's Index used to control what color is displayed: the index of 0 will display the first color, the index of 1- the second color, and so on.

The list transformation may be attached to attributes of any type (D, S or G). For example, you can attach a list of strings to be displayed in a text object via the text's String attribute, or attach a table of line widths for the polygon's Line Width attribute.

The attributes for this transformation are as follows:

List of Values
The list of attribute values to use, which may be edited.
Index
The zero-based index controlling which value from the list is displayed.

For color attributes with the list transformation attached, the transformed color value is calculated by adding the color value specified in the list to the value of the attribute. When the transformation is attached in the Builder, the first color in the list is set to the attribute's color, and the attribute's color value is set to a black color (0,0,0) to prevent interference.

SMap
DMap

The SMap and DMap transformations select the transformed output value by matching the input key with the list of key strings and using a matching value from the list of values. The type of the keys is determined by the type of the transformation: D (double) or S (string). The type of the output values is determined by the type of the attribute the transformation is attached to. If no match is found, the value of the last entry in the list of values is used. Same as the list transformation, these transformations may be attached to attributes of any type (D, S or G).

The SMap and DMap transformations have the following attributes:

List of Values
The list of attribute values to use. It may have one more entry than the list of keys: this last entry is used when no match is found.
List of Keys
The list of keys to compare the input key with.
Input Key
The input key that controls which value from the list of values will be displayed.
Precision (DMap only)
Controls the precision used for comparing an input key with the keys in the list of keys. A match is generated if the value of the input key differs from the key it is compared with by an amount which is less than or equal to the specified precision. Use the value of 0 for an exact match.
Threshold

The Threshold transformation compares an input scalar value with the list of thresholds and selects an attribute value from a matching list of values. For example, a threshold transformation containing a list of two threshold values and a list of three colors may be attached to the Fill Color attribute of an object and the threshold's Value used to control what color is displayed: the value less than the first threshold value will display the first color, the value between the first and the second threshold value - the second color, and the value bigger than the second threshold - the third color. Notice that the number of colors is one bigger than the number of threshold values.

The threshold transformation may be attached to attributes of any type (D, S or G). For example, the list of attribute values may be a list of strings to be displayed in a text object's String attribute, or a list of line widths for the polygon's Line Width attribute.

The attributes for this transformation are as follows:

List of Values
The list of attribute values to use, which may be edited. The number of values in the list must be bigger than the number of the threshold values by 1.
Thresholds
The list of threshold values to use, which may be edited. Since a threshold list is processed sequentially using LESS THAN or LESS OR EQUAL comparison, each threshold in the list must be bigger than the previous one.
Value
The value that, after mapping to the list of thresholds, controls which value from the list of attribute values is displayed.
Equal Flag
A flag that controls the threshold comparison mode. It may have values of LESS (use ith attribute of the List of Values if the value is less than ith threshold) or LESS OR EQUAL.
JavaScript

The Java Script transformation allows using an arbitrary Java Script expression to generate an output value of the transformation based on a variable number of input parameters. The transformation may be attached to an attribute of any type (D, S or G) and may be used to provide a custom transforming function when there are no other suitable transformation types available.

The Java Script transformation has the following attributes:

Java Script
The Java Script expression.
Arg List
The list of input parameters. The list can be edited to add or delete parameters from the list.

The Java Script expression can use input parameters provided by the argument list, referencing them using the $N notation, where N is a 1-based argument index. For example, $1 is the first argument in the argument list, $2 is the second argument, and so on. Referencing an argument that is not in the argument list generates an error.

The return value of the Java Script expression should match the type of the attribute the transformation is attached to, returning a numerical value for D (double) attributes, or string for S (string) attributes. For G attributes, such as XYZ points or RGB colors, a variable with the x, y and z fields must be returned. An error is generated in case of a return type mismatch.

The following shows examples of Java Script expressions with different types of return values that can be used with different types of attributes:

$1 * Math.sin( $2 / 180. * Math.PI )                /* D attribute */
$1 < ( $2 + $3) ? "Value is too small" : "OK"       /* S attribute */
var xyz= {x:$1, y:$2+$3, z:0}; xyz                  /* G attribute */
var rgb= {}; rgb.x=$1; rgb.y=$2+$3; rgb.z=0; rgb /* G attribute */

If a JavaScript transformation attached to an S attribute generates a string containing non-ASCII characters, the UTF8Encoding flag of the attribute must be set to properly handle the string in the Builder and the C/C++ environment.

An external script file can be used to define common script functions that can be used in the JavaScript expression. A global script file can be defined for all programming environment other than JavaScript by setting the GlgJavaScriptFile global configuration resource. In the JavaScript environment, a global script file may be included in the HTML page. For the GLG editors and C/C++ programs, a global script file can also be supplied by using either the -glg-java-script-file command-line option or the GLG_JAVA_SCRIPT_FILE environment variable (setting the environment variable also affects the GLG ActiveX Control on Windows).

In the C/C++, Java and C# environments, an external JavaScript file can also be associated with a particular drawing by using the JavaScript File property of the drawing's viewport. While the global script file is loaded on the application startup, the script file associated with a drawing will be loaded only when the drawing is loaded.

A List transformation can be attached to the transformation's JavaScript attribute to execute different scripts depending on the value of the List's Value Index parameter.

The Toolkit uses a single JavaScript context for all Java Script expressions and external script files. Global variables and functions should be named to avoid ambiguity and minimize the risk of naming collisions. In case of a name collision, the later definition overwrites the earlier one.

For performance optimization, the JavaScript expressions are pre-parsed when the drawing hierarchy is set up. The JavaScript transformation is also optimized to execute JavaScript expressions only when the arguments in the Argument List change.

In the C/C++ environment, there are two modes for checking the use of arguments in the JavaScript expressions: strict and relaxed. The strict mode is slower, but catches more errors of improper argument use compared to the relaxed mode. By default, the GLG editors use the strict mode to catch more errors at design time. The relaxed mode is used by default by the GLG library at run time for faster execution. The argument use mode can be changed by setting the value of the GlgJavaScriptArgCheck global configuration resource to 1 for the strict mode, or to 0 for the relaxed mode.

The type of the JavaScript engine used to evaluate JavaScript depends on the programming environment. The GLG editors and the GLG C/C++ libraries use the Duktape JavaScript interpreter1. In C#, the Jurrasic JavaScript interpreter2 is used, and a native JavaScript engine is used in the Java version.

Transfer

The Transfer transformation is used to transfer a value from one attribute object to another. It can be used to implement a "one-way" constraint, where changes in one object affect another, but not vice versa. The transfer transformation may be attached to an attribute of any type (D, S or G). This transformation is disabled in the Graphics Builder by default; set EnableAdvancedTransforms=1 in the glg_config file to enable it.

The transfer transformation has the following attributes:

Source
Constrain this attribute to the "source" attribute. Its value is passed into the Buffer attribute.
Buffer
If you want to attach a transformation to this transfer, attach it to this attribute. The transformation will alter the transferred value without affecting the source value.
Use Value
If set to Value, the Value of the Source attribute before applying any attribute transformations is used. If set to XfValue (default), the transformed value of the Source attribute is used. The transformed value includes an effect of all transformations (if any) attached to the attribute.

An example of a transfer's use will make it clear. You can use a transfer transformation to set the line width of one polygon equal to a half of the line width of another. Name the first polygon PY1, and the second PY2. Attach a transfer transformation to the LineWidth attribute of PY1. Constrain the Source attribute of the transformation to the LineWidth attribute of PY2. Now attach the Divide transformation to the Buffer attribute of the Transfer transformation, and set its D attribute to 2. The LineWidth of PY1 is now constrained to be one half of the value of the PY2 LineWidth attribute.

Identity

An Identity transformation ignores the attribute's Value and sets the attribute's output value to the value of the transformation's Source attribute, which is its only attribute. The type of the Source attribute matches the type of the attribute the transformation is attached too.This transformation is used for the internal design of the GLG Control Widgets and is disabled in the Graphics Builder by default; set EnableAdvancedTransforms=1 in the glg_config file to enable it.

Predefined Dynamics

In addition to the stock transformation types listed above, predefined dynamics options are provided in the Builder for convenience. Predefined dynamics provide easy to use options for implementing the most common dynamic actions, for example Blinking Alert. The parameters of predefined dynamics are presented to the user as a simple list of public properties that define the its dynamic behavior.

Predefined dynamics is implemented using custom transformations, which represent a collection of several transformations wired together to implement a specific dynamic behavior, and present it to a user as a simple list of public properties that define its parameters. Custom transformations may be used by the system integrators to extend GLG editors with elaborate application-specific dynamics. The Export Property feature of the OEM version of the Graphics Builder is used to define custom transformations.

The dynamics are attached to the object attributes and edited the same way as any other dynamic transformation. Predefined dynamics available in the Builder are listed below.

Color List

The Color List dynamics uses an integer index to select a color from a list. It works the same way as the List transformation and differs only in the way it lists its properties. It has the following properties:

ColorN
Colors to be used, where N is a zero-based color index.
ColorIndex
The zero-based index controlling which color to use.
Color Threshold

The Color Threshold dynamics compares an input scalar value with the list of thresholds and selects a corresponding color from a list of colors. It works the same way as the Threshold transformation and differs only in the way it lists its properties. It has the following properties:

ColorN
Colors to be used, where N is a zero-based color index.
ThresholdN
Thresholds to be used, where N is a zero-based threshold index. Threshold values must be specified in the increasing order.
InputValue
This value is compared with the thresholds and controls which color to use. The color corresponding to the first threshold smaller than the input value is used.
Color Blinking

The Color Blinking dynamics alternates an attribute's color between the two specified colors. It has the following properties:

Enabled
Enables or disables blinking. When set to 0, the blinking is disabled and the OffColor is displayed.
Interval
The blinking interval in seconds.
OnColor
The first color.
OffColor
The second color.
Color Blinking Alert

The Color Blinking Alert dynamics alternates the attribute's color between the default and alarm colors when the monitored value goes out of the specified range. It has the following properties:

ActivateOnEqual
If set to 1 (True), the color is changed when the input value is equal to or exceeds the specified range. If set to 0 (False), the color is changed only when the value exceeds the range.
InputValue
The monitored value.
Interval
The blinking interval in seconds.
OnColor
The first color.
OffColor
The second color.
RangeHigh
The High range.
RangeLow
The Low range.
Color Alert

The Color Alert dynamics changes an attribute's color when the monitored value goes out of the specified range. It has the following properties:

ActivateOnEqual
If set to 1 (True), blinking starts when the input value is equal to or exceeds the specified range. If set to 0 (False), blinking starts only when the value exceeds the range.
ColorOK
The default color to use when the value is inside the Low / High range.
ColorWarning
The color to use when the value goes outside of the Low / High range.
ColorAlarm
The color to use when the value goes outside of the LowLow / HighHigh range.
InputValue
The monitored value.
RangeHigh
The High range.
RangeHighHigh
The HighHigh range.
RangeLow
The Low range.
RangeLowLow
The LowLow range.
List

The List dynamics uses an integer index to select an attribute value from a list. It works the same way as the List transformation and differs only in the way it lists its properties. It may be applied to attributes of either D (double) or S (string) type and has the following properties:

ListIndex
The zero-based index controlling which attribute value to use.
ValueN or TextStringN
Attribute values or text strings to be used, where N is a zero-based value or string index.
Threshold

The Threshold dynamics compares an input scalar value with the list of thresholds and selects a corresponding attribute value from a list of values. It works the same way as the Threshold transformation and differs only in the way it lists its properties. It may be applied to attributes of either D (double) or S (string) type and has the following properties:

InputValue
This value is compared with the thresholds and controls which attribute value to use. The value corresponding to the first threshold smaller than the input value is used.
ThresholdN
Thresholds to be used, where N is a zero-based threshold index.The thresholds must be specified in the order of increasing their values.
ValueN or TextStringN
Attribute values or text strings to be used, where N is a zero-based value or string index.
Blinking

The Blinking dynamics alternates an attribute's value between the two specified values. It may be attached to any attribute of D type (double), including the object's visibility. It has the following properties:

Enabled
Enables or disabled blinking. When set to 0, the blinking is disabled and the OffValue is displayed.
Interval
The blinking interval in seconds.
OnValue
The first color.
OffValue
The second color.
Range Alert

The Range Alert dynamics changes the attribute's value when the monitored value goes out of the specified range. It has the following properties:

ActivateOnEqual
If set to 1 (True), the attribute's value is changed when the input value is equal to or exceeds the specified range. If set to 0 (False), the value is changed only when the input value exceeds the range.
InputValue
The monitored value.
ValueOK
The value to use when the value is inside the Low / High range.
ValueWarning
The value to use when the value goes outside of the Low / High range.
ValueAlarm
The value to use when the value goes outside of the LowLow / HighHigh range.
RangeHighHigh
The HighHigh range.
RangeHigh
The High range.
RangeLow
The Low range.
RangeLowLow
The LowLow range.

The ValueWarning, RangeHighHigh and RangeLowLow properties are not present in the Range Alert dynamics attached to the Visibility attribute, since visibility has only two states: ON and OFF.

Blinking Alert

The Blinking Alert dynamics alternates the attribute's value when the monitored value goes out of the specified range. It has the following properties:

ActivateOnEqual
If set to 1 (True), blinking starts when the input value is equal to or exceeds the specified range. If set to 0 (False), blinking starts only when the value exceeds the range.
InputValue
The monitored value.
Interval
The blinking interval in seconds.
OnValue
The value to use for blinking when the value goes outside of the range.
OffValue
The default value to use when the value is inside the range.
RangeHigh
The High range.
RangeLow
The Low range.
VisibilityThreshold

The Visibility Threshold dynamics compares an input scalar value with the specified threshold and sets the object visibility to a matching value. It has the following properties:

InputValue
This value is compared with the threshold and controls which attribute value to use.
Threshold
The threshold.
VisState0
The visibility value to use when the input value is less than the threshold. May be set to 0 or 1.
VisState0
The visibility value to use when the input value is less than the threshold. May be set to 0 or 1.
Value Display

The Value Display dynamics may be attached to the TextString attribute of text objects to display a numerical value using the specified format. It has the following properties:

InputValue
The value to be displayed.
Label
The label used to annotate the value.
MinLength
The minimum number of characters used to display the value. If the number of characters is less than MinLength, the value is padded with spaces on the left.
Precision
The number of digits after the decimal point in the value display.
Separator
The string used as a separator between the label and the value.
Units
The unit string displayed after the value.
UnitsSeparator
The string used as a separator between the value and the unit string.
Text Display

The Text Display dynamics may be attached to the TextString attribute of text objects to display a string using the specified format. It has the following properties:

InputString
The string to be displayed.
Label
The label used to annotate the string value.
MinLength
The minimum number of characters used to display the string. If the number of characters is less than MinLength, the string is padded with spaces on the left.
Separator
The string used as a separator between the label and the string.
Suffix
The second annotation displayed after the string.
SuffixSeparator
The string used as a separator between the string and the suffix.
Time Display

The Time Display dynamics may be attached to the TextString attribute of text objects to display the current time. It has the following properties:

Enabled
Enables or disables time updates. In the Builder, use the Run mode to see updates of the time display.
TimeFormat
A character string specifying a desired time format ("%X" by default). Refer to the description of the axis object's Time Format attribute on page 140 for information on the supported time formats.
TimeLabel
A label appended to the displayed time string.
UTCFlag
If set to 1, the UTC time will be displayed. Otherwise, a local time will be shown.
UpdateInterval
Update interval in seconds (1 by default).
Date Display

The Date Display dynamics may be attached to the TextString attribute of text objects to display the current date. It has the following properties:

Enabled
Enables or disables time updates. In the Builder, use the Run mode to see updates of the time display.
DateFormat
A character string specifying a desired date format ("%x" by default). Refer to the description of the axis object's Time Format attribute on page 140 for information on the supported time formats.
DateLabel
A label appended to the displayed time string.
UpdateInterval
Update interval in seconds (1 by default).
JavaScript

The JavaScript dynamics allows using an arbitrary JavaScript expression to generate an output values of the transformation based on values of its input parameters. While a JavaScript transformation can be applied to attributes of any type (D, S or G), a Predefined Dynamics option for the JavaScript dynamics is provided only for the D (double) and S (string) attributes by default. The dynamics has the following properties:

ArgN
Input parameters, where N is 1-based index of the input parameter.
JavaScript
The JavaScript expression.

Refer to the JavaScript section on page 187 for information on using input parameters in the JavaScript expression and examples of the JavaScript syntax.

Flow

The Flow dynamics may be attached to the LineType attribute of lines and polygons to visualize flow of gases and liquids through pipes. The dynamics shifts a line type pattern along the length of the line to animate the flow. It has the following properties:

DisabledLineType
The line type used to visualize the pipe when the flow is disabled. The default value is 0 (solid line).
EnabledLineType
The line type pattern used for animation when the flow is enabled.
FlowEnabled
Enables of disables the flow animation. When set to 0, the flow is disabled.
FlowInterval
Controls the flow speed by defining a timer interval (in milliseconds) between the flow updates. The default value is 0.1.
FlowInversed
Inverses the flow direction if set to 1. The default value is 0 (direct flow).

Alarm Object

The alarm object can be attached to a data or attribute object to monitor its value. The alarm object defines the normal range of the monitored value and generates an alarm message when the value goes outside of the normal range. There is also a type of alarm that generates a message every time the monitored value changes.

Internally, the alarm object is implemented as a special type of a transformation object and its attributes follow the same convention for the default attribute names.

While alarm attributes depend on the type of alarm as described in the following sections, all alarm objects share the following common attributes:

Alarm Label
Contains a user-defined label used to identify the alarm.
Enabled
Used to enable or disable the alarm by setting its value to 1 or 0, respectively.

The rest of the alarm attributes depend on the alarm type and are described in the following sections.

Alarm Messages

Alarm objects generate alarm messages when changes of the monitored value trigger a specified alarm condition. Alarm messages are processed by an alarm handler which is installed by using the GlgSetAlarmHandler API method described on page 86 of the GLG Programming Reference Manual. Each message contains Action and SubAction parameters that indicate the condition that generated the message. The message also contains AlarmLabel, as well as the alarm object and the attribute object whose value change triggered the alarm.

There are two types of alarm messages: messages that indicate the state of readiness of the alarm object, and messages that reflect the alarm state of the monitored value. The following alarm messages are generated by all alarm objects to reflect readiness of the alarm object:

When an alarm is armed and enabled, it generates alarm messages when changes of the monitored attribute value trigger the alarm condition. These messages vary depending on the alarm type and are described in the following sections.

Range Alarm

The Range alarm can be attached to an attribute of a D type (double) to monitor its value. The alarm message is generated when the value goes below or above the specified High/Low range.

The range alarm has the following attributes:

Use Value
If set to Value (default), the value of the attribute before applying any attribute transformations is used. If set to XfValue, the transformed value of the attribute is used. The transformed value includes an effect of all transformations (if any) attached to the attribute.
High
Defines the high range of the value. The alarm message with the High subaction is generated when the value reaches or exceeds the High range.
Low
Defines the low range of the value. The alarm message with the Low subaction is generated when the value drops below or equal to the Low range.

The Range alarm generates the following alarm messages:

Range2 Alarm

This alarm is similar to the Range alarm, but adds the following attributes that define second thresholds in addition to High and Low:

High High
Defines the high high range of the value. The alarm message with the HighHigh subaction is generated when the value reaches or exceeds the HighHigh range.
Low Low
Defines the low low range of the value. The alarm message with the LowLow subaction is generated when the value drops below or equal to the LowLow range.

The alarm generates the same messages as the Range alarm, with the addition of the alarm messages with the HighHigh and LowLow subactions for the corresponding alarm states.

Change Alarm

The Change alarm can be attached to an attribute of any type (D, S or G) to monitor changes of its value. The change alarm does not define any new attributes in addition to Alarm Label and Enabled.

The Change alarm generates an alarm message with the ValueChange action and NULL subaction every time the value is changed.

Action Object

An action can be attached to a graphical object to perform a specified action when user interacts with the object at run-time. There are three types of actions that differ based on the activation conditions:

The type of an action is determined by its Trigger attribute which is set at the time the action is attached to an object. The trigger attribute may be set to either MOUSE_CLICK or MOUSE_OVER for mouse actions, and is always set to INPUT for input actions, and TOOLTIP for tooltip actions. A viewport's ProcessMouse attribute must be set to a value that includes a combination of Click, Move and Tooltip masks to enable processing corresponding mouse actions.

There are also several types of action objects based on the type of activity performed when the action is triggered:

Mouse feedback action
Mouse feedback actions are used to change appearance of an object without writing any application code. For example, it may be used to highlight an object on mouse click or mouse over by changing its LineWidth or FillColor attribute. Mouse feedback actions have a State parameter; the value of the parameter is set by the action depending on the requested mouse activation condition.

To change an object's appearance, the State parameter of the action should be constrained to some attribute of the object. For example, to change the object's color on mouse over, State can be constrained to the index of a color list transformation attached to the object's FillColor attribute.

There are several types of available feedback:
TRACE_STATE
Traces the state of the mouse click on the object or the mouse being over the object (as requested by the action's Trigger parameter) by setting the action's State parameter to 1 or 0. It can also trace the state of the Control key if the action's ProcessArmed parameter is set to ARMED_AND_UNARMED, in which case the value of State will be set to 1 if the mouse activation condition specified by Trigger are met and the Control key is not pressed, and to 2 of the Control key is pressed. See page 202 for more information.
SET_STATE
Sets the action's State attribute to 1 when the action's activation conditions are met.
RESET_STATE
Resets the action's State attribute to 0 when the action's activation conditions are met.
TOGGLE_STATE
Toggle the action's State attribute every time the action is activated.
The TRACE_STATE feedback type is usually used to provide a visual feedback when the object is selected with a mouse click or a mouse over event. The SET_STATE and RESET_STATE feedback types allow the application to use a graphical object as a button that sets or resets the state of some other object in the drawing, without the use of button input objects, while the TOGGLE_STATE allows the application to use an object as a toggle button.
Advanced: Mouse feedback actions automatically update the viewport that contains the object to which the mouse feedback action is attached. If the action's State attribute is constrained to an object in a different viewport (that is not a child of the viewport containing the object with the action), that viewport will not be updated. The feedback actions generates an UpdateDrawing, which can be processed in the input callback to update the top-level or sibling viewport that contains the constrained object, if required. Refer to the Handling Action Object Messages and Commands in Application Code at Run Time section on page 212 for more information.

Advanced: At run time, the drawing traces the mouse position and the state of mouse buttons, processing matching actions when objects are selected with the mouse. Matching of action conditions is performed based on the settings of an action's Trigger attribute (MOUSE_OVER or MOUSE_CLICK), as well as the values of its ProcessArmed, ProcessDoubleClick and MouseButton attributes.

In cases when several intersecting objects are potentially selected, all objects are searched for matching actions to be executed, with objects drawn on top being searched first. When an object with any matching actions is found, the object's actions are processed and any further search for matching actions attached to other objects is stopped. Only visible objects are included in the search, with the exception of invisible objects with the MOUSE_OVER actions and a visible parent. For such objects, SET_STATE, RESET_STATE or TRACE_STATE actions attached to the object or its parents will still be processed to make it possible to draw the object when the mouse moves over it and erase it when it moves away.

If an object is a child of a container, such as a group or a viewport, the object at the bottom of the hierarchy is searched first, then the container and all of its ancestors are searched. When an object with any matching actions is found, the object's actions are processed and any further search up the hierarchy tree is stopped.

When an object's actions are processed, all matching SET_STATE, RESET_STATE and TOGGLE_STATE actions attached to the object are executed first, if any. Then the first matching TRACE_STATE action and the first matching SEND_EVENT action are executed, if any. Finally, all matching SEND_COMMAND actions are executed, if any.

When processing actions, the old-style (prior to v. 3.5) custom events and mouse feedback properties of the drawing are handled the same way as actions: the action processing stops when the first property matching the event has been processed. For example, is an object has the MouseClickEvent property, a custom event will be generated and the search for the mouse click event actions will stop.

The action object provides a more efficient alternative to the old-style custom events, mouse feedback and tooltip properties (such as MouseClickEvent, TooltipString, etc.) since it does not involve resource name queries required by these properties. If the drawing does not contain the old-style properties, the GlgDisablePre35ObjectEvents global configuration resource or the GLG_DISABLE_PRE35_OBJECT_EVENTS environment variable may be set to speed up mouse move processing for large drawings.

Action Object Attributes

Most of the action attributes are common across all available action types, with the exception of the tooltip action that has only two attributes: Tooltip and Enabled. The following lists all attributes of an action object:

ActionType
Defines the type of the action performed when the action is triggered, may have one of the following values:
SEND_EVENT
Generates a custom event with the event label defined by the action's EventLabel attribute. The custom event provides backward compatibility with the custom event handling code from previous releases of the Toolkit. Additional custom data needed by an application may be held in the ActionData container, which can be accessed via the Add Data or Edit Data button in the Builder. The action also allows the user to define an arbitrary set of action data, which is different from the SEND_COMMAND action that uses predefined sets of data for each command type.
If the action's ProcessArmed attribute is set to ARMED_ONLY, a custom event will be generated only if the Control key was held down, and if ProcessArmed=UNARMED_ONLY, the custom event will be generated only if the Control key is not pressed. If ProcessArmed=ARMED_AND_UNARMED, the event will be sent regardless of the state of the Control key, but the SubAction resource of the message object in the input callback will be set to "Armed" if the Control key was pressed, and unset (an empty string) otherwise.
If the action's ProcessDoubleClick attribute is set to DOUBLE_CLICK_ONLY, a custom event will be generated only on a double click. If ProcessDoubleClick= SINGLE_CLICK_ONLY, a custom event will be generated only on a single click (that includes the first click of the double-click sequence).
If ProcessArmed=SINGLE_AND_DOUBLE, an event will be sent on either a single or double click. The Action resource of the message object in the input callback will be set to "MouseClick" or "DoubleClick" depending on the type of the click that generated the event.
The ProcessDoubleClick=NONE setting can be used to always report "MouseClick" regardless of the type of the click. This is the default setting which also guarantees compatibility with the source code that was used with the previous versions of the Toolkit.
Refer to the Handling Action Object Messages and Commands in Application Code at Run Time section on page 212 for information on using handling custom events in the application code at run time.
SEND_COMMAND
Generates a command event with a Command object containing command type, as well as data required to execute the command. The command data are held in the Command container, which is accessible via the Edit Command button in the Builder.
When a command action is created, the Builder prompts the user to select a command from a list of several predefined command types, and then displays the Properties dialog for the selected command. Refer to the Command Object section on page 208 for the list of the predefined command types. The set of predefined command types may be extended by adding custom commands to the list, see the Custom Data Sets and Custom Commands section on page 340 for more information.
For ProcessArmed=ARMED_ONLY, the command will be triggered only if the Control key was held down, and for UNARMED_ONLY, the command will be sent only if the Control key was not pressed. If ProcessArmed=ARMED_AND_UNARMED, the command will be sent regardless of the state of the Control key, but the SubAction resource of the message object in the input callback will be set to "Armed" if the Control key was pressed, and unset (an empty string) otherwise.
Same as for the SEND_EVENT action type, the ProcessDoubleClick attribute controls if the command is triggered on a single click, a double click or both.
Refer to the Handling Action Object Messages and Commands in Application Code at Run Time section on page 212 for information on using command actions in the application code at run time.
TRACE_STATE
Traces the mouse events and sets the action's State attribute depending on the action's Trigger:
Trigger = MOUSE_CLICK
If ProcessArmed=NONE, sets State to 1 when the object is clicked with the mouse button specified with the MouseButton attribute, and resets State back to 0 when the mouse button is released.
If ProcessArmed=ARMED_ONLY, the value of State is changed to 1 only if the Control key is pressed down when the mouse click occurs, and is reset back to 0 if either the Control key or the mouse button is released.
If ProcessArmed=UNARMED_ONLY, the value of State is changed to 1 only if the Control key is not pressed when the mouse click occurs, and is reset back to 0 if the either the Control key is pressed or the mouse button is released.
If ProcessArmed=ARMED_AND_UNARMED, the State changes to 1 on the mouse click without the Control key, or to 2 if the Control key was held down. The State returns back to 1 when the Control key is released, and to 0 when the mouse button is released.
The ProcessDoubleClick attribute controls if the state change occurs on a single click, a double click or both.
Trigger = MOUSE_OVER
If ProcessArmed=NONE, sets State to 1 when the mouse moves over the object and resets State back to 0 when the mouse moves away from the object.
If ProcessArmed=ARMED_ONLY, the value of State is changed to 1 only if the Control key is pressed down and the mouse is positioned on top of the object.
If ProcessArmed=UNARMED_ONLY, the value of State is changed to 1 only if the Control key is not pressed and the mouse is positioned on top of the object.
If ProcessArmed=ARMED_AND_UNARMED, the State changes to 1 when the mouse moves over the object without the Control key, or to 2 if the Control key is held down while the mouse is positioned on top of the object. The State returns back to 1 when the Control key is released, and to 0 when the mouse moves away from the object.
SET_STATE
RESET_STATE
SET_STATE sets the action's State attribute to 1 when the action is triggered, and RESET_STATE resets it to 0.
If ProcessArmed is set to ARMED_ONLY or UNARMED_ONLY, the action is activated only if the Control key is in a matching state: is held down for ARMED_ONLY or released for UNARMED_ONLY. The ProcessDoubleClick attribute controls if the state change occurs on a single click, a double click or both.
TOGGLE_STATE
Toggles the action's State attribute between 0 and 1 every time the action is triggered.
If ProcessArmed is set to ARMED_ONLY or UNARMED_ONLY, the action is activated only if the Control key is in a matching state: held down for ARMED_ONLY or released for UNARMED_ONLY. Only the MOUSE_CLICK trigger is supported for TOGGLE_STATE. The ProcessDoubleClick attribute controls if the state change occurs on a single click, a double click or both.
Trigger
Specifies an action's activation condition, may have one the following values:
MOUSE_CLICK
Activates the action when the object is selected with the mouse button specified by the MouseButton attribute. The ProcessArmed attribute may be used to handle the state of the Control key, and the setting of the ProcessDoubleClick attribute may be used to differentiate between single and double clicks.

A viewport's ProcessMouse attribute must contain the Click mask for the action to be processed.
MOUSE_OVER
Activates the action when the mouse moves over the object. The ProcessArmed attribute may be used to handle the state of the Control key.

A viewport's ProcessMouse attribute must contain the Move mask for the action to be processed.
INPUT (for input actions only)
Activates an action attached to an input object when activity specified by the InputAction is detected. For example, InputAction=ValueChanged may be used to activate the action attached to a slider every time the slider value is changed.

The value of the InputAction attribute is a string that matches the Action resource of a message object received in the input callback. The action's InputSubAction attribute may be used to match the SubAction attribute of the message object is required.

Input actions may be used to effectively translate user interaction with input objects into encapsulated action commands that may also contain additional data needed for executing the command. For example, a GoTo command contains a DrawingFile parameter that specifies the drawing to navigate to.

The use of input actions makes it possible to attach well-defined commands to input objects, instead of using input object names for handling user interaction. In the previous releases of the Toolkit (prior to v. 3.5), an application code in the input callback had to use input object names and the Action / SubAction parameters of the message object to determine the action to be performed. Using input actions, the code can handle a set of predefined commands that are completely defined in the drawing,
making the code more generic and independent of object names.

Refer to the Handling Action Object Messages and Commands in Application Code at Run Time section on page 212 for information on using input actions in the application code at run time.
TOOLTIP (for tooltip actions only)
Displays a tooltip when the mouse is hovering over an object. The value of the attribute is set at the creation time when the tooltip action is attached to an object, and the Trigger attribute is not shown in the tooltip action's properties.
ProcessArmed (mouse actions only)
Modifies an action's activation condition to check the state of the Control key. In mission-critical applications, the Control key is often used to "arm" the action, so that it could be activated ("armed") only if the Control key is held down and inactive ("disarmed") if the Control key is not pressed. The attribute may have one the following values:
NONE
An action may be activated regardless of the state of the Control key.
ARMED_ONLY
An action may be activated only if the Control key is held down.
UNARMED_ONLY
An action may be activated only if the Control key is not held down.
ARMED_AND_UNARMED
Modifies action behavior depending on the action type. For TRACE STATE actions, it sets its State attribute to different values (1 or 2) when an action is activated depending on the state of the Control key. For the SEND_COMMAND and SEND_EVENT action types, it reports the state of the Control key in the SubAction parameter of the input callback message object: "Armed" if the Control key is pressed, or unset (an empty string) otherwise. For other action types, this setting is the same as NONE.
ProcessDoubleClick (mouse actions only)
Modifies an action's activation condition to differentiate between single and double clicks. The attribute may have one the following values:
NONE
An action is activated on either single or double click and all clicks are reported as single clicks. This is the default setting that also provides source code compatibility with the pre-3.7 versions of the Toolkit. The GlgGetModifierState method can still be used in the application code to differentiate between single and double clicks.
DOUBLE_CLICKS_ONLY
An action is activated only on double clicks and double clicks are reported in the Action parameter of the input callback message object as "DoubleClick".
SINGLE_CLICKS_ONLY
An action is activated only on single clicks. For a double click sequences, the action will be activated on the first click of the double click sequence, but not on the second click.
SINGLE_AND_DOUBLE_CLICKS
An action is activated on either a single or double click, but double clicks are reported in the Action parameter of the input callback message object as "DoubleClick" vs. "MouseClick" for single clicks.
The double click settings can be adjusted via the GlgDoubleClickTimeout and GlgDoubleClickDelta global configuration resources described on page 425 of Appendix A: Global Configuration Resources of the GLG Programming Reference Manual.
MouseButton (mouse click actions only)
Specifies the index of the mouse button (0, 1 or 2) that will trigger the action for actions with the MOUSE_CLICK trigger.
Enabled
Enables or disables the action when is set to 1 or 0.
EventLabel (SEND_EVENT and SEND_COMMAND actions only)
Defines an event label string that will be available in the input callback as the EventLabel resource of the message ob