PREV NEXT

Generic Logic, Inc. www.genlogic.com


6 Using the GLG Graphics Builder

The GLG Graphics Builder is a tool that provides an interactive way to create or modify a GLG drawing. The Builder enables you to add new objects to a drawing, and to manipulate the graphical objects in the drawing. It provides access to the attributes of the graphical objects and their transformations. The Builder also includes a facility for testing the animation of a drawing.

Before you begin to use the Builder, we strongly recommend that you familiarize yourself with the structure and contents of GLG drawings; see the Structure of a GLG Drawing and GLG Objects. It is also recommended to go through the GLG Builder and Animation Tutorial to familiarize yourself with the basic editing operations.

This guide explains how to use the GLG Graphics Builder, outlining some of the basic tasks in creating and editing GLG drawings:
Task
Page

Visualize the structure of a drawing

page 265

Start the Builder, and identify its features

page 267

Create a drawing and add objects to it

page 265

Edit an object, including changing its geometry and setting its attributes

page 277

Create constraints between object attributes

page 285

Add dynamics to objects and attributes

page 289

Define objects as resources, and arrange them in a hierarchy

page 296

Add tags for database connectivity

page 300

Add alarms to monitor data values

page 304

Animate a drawing

page 306

Work with advanced objects

page 315

Creating and animating objects: a tutorial example

page 325

The GLG Builder also provides scripting capabilities for creating and editing drawings in a batch mode. Refer to GLG Programming Tools and Utilities of the GLG Programming Reference for details on using the Builder in scripting mode.

Creating a Drawing

Before you start the Builder, we suggest that you determine the general content and overall organization of the drawing you plan to create. Identify the parts you want to animate, and the resources you intend to name. Planning your drawing makes the drawing more efficient, and saves you time.

Viewing a GLG Drawing

A GLG drawing is an abstract hierarchy of objects. The hierarchy defines the relationships between the objects in a drawing and their attributes, which define their appearance and behavior.

When you open a GLG drawing in the Builder, the Builder reads the object hierarchy information in the drawing, using it to render a set of visible graphical objects in its drawing area. Because only part of the object hierarchy is composed of visible graphical shapes, the Builder can only present a partial view of the object hierarchy. The Builder shows the graphical shapes that make up the visible part of the drawing (polygons, lines, and the like) in its drawing area.

As you draw shapes in the Builder, set their attributes, and add transformations to them, you are constructing the hierarchy of objects that make up a drawing. The Builder uses dialogs to provide access to the other, non-graphical objects that are subordinate to the graphical objects, such as transformations and attributes.

In general, the Builder restricts the use of the term object to visible, selectable shapes that appear in the drawing area. An object immediately below such a shape in the object hierarchy is described as an attribute (though it is usually an object, too). An object may be defined as a resource by naming it. A member of an advanced object such as a group may be called a subobject. In the Builder, the words attribute and property are synonymous.

Viewing the Object Hierarchy

Because the Builder is a visual and interactive tool, it presents the drawing as a set of visible shapes that can be selected and edited. This focus on graphical objects - the shapes that make up the drawing - has the effect that the complete object hierarchy can be difficult to visualize in the Builder interface.

Although there is no single representation of the object hierarchy, several partial views are available:

Starting and Stopping the Builder

The bin subdirectory of the GLG installation contains executables of one or more GLG editors:

<glg>/bin/
	GlgBuilder
	GlgHMIEditor

If a GLG Editor is started from a command line, it starts in the OpenGL mode and uses the OpenGL driver, if it is available. The bin directory also contains links (shortcuts on Windows) for starting a GLG Editor in non-OpenGL (GDI) mode:

GlgBuilder_no_opengl
GlgHMIEditor_no_opengl

For the Enterprise Edition of the Graphics Builder, the bin directory also contains links for starting the Builder in the OEM mode:

GlgBuilder_OEM_no_opengl
GlgBuilder_OEM_no_opengl

Instead of using links, command options listed below may be used to specify the OpenGL or OEM mode.

To load a specific drawing file on startup, specify the drawing file name:

GlgBuilder filename

If multiple drawings are specified, the first drawing is loaded in the Builder, and the rest of the drawings are added to the File, Recent Drawings menu. Wild cards may be used in the filename to preload files into the Recent Drawings menu for easier navigation between drawings.

For Windows users, a GLG Editor may be started by choosing GLG Graphics Builder or GLG HMI Configurator from the Start Menu. The Start menu contains two separate folders: one for the OpenGL and another for the GDI version of the Toolkit.

Command-line Options

A number of command-line options and environment variables are also supported. The most common options are:

-help
Prints all available command-line options on the terminal.
On Windows, writes command-line option information to the glg_error.log file. The location of the file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in the Error Processing and Debugging section on page 49 of the GLG Programming Reference Manual.
-verbose
Generates diagnostic output for troubleshooting the OpenGL driver, editor setup, loadable editor extension DLLs and other editor extensions.

On Windows, the output is saved in the glg_error.log file. The location of the file is determined by the GLG_LOG_DIR and GLG_DIR environment variables as described in the Error Processing and Debugging section on page 49 of the GLG Programming Reference Manual.
-config-file <filepath>
Specifies an alternative glg_config file to use.
-oem
Starts the Enterprise Edition of the Graphics Builder in the OEM mode.
-widget-editing-mode
In this mode, widgets loaded from the palettes with Ctrl+click can be saved into the original drawing files, facilitating convenient editing of widgets in the custom widget palettes. Without this option, a copy of a modified widget is saved in the current directory by default, to avoid permanently overwriting widgets in the GLG Builder palettes.
-glg-java-script-file <filepath>
Specifies a global JavaScript file.
-glg-disable-opengl
Disables OpenGL renderer in favor of the native windowing renderer.
-glg-enable-opengl
Enables OpenGL renderer if present. The OpenGL renderer will be used only for the viewports which have their OpenGLHint attribute set to ON.
-glg-opengl-version <NNN>
Specifies the value of GlgOpenGLVersion which requests the specified OpenGL version. The shader-based Core OpenGL profile is used for OpenGL versions higher than 3.00, and the Compatibility profile is used for older OpenGL versions. The Core profile is used by default, switching to the Compatibility profile if an older graphics card doesn't support the Core profile.
-glg-debug-opengl
Generates extended diagnostic output for the OpenGL driver in the glg_error.log file.
-glg-opengl-hardware-threshold <N>
Specifies the value of GlgOpenGLHardwareThreshold. All viewports with a non-zero value of the OpenGLHint attribute, less than or equal to GlgOpenGLHardwareThreshold, will be rendered using the hardware OpenGL renderer (if available). Viewports with the attribute value between GlgOpenGLHardwareThreshold and GlgOpenGLThreshold will be rendered using the software OpenGL renderer (if available).
-glg-opengl-threshold <N>
Specifies the value of GlgOpenGLThreshold. All viewports with a value of the OpenGLHint attribute greater than GlgOpenGLThreshold will be rendered using the GDI renderer.
-glg-enable-hardware-opengl
-glg-disable-hardware-opengl
Enables or disables hardware OpenGL. If the OpenGL driver is enabled and the hardware OpenGL is disabled, only the software-based OpenGL renderer will be used.
-glg-enable-software-opengl
-glg-disable-software-opengl
Enables or disables software OpenGL. If the OpenGL driver is enabled and the software OpenGL is disabled, only the hardware-based OpenGL renderer will be used.
-glg-debug-encoding
Generates diagnostic output for the string encoding conversions.
-glg-debug-fonts
Generates diagnostic output for troubleshooting font sets on Linux/Unix.
-glg-enable-xft-fonts     (default)
-glg-disable-xft-fonts
Controls the use of XFT fonts on Linux/Unix.
-glg-x-resource-file <filename>
Specifies location of a custom X resource file for customizing XFT fonts used by native input objects on Linux.
-glg-debug-xft-fonts
Generates diagnostic output for troubleshooting XFT font matching on Linux/Unix.
-glg-disable-timers
Disables timer transformations in the drawings for debugging purposes.

Environment variables may be used instead of the command-line options if necessary.

A verbose mode may be set by setting the GLG_VERBOSE environment variable to True.

The OpenGL renderer may also be enabled or disabled by setting the GLG_OPENGL_MODE environment variable to True or False, or by setting the GlgOpenGLMode global configuration resource in the GLG configuration file to the following values:

 0 - disable the OpenGL renderer
 1 - enable the OpenGL renderer
-1 - don't change the default setting.

When the OpenGL renderer is enabled, the GLG_DISABLE_HARDWARE_OPENGL environment variable may be set to True to disable hardware-accelerated OpenGL and use the software OpenGL.

Refer to Builder Setup and Customization on page 329 for a list of all supported environment variables.

GLG Graphics Builder Features

When the Builder starts, you see the main window:

The most important areas of the GLG Graphics Builder window are:

The Toolbar contains icon buttons for fast access.
The Drawing Area contains the graphical objects of the drawing. By default, the drawing area contains an axis marker that shows the projection of the current view, and grid lines. The drawing area also contains round red markers that annotate the extent of the default span.
The markers are usually displayed in the corners of the viewport with the current editing focus, unless the viewport is zoomed in or out. The markers may be outside of the visible area if the viewport is zoomed in, of if Stretch XY=NO and PushIn=NO.
The Object Palette contains buttons for creating graphical objects.
The Control Panel contains the following controls:
The Point Controls let you select a method for specifying the location of points as you draw an object. It contains the following buttons for selecting the mode for defining points:
P (Position) - define the point position by clicking with the mouse in the Drawing Area.
C (Constrain) - constrain to a control point selected with the mouse.
U (Use) - use the position of a control point selected with the mouse.
V (Value) - specify X, Y and Z coordinates of the point using the keyboard.
The buttons become active for any operation that requires the user to define one or more points.
The Hierarchy and Focus Controls navigate through composite objects such as groups and viewports in order to edit their subobjects.
The Flip and Transform Controls may be used to flip, rotate or scale the object by a precise value.
The Zoom and Rotate Controls let you control your view of the drawing area.
The Status Panel contains two rows of controls:

Stopping the GLG Graphics Builder

Use File, Exit to close the Builder; see page 355.

Creating a Viewport

A viewport is a GLG object that represents a cross-platform window used as a backdrop and container for other objects. The viewport also defines what part of the GLG drawing's infinite coordinate space will be visible on the screen. Although the Builder allows you to draw objects in its Drawing Area without a viewport, you must use a viewport as a container for a drawing if you want to display the drawing in a program.

When the Builder first starts, it creates a default viewport, names it "$Widget" and brings editing focus into the viewport, which is equivalent to the File, New, Widget (Resize and Stretch), 1:1 menu option. You'll see this viewport when you save the drawing, or load the drawing in the Builder.

The File, New, Widget menu options described below start a new drawing and create a viewport named "$Widget" that is used as a container for drawing graphical primitives inside it.

If you start a new drawing using the File, New, Empty Drawing (Resizable) menu option, it will start with an empty drawing, and you will need to create a viewport that will act as a container for other objects. To create the viewport:

1. Use the Object, Create, Viewport menu option, or click on the Viewport button in the object palette in the upper left of the Builder window, then click on two points in the drawing to define the viewport's corners.

To draw objects inside the viewport, we need to "open" it to get inside:

2. If the viewport is not selected, select it by clicking on it with the mouse.
3. Use the Traverse, Hierarchy Down menu option, or click on the down arrow in the hierarchy controls in the lower left of the Builder window.

Once you have created and opened a viewport, you can draw objects within its boundaries. To use the drawing in program, the viewport must be named "$Widget".

Saving a Drawing

As you work on a drawing, use File, Save or Save As to save the drawing to a file; see page 351.

If you were editing objects inside the viewport, saving the drawing will bring you back to the top level of hierarchy. To return back to editing objects in the viewport, select the viewport and click on the Hierarchy Down button.

You should save your drawing frequently, so you can back out changes by reverting to the last saved version of the file. The Builder also provides an explicit Undo function, but some of the advanced operations, such as exploding or changing constraints, can not be undone.

Options For Creating New Drawings

The File, New, Widget menu provides options for creating new drawings that automatically create a viewport named "$Widget" and also set a desired width/height ratio. There are two sets of options: one for creating resizable drawings and another for fixed scale drawings. When the window the drawing is displayed in is resized, resizable drawings will scale and stretch all graphics proportionally to the new window size, while fixed scale drawings will show more or less of the graphics without scaling or stretching it.

The File, New, Widget (Resize and Stretch) and File, New, Widget (Resize, No Stretch) menus are used to create drawings that scale the graphics when the drawing window is resized. The Resize and Stretch option creates a resizable drawing that stretches graphics when the window aspect ratio changes. The Resize, No Stretch option scales the graphics, but preserves its aspect ratio by adding padding areas on the sides of the drawing as needed.

Both File, New, Widget (Resize and Stretch) and File, New, Widget (Resize, No Stretch) menus provide options for creating drawing with different width/height ratios to match the width/height ratio of the window the drawing will be displayed in. This allows to target screens of different sizes and avoid X/Y distortion of objects in the drawing when the drawing window is maximized to the full screen size:

The coordinate extent is set via the SpanX and SpanY attributes of the viewport's screen according to the selected option. Other ratios can be achieved by setting these attributes to different values.

Another alternative, setting the Stretch XY attribute of the viewport screen's to NO, preserves the X/Y ratio of the drawing regardless of the window dimensions, but leaves gaps at the edges of the drawing to accommodate changing width/height ratio of the window.

The File, New, Widget (Fixed Scale) menu provides options for creating fixed scale drawings. The Size From Config File option creates a fixed scale viewport with the size specified in the glg_config file (glg_hmi_config for the HMI Configurator). The Custom Size option allows creating a fixed scale drawing of an arbitrary size specified via a popup dialog.

The File, New menu also contains options for starting with an empty drawing, as well as for creating subdrawings, which are drawings that will be referenced in other drawings. Both options provide resizable and fixed size choices.

When a new widget is created using one of the File, New, Widget menu options, a Hierarchy Down operation is executed automatically to get the editing focus inside the widget, so that the user can start creating objects inside the drawing's viewport. For resizable viewports, the default extent of the coordinate system in an unzoomed state is annotated by using different colors, with span markers drawn in the corners. For fixed scale viewports, an area corresponding to the current viewport size (the area that is visible at the top level of the hierarchy) is annotated. The Options, Show Span menu contains options that may be used to turn the annotation on or off. Use the Traverse, Hierarchy Up menu option or the Up button to get to the top level of the hierarchy outside the viewport. Saving the drawing also brings editing focus to the top level of the hierarchy.

If the Builder is resized, the Adjust $Widget Size menu option may be used to adjust dimensions of the $Widget viewport to take all space available in the drawing area while maintaining its width/height ratio. This option is active only at the top level of the drawing hierarchy.

Drawing an Object

Once you have created and opened a viewport, you can draw other objects within it.

To draw most GLG objects, you use the options on the Object, Create submenu, or pick a shape from the Object Palette in the upper left of the Builder window.
The buttons in the Object Palette have tooltips that provide information about each button's function.

Not all the buttons on the palette correspond to distinct GLG object types. Some of the buttons are shortcuts to producing an object with particular attribute settings, provided for convenience. For example, both the Arc and Circle buttons create an arc object, but the angle of it is preset to 360 degrees when the Circle button is used.

The Status Panel at the bottom of the Builder window prompts you to specify the geometry and/or parameters of the new object. By default, you specify geometry by clicking on points inside the drawing area. Alternatively, you can change the way you specify points by using the Point Controls in the lower left of the window.

For most objects, you only need to specify a few points. The Builder always prompts you for all the information needed to create a particular object: the prompt is displayed at the bottom of the drawing area. For help in creating a particular shape, see Create on page 384.

For example, to draw a circle, you can click on the button. The Builder prompts you to specify the circle's center and another point that defines the radius.

To align the points of an object, use the options on the Options, Snap To submenu; see page 415. When you select a Snap To value, specifying coordinates with the mouse becomes less precise, because the point values are rounded off. Snap To only affects mouse selection.

GLG Objects

Although the menus and buttons in the GLG Graphics Builder show a wide variety of different drawing possibilities, the underlying graphical types are more restricted in number. Many of the buttons are provided for convenience, and do not represent separate object types. The available object types are:

Complete descriptions of all the GLG objects appear in GLG Objects on page 57.

Selecting an Object

The simplest way to select an object is to click on it with the mouse. When you select an object, its control and resize points appear.

The move point appears at the object's center, it's a dynamically calculated point, provided for convenience in the Builder only. You can reposition an object precisely by Shift+clicking on the move point, and using the arrows in the Object Move Point dialog. To avoid accidental movement while you are selecting an object, use Shift+click to select the object. For less precise movements, just drag the object with the mouse.

An 8-point resize box appears around an object. Use its points to resize the object. You can also flip the object by dragging any of the resize points to the other side of the object's box. Objects with only one control point (marker, fixed text, etc.) can't be resized, and resize points for these objects appear desensitized (in a gray color).

A rotate point appears on the right side on the resize box. To rotate an object precisely by a specified angle, Shift+click on the rotate point and use the arrows in the Object Rotation Point dialog. For quicker or less precise rotation, drag the rotate point with the mouse.

Control points appear at the vertices or other important points. To change the shape of the object, drag its control points with the mouse. You can also edit a control point precisely by Shift+clicking on it; see page 283.

If an object has geometrical dynamics attached, the control points of the dynamics will also be displayed. The object dynamics' points may be positioned the same way as other control points.

The Options, Selection Options, Selection Display menu (Ctrl-N accelerator) can be used to change the selection display to show just the resize box, just the control points or both for convenience. When editing large groups with a lot of control points, set the selection display to show just the resize box to speed up group selection.

The Options, Selection Options, Control Points Display menu can be used to enable or disable display of control points of the object's dynamics.

The Options, Selection Options, Show Attachment Points menu option can be used to enable or disable display of attachment points of reference objects. Refer to the Attachment Points section on page 114 for more information on attachment points.

To select an object with no fill, click on its edge. The FillType attribute controls this aspect of an object's appearance.

The move point, rotate point and the resize box's points are provided for convenience in the Builder only. The control points, on the other hand, are real object points and may be accessed as object attributes or (if named) resources. For objects with a fixed number of control points, the points may be also accessed using the point's default resource name: Point1, Point2, Point3, etc. For objects with a variable number of control points, such as a polygon and its subclasses, the points can be accessed at run time by using the GlgGetElement function or method without naming the points in the Builder.

In the Windows environment, some viewports require special handling in order to move them. For instructions on dealing with this special case, see page 391.

Selecting an Object That Is Close To or Behind Another Object

To select objects that are located close to each other, use Shift+click. If the Properties dialog is open, the arrow buttons in the upper right corner of the dialog may be used to select an object out of several potentially selected objects. If the Properties dialog is not active, the Object Selection dialog will be displayed. Use the dialog's arrow buttons to select an object out of several objects that are potentially selected.

Multiple Selection

To select more than one object, click and drag the mouse in the drawing to define a rectangular area: all objects that intersect this area will be selected. A temporary group is created to hold all selected objects; the group will be discarded when the objects are unselected. The temporary group is named "$TempGroup", and this name is displayed in the Status Panel when temporary group is created.

To add or delete objects from the selection, Ctrl+click on the objects with the left mouse button. For example, you could select multiple objects by Ctrl+clicking on them with the mouse. Ctrl+clicking on an object which is already selected deletes it from the selection.

The Edit menu provides more selection options: Select All, Select Multiple Objects and Select Rectangular Area, which may be used when the drawing has no empty space, making it impossible to define the selection rectangle with the mouse without selecting an object.

The Arrange, Permanent Group option changes the group type from temporary to permanent and back. The Arrange menu also provides explicit options for creating both temporary and permanent groups, as well as selecting multiple objects.

A permanent group can also be created by using Object, Create, Group, and drawing a rectangle that touches or encloses all the objects you want to include in the group. Release the objects from the group by selecting the group and using Arrange, Explode, Object. See Associating Objects Together on page 316 for information on how to perform an action on objects in a group.

Focus and Group Selection Shortcut

The Ctrl+Shift+click serves as a universal shortcut for traversing object hierarchy. For example, the first Ctrl+Shift+click on a group selects this group object. The second Ctrl+Shift+click selects a group element under the mouse. If there are several group elements that could potentially be selected, the third Ctrl+Shift+click activates either Rotate Object Selection arrows in the upper right corner of the Properties dialog, or the Object Selection dialog if the Properties dialog is not active.

The first Ctrl+Shift+click on a viewport or light viewport selects this viewport object. The second Ctrl+Shift+click moves the editing focus into that viewport. To move the focus back, Ctrl+Shift+click outside of the viewport.

If a group contains nested groups or viewports, or if a viewport contains groups or other nested viewports, repeated Ctrl+Shift+clicks on an object at the bottom of the object hierarchy inside that group or viewport may be used to select it, with each click selecting group elements or moving editing focus to the next level in the object hierarchy until the bottom object is selected. Ctrl+Shift+click outside of the group or viewport returns editing focus to the top level.

Editing Objects

Creating an object adds a graphical object to the drawing and another branch to the object hierarchy. The object is created with default attributes that control its appearance. The Builder lets you change the object. You can:

To prototype the object's run-time behavior, you can animate it with simulated or random data; see page 306.

Editing Attributes

The attributes of an object are the characteristics that control its appearance. Each object type has its own set of attributes that are used to draw the object. Because the GLG objects are arranged in a hierarchy, an attribute is usually an object with its own attributes, constraints, and transformations. In the Builder, you can edit not only the attributes of a graphical object, but also the attributes of its attributes.

For a complete discussion of the attributes of the GLG objects, see Structure of a GLG Drawing.

Edit Toolbox

The Edit Toolbox provides a fast access to editing attributes of an object or a group of objects, and may be activated with either the Object, Edit Toolbox, or the Edit Toolbox toolbar button. The toolbox also provides a direct, single-click access to common rendering and text box attributes (i.e. gradient and shadow colors, text box color and line attributes), which otherwise require several mouse clicks to be accessed. When activated, it displays the most common graphical attributes of the selected object (or group of selected objects) and provides menus and palettes for point-and-click attribute editing. It also displays the name of the selected attribute and provides a text entry box for entering its value directly, in addition to the palettes and menus. To apply a new attribute value entered in the text entry box, press either the Enter key or Apply button. This picture shows the Edit Toolbox with a color palette for editing TextColor attribute:

The buttons in the toolbox have tooltips that show names of attributes associated with buttons' icons. Only the attribute buttons that are applicable to the currently selected object or group of objects are highlighted and active.

Properties Dialog

The properties dialog provides access to the object attributes for more specific editing. In addition to changing attribute values, it also enables assigning resource names to attribute objects, editing constraints and attaching attribute transformations.

To edit an attribute of a graphical object:

1. Select the object.
2. Use Object, Properties or click on the Properties button on the toolbar to show the Selected Object Properties dialog. This dialog shows a list of attributes, with the current values. The list of attributes differs according to the object type. This example shows the properties of an unnamed parallelogram:

3. To edit an attribute, change its value.

The top panel of the properties dialog contains attributes common for all graphical objects, such as an object's Name, Type, Visibility, HasResources, etc. The middle part of the dialog contains object attributes that vary depending on the object type. At the bottom of the dialog there are buttons for adding and editing geometrical transformations, such as move, scale or rotate.

The Properties dialog of special objects, such as rendering attributes, text box attributes, font tables and viewport light attributes objects, also contain the Mark button to facilitate an easy reuse of these objects. The Add or Use Marked Object option of the Edit menu described on page 364 may be used to reuse these objects. If an object has custom properties attached, the Custom Properties button at the top of the dialog provides access to the custom property editing dialog.

While a value of an object attribute may be edited right in the Properties dialog, most attributes are objects themselves and have other properties in addition to the value. For attributes that are objects, an ellipsis button lets you open a separate Attribute dialog for editing the attribute value and other attribute properties.

Attribute objects may also have transformations, alarms and tags attached, in which case they are annotated with "X", "A" or "T" buttons on the right side of the Properties dialog. These buttons may also be used as shortcuts for accessing the dynamics, alarms or tags attached to an object's attributes.

If an attribute has a transformation attached that overrides the value of the attribute, the value of the attribute in the Properties dialog will be read-only.

Public Properties Dialog

Predefined components, such as dials and meters in the Dials and Meters palette, are composed of multiple objects contained in a group or viewport object. The Properties dialog for such a composite object displays only attributes of its group or viewport container, and the Resource Browser has to be used to access resources of objects contained inside the container.

To simplify editing of such components, commonly used resources of a component can be exposed as public properties that can be conveniently edited via the Public Properties dialog. Most of the predefined widgets in the GLG palettes already have public properties for simplified editing. Use the Object, Public Properties menu or the Public Properties toolbar button to display public properties of the selected object.

Refer to the Export Tags section on page 335 for information on how to define public properties.

Attribute Dialog

The content of the attribute dialogs differ according to the attribute and its data type (string, scalar, or geometric). However, all the dialogs include:

The following picture shows an Attribute dialog for a color attribute.

For color attributes, the colored boxes on the right side of the Value and XfValue fields show both the color and transformed color of the attribute.

The Options, Color Options, 255 Color Display option may be checked to display color RGB value in the range 0-255. By default, RGB values use the range from 0 to 1. The ColorDisplay255 parameter in the glg_config file may be set to 1 to permanently use the 255 color range.

In addition to a color palette shown in the picture, the Builder provides a custom color palette. To switch color palettes, use Options, Color Options, Swap Color Palettes, or simply Ctrl+click on the color palette. Refer to the OEM Customization chapter for information on how to supply your own custom color palette.

You can also Shift+click in the color palette or select Options, Color Options, Pastel Colors to switch between pastel and regular colors.

For the TextString attribute of a text object, the dialog will contain a text edit box for entering a multi-line text, while the text box in the Object Properties dialog allows only a single-line text string to be entered.

If an attribute object has transformations, alarm or tag attached, it will be annotated with "X", "A" or "T" buttons on the right side of the attribute row in the object's Properties dialog. These buttons may also be used as shortcuts for accessing the dynamics, alarms or tags attached to an object's attributes, bypassing the Attribute dialog.

XfValue is an edit-only text field that shows the transformed value of the attribute. If the attribute does not have any transformation attached, the transformed value will be the same as the attribute value, otherwise it will show the transformed value of the attribute that reflects the combined effect of all transformations attached to the attribute.

For convenience, all object attributes have default attributes names. Therefore, you can edit an attribute of an object by browsing its resource hierarchy and locating the attribute; see page 296. For a complete list of the objects' attributes and their default attribute names, see Appendix C: GLG Object Attribute Table on page 460 of the GLG Programming Reference Manual.

If an attribute has a transformation attached that overrides the attribute's value, the Value field will be read-only.

If the Edit Dynamics or Edit Alarm dialogs are open to edit a transformation or alarm attached to the attribute object, the Attribute dialog is disabled for the duration of the editing. This behavior may be changed using the ModalXformDialogs parameter of the glg_config file.

Editing Control Points

A control point is just a data attribute of an object, containing the coordinates of one point. However, since the Builder uses a different technique for editing control points, they require extra attention.

A minimal number of control points defines the basic geometry of each object. Depending on the shape, additional points may be calculated dynamically. For example, three control points define a parallelogram, and the last vertex is calculated dynamically. However, a free-form polygon has a control point at each vertex.

A parallelogram and a polygon, with their control points

To see the attributes of a control point, Shift+click over the point. The Control Point dialog shows the attributes of the point, with arrows for precise movement of the point and buttons for manipulating the point.

If more than one control point is located at the same spot, the Builder prompts you to select the one to edit by activating the arrow buttons in upper left corner of the Control Point dialog when the point is selected with the Shift+click.

Object Layout and Alignment

The Layout Toolbox provides point and click access to the align and layout features, and can be activated using Layout, Layout Toolbox, or pressing the Layout Toolbox button in the toolbar. The toolbox is split into two areas: the top panel contains icons for operations that does not require any parameters (Align Top, Set Same Width, Distribute Evenly Across, etc.) , while the bottom panel contains icons and controls for operations that requires a parameter, such as Set Width or Set Horizontal Distance. The toolbox's buttons have tooltips that show actions associated with buttons' icons. The following picture shows the Layout Toolbox:

The icons in the top panel of the Layout Toolbox operate on several objects and are active only when multiple objects or a group is selected. The first button in the second row, the Select Anchor Object button, has a bright red color and may be used to select the anchor object: the rest of the objects will be aligned relatively to the anchor object's extents. To select an anchor for several selected objects, click on the button, then click on one of the selected objects. When the anchor object is selected, the color of the icon turns green.

The first two buttons in the lower row of the area are highlighted with red color as well and can be used to switch between two layout modes: the control points and bounding box mode. In the control points mode, the object's control points are aligned. In the bounding box mode, the bounding box of objects is used for alignment. The difference can easily be seen by trying to align text objects with just one control point but different text extents. There are situations, though, where either one or the other alignment mode may be useful.

When setting sizes of text objects with more than one control point, the control points mode is always used regardless of the layout mode settings. When setting sizes of objects with a single control point, such as arcs and reference objects, the bounding box mode is always used.

When an object is selected, the bottom panel of the Layout Toolbox may be used to display its width or height in either the world or screen coordinates by clicking on the Set Width or Set Height buttons in the bottom panel. When an anchor is selected, clicking on the buttons displays the width and height of the selected anchor object. For example, selecting a group object with the Set Width button active will display the width of the whole group. Clicking on the Set Anchor Object button and selecting an object inside the group as an anchor will display the width of the anchor.

The bottom panel of the toolbox contain a row of icons for operations that need a numerical parameter. For example, setting the width of an object requires the width parameter. These operations may be applied to a single object or to a group of objects. When a group is selected, the Group Editing Mode button on the left of the panel defines if the layout operation, such as Set Width or Set Height, will be applied to the group itself or to the objects the group contains.

Note: the displayed screen pixel values of width and height are 1 less than the actual width and height.

The text entry box is provided for entering the required parameter, which is initialized to the corresponding parameter of the selected object, or the anchor object if it is defined. The World and Screen buttons above the text box control whether the value of the layout parameter, such as width, height or space, is interpreted as screen pixels or world coordinates. The Increase and Decrease Value buttons with arrows provide a convenient way to increase or decrease a desired parameter in steps, and with the provided increment. To apply a new parameter value entered in the text edit box, press either Enter key or Apply button.

Some operations from the bottom panel may not be applicable to certain object types. For example, trying to set width or height of a text object with one control point would generate a corresponding warning message. The Layout pull-down menu also provides options for accessing align and layout operations via the menu.

Edit, Undo may be used to reverse erroneous layout or alignment actions.

Creating Constraints

A constraint causes one attribute to change along with another attribute.

You can constrain the same attribute for two different objects. For example, constraining the FillColor attribute of a yellow polygon to the FillColor attribute of a green circle turns the polygon green. In the future, changing the FillColor of either object will affect both of them.

You can also constrain any attributes that have the same data type (string, scalar, or geometric); for example, a label and incoming data, the radius of a circle to the number of sides it has, or a color and a control point.

In the object hierarchy, a constraint is a point where two attributes merge. The constraint is not a link between the values for an attribute; it actually merges the attribute values. When two attributes are constrained, one attribute value is replaced.

In the Builder, an error checking is performed to detect circular constraints that would create a constraint loop. If a circular constraint is detected, constraining operation is aborted, generating an error message.

Constraining Similar Attributes

To create a constraint, you select the attribute that is to lose its value, and then constrain it to the attribute that replaces it. If the attribute is already constrained, the existing constraint is replaced by the new one unless you merge the constraints; see below.

To constrain an attribute to the same attribute in another object:

1. Select the object that has the attribute you want to constrain.
2. Use Object, Properties or click on the Properties button to show the Selected Object Properties dialog. This dialog shows a list of attributes, with a for attributes that can be edited in a dialog.
3. Click on the to see the Attribute dialog.
4. Click on the Constrain One button in the Attribute dialog. To keep existing constraints, use the Constrain All button instead. (Constrain One is enabled only if activated in the glg_config file.)
5. The Builder prompts you for the object to constrain to. To do so, click with the mouse on an object in the drawing.

With this method, the Builder automatically applies the constraint to the appropriate attribute. For example, selecting the FillColor attribute of a yellow polygon and then selecting a green circle to constrain to creates a constraint between the FillColor attributes of the two objects.

Merging Constraints

If you use the Constrain One button, any existing constraints are replaced by the one you create. However, you can add another constraint without removing the existing constraints; use the Constrain All button instead of the Constrain One button. (Constrain One is enabled only if activated in the glg_config file.)

For example, you can constrain the points C and D.

If you then select C and use the Constrain One button to constrain it to E, the constraint between C and D is lost.

However, if you select C and use the Constrain All button instead of the Constrain One button, the constraint between C and D is preserved.

Constraining Different Attributes

To constrain different attributes that have the same data type, you can use the Builder's marking facility or refer to a named resource. To use marking, you open and mark the attribute value that you want to reuse, and then use it in the attribute whose value you want to replace. Alternatively, if the attribute already appears in the resource hierarchy, you can just use its value without having to mark it.

As with constraints between similar attributes, constraining an attribute that is already constrained replaces the existing constraint, but you can add another constraint and preserve the existing ones by merging them.

To constrain two different attributes:

1. Open the Selected Object Properties dialog for the object.
2. Open the Attribute dialog for the attribute that you want to reuse.
3. Click on the Mark button, and select a mark number to assign to the attribute value. The attribute value is now marked.
4. Open the other object's Selected Object Properties dialog.
5. Open the Attribute dialog.
6. Click on either the Constrain All button or the Constrain One button in the Attribute dialog. The Builder prompts you to select either a resource or a marked value. (Constrain One is enabled only if activated in the glg_config file.)
7. Click on Use Marked and select the mark number you assigned earlier (if only one mark was assigned, it'll be used automatically). To use a named resource instead of a marked value, click on Use Resource and select the resource from the Resource Browser dialog.

The value of the attribute you marked is applied to the other attribute. For example, constraining the FillColor attribute of a yellow circle to a control point of a green polygon makes the circle change color when you move the control point.

Constraining Control Points

Control points are constrained just like other attributes. Use Shift+click to see the attributes for the control point, then use either the Constrain All or the Constrain One button and select the control point to constrain to. (Constrain One is enabled only if activated in the glg_config file.)

Constraints Tracing

Tracing Tags, Resources and Object Attribute Constraints

The object tracing feature may be used to examine tags and resources defined in the drawing, as well as constraints between object attributes. The feature is activated using the Options, Trace/Highlights, Trace Tags, Resources and Constraints menu option. When activated, it highlights all objects in the drawing that depend on a tag selected in a Tag Browser, a resource selected in a Resource Browser or an attribute displayed in the Attribute Object dialog.

Tracing Marked Attribute

Tracing marked attribute may be used when attributes of several objects are constrained, and one needs to find the exact way the attributes are constrained. While the tracing attribute constraints option described above helps find objects in the drawing that have constraints to a given attribute, the Tracing Marked Attribute option highlights attributes in the property dialogs, helping to find the exact attributes that are constrained, which could be hidden inside the transformations attached to the object or its attributes.

To trace constraints for a given attribute, mark the attribute as Mark0 in the Attribute or Resource Object dialog and activate tracing via the Options, Trace/Highlights, Trace Attribute Constraints for Mark0 menu option.

If the Trace Tags, Resources and Constraints option is activated, it highlights all objects in the drawing that have attributes constrained to the marked attribute. When one of the objects is selected with the mouse, the Status Panel fields that display the object's Name and Type will be highlighted in red to indicate the presence of the constraints. If the object has a geometric transformation, an action or custom data whose attributes are constrained to the marked attribute, the corresponding buttons in the Status Panel will also be highlighted. To narrow the search, follow the highlighted items and their properties.

The attributes constrained to the marked attribute will also be highlighted with a red outline in the property dialogs, such as Object Properties, Object Dynamics, Attribute Object and others, helping to navigate to the source of the constraint. If the attribute itself is constrained, a solid outline is used. If an attribute itself is not constrained, but has a transformation whose parameters are constrained, a dashed outline is used.

Stars are used to annotate constrained items in list dialogs, such as Custom Properties or Object Dynamics List. If an item is constrained, it is annotated with two stars. If the item itself is not constrained, but has a transformation whose parameters are constrained, it is annotated with one star.

In drawings with a large number of objects, group multiple objects in a temporary group and check if Name and Type field in the Status Panel are highlighted.

Defining Transformations and Adding Dynamics

In addition to changing values of object attributes directly, dynamic behavior may be achieved by adding a dynamic transformation to an entire object or an object attribute. For example, a rotate transformation may be attached to an object to rotate it by changing a rotation angle, or a Color List transformation may be attached to an object's FillColor attribute to change the color depending on an input value.

A transformation is applied to change the value of an entity. It operates on the actual value of the object, producing an effective value which is used in rendering the drawing. The GLG Graphics Builder provides three sets of basic transformations, one set for each basic data type (string, scalar, and geometric). See GLG Objects for descriptions of the different transformation objects.

In the Builder, there are three different ways to apply a geometrical transformation to an object:

A transformation can be attached to an entire object, to an attribute of an object, to a control point, or to the entire drawing. If a composite object such as a group has a static or dynamic transformation added to it, the transformation transforms all objects inside the group. In other words, an object in a drawing inherits the combined effect of all transformations attached to it or its parents.

Adding Geometrical Dynamics and Transforming an Object

You can define a geometrical transformation by using a dialog to set the parameters of the transformation. When you transform an object, you can use one of three methods:

Transforming Object's Points

To transform the points of an object, making a permanent change to their coordinates:

1. Select the object and use Object, Transform Points. Alternatively, click on the Transform Object Points toolbar icon or Transform Object button in the Control Panel. The Transform Points dialog appears.
2. Select the transformation type using the Transformation Type option. The content of the Transform Points dialog changes, depending on the transformation you select. You can also switch to creating a static or dynamic transformation using the Action option in the dialog.
3. Specify the values to use in the transformation by typing them in the boxes. Alternatively, use the buttons on the right to supply the values using the mouse; the Builder prompts you for each required value.
4. Click on the Apply button to change the definition of the object by applying the transformation to the object.
5. To undo a transformation right after you apply it, use the Reverse button to specify an inverse transformation, and click on Apply again.

Transforming the points changes the object definition permanently, but does not add a transformation object to the object hierarchy.

Creating a Transformation Object

To create a transformation object attached to a graphical object:

1. Select the object and use Object, Add Static Transformation, or Add Dynamics. Alternatively, open the Selected Object Properties dialog for the object, and click on the Add Dynamics button, or click on the Add Dynamics toolbar icon. A dialog for specifying the transformation appears; its title depends on the transformation you selected.
2. Select the transformation type using the Transformation Type option. The content of the dialog changes, depending on the transformation you select. You can also switch between transforming points and creating static or dynamic transformation using the Action option in the dialog.
3. Specify the values to use in the transformation by typing them in the boxes. Alternatively, use the buttons on the right to supply the values using the mouse; the Builder prompts you for each required value.
4. Optional step for dynamic transformations: enter a name for the transformation's controlling parameter into the Variable Name field, and define the ranges that control mapping of input data to the change of the Factor parameter. If the default ranges are modified, a Range Conversion transformation will be attached to the Factor parameter, and the name entered in the Variable Name field will be assigned to the Input Value parameter of Range Conversion. If the default ranges are not modified, the name will be assigned to the Factor attribute of the attached dynamics.
5. Click on the Apply button to change the definition of the object by applying the transformation to the object.
6. To undo a static transformation right after you apply it, use the Reverse button to specify an inverse transformation, and click on Apply again. To undo a dynamic transformation, delete the attached transformation using Object, Delete Dynamics or the Delete Dynamics toolbar icon.

Defining a static or dynamic transformation adds it to the transformation list, so you can access it using Object, Edit Dynamics. If you want to attach the same transformation definition to other objects, you can use the Mark Object or Mark List buttons in the Edit Dynamics list; see page 311.

Several dynamic transformations can be attached to an object to move, scale and rotate it depending on several dynamic parameters. The order of transformations is important: if the order is changed, the result of applying several transformations to an object will be different. The Edit Dynamics dialog provides controls for changing the order of transformations in the list.

The MoveMode Attribute

The MoveMode attribute is used to preserve a relative position of centers of rotation and scale dynamics attached to the object from changing when the object is moved with the mouse. If the MoveMove is set to STICKY MODE, the center of rotate or scale transformation will be moved together with the object. If it is set to MOVE POINTS, the center of the transformation will not be moved with the object.

For example, an object rotating around its center with MoveMode set to STICKY MODE will still rotate around its center after being moved. With MoveMode set to MOVE POINTS, the center of rotation will not move along with the object, and the object will rotate around the old center position even after the object has been moved.

If the MoveMode is set to MOVE BY XFORM, moving or transforming the object in some other way results in adding a static xform to the object, instead of changing the coordinates of the object's control points. The added transformation equally transforms the object's control points and the attached transformation's center points, preserving their relative position. This may be used when you want to preserve the original coordinates of an object's control points.

The MoveMode attribute is located in the Selected Object Properties dialog next to the HasResources flag.

Adding Attribute Dynamics

Attribute dynamics are accomplished by adding a dynamic transformation to an attribute object. Examples of commonly used attribute dynamics include visibility, color and text dynamics.

The data type of the attribute controls the type of transformation you can apply to it. For geometric values that represent points in the drawing, the dialogs are similar to those for transforming objects. For other attribute objects that represent scalar, string or color values, the transformation type is selected from a list displayed inside the Attribute dialog.

The Builder provides various types of dynamic transformations that can be used as building blocks for implementing elaborate dynamic behavior. In addition to the stock transformation types, the Builder also supplies easy to use predefined dynamics options for implementing the most common dynamic actions.

Custom predefined dynamics may be defined using the Enterprise version of the Builder started with the -oem command-line option, see the Custom Predefined Dynamics section on page 337. Custom predefined dynamics may be used by the system integrators to extend GLG editors with elaborate application-specific dynamics.

To define a transformation object attached to an object's attribute:

1. Select the graphical object that has the attribute you want to transform.
2. Use Object, Properties or click on the Properties button to show the Selected Object Properties dialog. This dialog shows a list of attributes, with a for attributes that can be edited in a further dialog.
3. Click on the for an attribute, to see the Attribute dialog.
4. Click on the Add Dynamics button in the Attribute dialog. A list of transformation types appears. The content of the transformation list depends on the data type of the attribute. The predefined dynamics are listed first by default, and the Stock Dynamics button located at the end of the list may be used to show all available stock transformation types. The Options, Dynamic Options, Show Predefined Dynamics First toggle in the main menu can be unchecked to list stock dynamics first. See Transformation Object on page 167 for specifications of the transformations.
5. Click on the transformation name to add the new transformation to the attribute, then edit the transformation's parameters in the activated Edit Dynamics dialog.

Once the transformation has been defined, you can edit it using the Edit Dynamics button in the Attribute dialog. You can attach the same transformation definition to other attributes by using the Mark Object and Mark List buttons in the Edit Dynamics dialog; see page 311.

Only one transformation can be added to an attribute (except for control points). To create complex attribute dynamics that depend on multiple parameters, dynamic transformations may be "chained" by attaching additional transformations to the attributes of the first transformation. When such recursive transformations are edited, the title of the Edit Dynamics dialog reflects the current nesting level of the transformation.

Adding Dynamics to Control Points

Control points are special attributes of an object that define its geometry. A geometrical transformation can be added to a control point to move, scale or rotate the point based on a value of a dynamic parameter.

To add a dynamic transformation to a control point, Shift+click on the point to show the Control Point dialog, click on the Add Dynamics button, then follow steps 2-5 described in the Creating a Transformation Object section on to add a transformation.

The Add Dynamics button in the Control Point dialog is activated only for real control points. It is disabled for the object move point and resize points, which are displayed only in the Builder for convenience of editing .

Several dynamic transformations can be attached to a point to move, scale and rotate it depending on several dynamic parameters. The order of transformations is important: if the order is changed, the resulting point position will be different. The Edit Dynamics dialog provides controls for changing the order of transformations in the list.

Editing Transformations

For each object or attribute with transformations, the Builder maintains a list of attached transformations. The list shows both the static and dynamic transformations, but you can only edit parameters of the dynamic transformations.

To edit transformations:

1. First, display the transformation list:
a. For a graphical object, use Object, Edit Dynamics to see a list of transformations. Alternatively, click on the Edit Dynamics toolbar icon or click on the Xform button in the Status Panel below the drawing area. If the Properties dialog is open, you can also use the Edit Dynamics button at the bottom of the dialog.
b. For an attribute, use Object, Properties to show the Selected Object Properties dialog, and click on the to see the Attribute dialog. Finally, click on the Edit Dynamics button. Alternatively, click on the "X" button on the right side of the attribute row in the Properties dialog.
c. For a control point, use Shift+click to see the Control Point dialog, and click on the Edit Dynamics button.

A list of transformations is displayed on the left side of the Edit Dynamics dialog.

2. In the Edit Dynamics dialog, select a transformation from a list on the left side of the dialog. The transformation attributes appear on the right side of the dialog.

The transformations are listed in the order you created them, with the first transformation at the bottom of the list. The new transformations are added at the top of the list. If the coordinate system is set to the Object Coordinate System, a new transformation is added at the bottom of the list, see page 314.

The Up and Down buttons on the right side of the Transformation List may be used to reorder transformations by moving the selected transformation up or down. The order of transformations is important: reordering transformations changes the way the object is transformed. The Delete button may be used to remove the selected transformation.

If you add several static (matrix) transformations consecutively, they are merged into a single matrix transformation.

Deleting Transformations

The Delete Dynamics toolbar icon can be used to delete the transformation that was added last (displayed at the top of the list). The Builder does not confirm the deletion of a transformation.
If the coordinate system is set to the Object Coordinate System, Delete Dynamics deletes the transformation which was added first (displayed at the bottom of the list), see page 314.

The Delete button of the Edit Dynamics dialog may be used to delete the currently selected transformation from any position in the list.

To remove the first transformation:

To remove a selected transformation from a list of transformations:

If you added several matrix transformations consecutively, they are merged into a single matrix transformation and are all deleted together.

Traversing Transformed Objects (advanced)

For an object with at least one transformation attached to it, the Builder lets you view the untransformed object. The Builder's main window shows the transformed object, and you use Traverse, Transformation Down and Traverse, Up to move between the transformed and untransformed view of the object.

Using View and Screen Transformations of the Viewport (advanced)

A Viewport uses two sets of transformations: the "outside" transformations are used to position the viewport itself, and the "inside" transformations are used to draw the objects inside the viewport. When the viewport is selected, the Add, Edit and Delete Dynamics buttons of the Properties dialog modify an outside transformation. If the editing focus is inside the viewport with no objects selected, the buttons modify the inside transformations which may be used to zoom, pan or rotate all objects in a viewport without creating a group to hold them. After either the inside or outside transformation is added, it may be edited with the Edit Dynamics button.

When a list of inner transformations of the viewport is displayed, it also shows the viewport's zoom transformation. This is a matrix transformation which is automatically created and used when changing the view in the Builder. It is always at the bottom of the list and cannot be deleted.

The viewport's screen object also has a special drawing transformation used to adjust the rendering of the viewport when the viewport's size changes. Clicking on the Screen Attributes button in the Viewport Properties dialog and then on the Edit Dynamic button in the Screen Properties dialog provides access to the parameters of this transformation. The X and Y scaling factors of the transformation may be used to create fixed screen offsets as described in the the Screen section of Simple Graphical Objects.

Using Resources

A resource is an object or attribute that is accessible by name. The Builder includes a browser which shows the structure of the named resources in a drawing - its resource hierarchy. The resource hierarchy is not the same as the object hierarchy; it contains only those objects that you have named and defined as having or being resources. See Structure of a GLG Drawing for more information.

Giving an object a name adds it to the resource hierarchy. The object's position in the hierarchy is controlled by the HasResources flags of its parent objects. If a parent object has the HasResources flag set to YES, the object is added to the hierarchy below the parent. If the object has no ancestors in the hierarchy, it appears at the highest level. The HasResources flag defines hierarchy levels similar to directories of a file system.

When naming an object, it's also convenient to consider the settings of its HasResources flag at the same time.

To see resources of an object, select it and use either Object, Resources menu option or the Resources toolbar button to bring the Resource Browser dialog, see page 400. To see resources of the whole drawing, unselect the object by pressing the Esc key. Selecting another object while the Resource Browser is active will show its resources in the Resource Browser.

The Resource Browser dialog shows the resources organized like a file and directory structure, with levels of hierarchy corresponding to the HasResources=YES settings.

Composite resources that contain other resources are annotated with the >> suffix added to the resource name. You can navigate between the hierarchy layers by double-clicking on the entries with the >> symbol at the end.

>> following a resource name means that it is either a geometrical object (i.e. polygon, arc, etc.) with a set of default attributes, or it has its HasResources flag set to YES and may contain other named resources. In either case, double clicking on such a composite resource opens another level of hierarchy, showing the resources inside it.

Entries with no >> symbol are usually attributes of objects. Clicking on such entries selects them, showing the Resource Object dialog for editing that attribute.

The selection box at the top of the Resource Browser shows the resource path of the currently selected resource, using / to separate hierarchy levels. This notation lets you specify a "path" to a resource, just as you would specify a path to a file. When the Resource Browser is used in the Builder, the path may start with one of the following symbols:

/ - top level (resources of the whole drawing area).
. - the selected object resources.
~ - resources of the viewport with the current editing focus (as a result of the Set Focus   button).
$config - global configuration resources of the Builder.

The first three symbols may also be displayed as entries in the Resource Browser to let you select a subset of resources for browsing. These entries are available only in the Resource Browser and not in the API.

The Resource Browser also contains the ".." entry representing the previous level of the hierarchy relatively to the currently selected resource.

The resource browser provides three toggles which can be used to control which resources are displayed in the browser: named resources, default resources, aliases or any combination or them. By default, all three resource categories are displayed. Commonly used attributes of most objects may be accessed via their default resource names such as FillColor or LineWidth, without requiring the user to name each resource. If an object attribute such as FillColor is named, it may be accessed by both the user-defined name and the default resource name.

The Filter field of the resource browser defines a regular expression to apply to the entries on one level of the hierarchy. Only the entries matching the filter expression on the current level of the resource hierarchy will be displayed. The * (any sequence of characters) and ? (any character) wildcards may be used to construct the filter.

Guidelines for Naming Resources

Although the resource hierarchy is totally flexible and should be organized to meet your requirements, we suggest the following guidelines for including resources:

These guidelines are not intended to force you into naming more objects than you find useful, but they may help you to make better use of the resource hierarchy's ability to structure the drawing and provide access to objects, especially as you begin using the Builder.

Adding and Deleting Resources

Naming an object automatically adds it to the resource hierarchy; its location is controlled by the HasResources flag of its parent object. When you delete an object from the drawing, it is also deleted from the resource hierarchy.

Adding an Object to the Resource Hierarchy

To add an object to the resource hierarchy:

1. Select the object.
2. Use Object, Properties or use the Properties button to see the attributes of the object.
3. Type a name for the object in the Name box.

The new name appears in the resource hierarchy.

A set of default resource names for the object's attributes are also added; they are automatically placed below the object, even if the HasResources flag is set to NO.

The object's attributes can also be named by selecting the attribute's ellipsis button and entering a name into the Name box of the Attribute dialog. For named resources, both the user-defined name and default resource name will appear in the resource browser.

The default names will always appear as the resources of the object. The location of the user-defined names will be controlled by the object's HasResources flag. If the flag is set, named attributes will appear as resources of the object, otherwise they'll appear as resources of the closest parent with its HasResources set to YES.

Defining the Hierarchy

Use the HasResources flag to control the organization of objects in the resource hierarchy.

For example, consider a group object named Group, with the members Circle, Triangle, and Rectangle. If the group object's HasResources flag is set to NO, the hierarchy is flat and the Resource Browser dialog shows all four objects at the same level.

Setting the group object's HasResources flag to YES defines an additional level of a hierarchy and makes the three objects into child objects of the group. The Resource Browser dialog shows Group as having child objects. Below, the picture on the left shows resources of the group, while the picture on the right shows resources of the Drawing Area.

Setting the HasResources flag also changes the path for locating an object. In this example, setting the group object's HasResources flag to YES changes the path to the Circle object from $Widget/Circle to $Widget/Group/Circle.

Deleting a Resource from the Hierarchy

To delete a named resource from the resource hierarchy, simply unname it. To remove the name from a named attribute object, follow the following steps:

1. Use Object, Resources or click on the Resources button to see the resource hierarchy.
2. Locate the resource you want to delete, and click on it to select it.
3. Delete the characters from the Name box of the Resource dialog. The object will no longer appear in the resource hierarchy.

The above procedure will work only for named attributes. To remove the name of a geometrical object (i.e. polygon, arc, etc.), select the object, and remove the name from the Name box in the Object Properties dialog. If the HasResources flag of the unnamed object was set to YES, its resources will disappear from the hierarchy and will not be accessible through the resources mechanism.

Using Tags

Data Tags

To simplify data access for process control applications, a data tag containing a TagName and TagSource may be assigned to any dynamic parameter or object attribute. Once a data tag is added, the data can be supplied to the attribute by using its TagSource. Unlike resources, which are hierarchical, the tags are global and have a flat hierarchy, with all tags visible at the top level. The tags can be accessed by their TagSource attribute, without a need to know the hierarchy path as it is the case with resources. Both tags and resources have their own advantages for different types of applications.

Resources are great for handling applications with a large number of instances of similar objects, where it is convenient to show just the names of instances on the top level and display more details when a particular instance is selected. Tags are ideal for process control applications, were the tag's TagSource attribute provide mapping between resources of the drawing and fields of a process database. TagSource defines the name of a database field which serves as a datasource for the tagged attribute. When a database field changes, an application can update a corresponding tag in the drawing by passing the tag source and new tag value to one of the SetTag functions. If multiple attributes share the same tag source, updating the tag will update all such attributes.

The Builder includes a Tag Browser which shows all tags of the selected object, or the tags of the whole drawing if no object is selected. If no object is selected and the editing focus is in a child viewport, the tags of that viewport will be shown in the Tag Browser.

A data tag may be added to any attribute or resource object by clicking on the Add Tag button in the Attribute dialog. The tag's TagName attribute may be given any local name that will help the user to identify the tag when browsing. The value of the TagSource attribute is used at run-time for accessing the value of the resource object the tag is attached to. Applications that receive data from a database usually use TagSource to define the database field to be used as a datasource. A tag also has a TagComment attribute that may store any auxiliary information related to the tag.

When a tag is added, its TagName and TagSource are initially set to the string "undefined" and may be edited in the Data Tag dialog. The values of the tag's TagName and TagSource attributes are displayed in the Tag field of the Attribute dialog as two fields separated by the `/' character. To edit the tag, click on the Edit Tag button of the Attribute dialog. All added tags are shown in a list of tags in the tag browser.

The Tag Browser dialog shows the list of tags. Each tag's entry shows its TagName and TagSource attributes separated by the `/' character. Clicking on tag entries selects them, showing the Data Tag dialog for editing the tag's attributes and the Attribute dialog for editing the attribute object the tag is attached to.

The tags displayed in the tag browser may be sorted by either their tag names or tag sources by using the tag browser's Sort by button. The Filter filed may be used to display only a subset of tags matching a regular expression that may contain the ? (any character) and * (any sequence of characters) wild cards. The regular expression will be applied to either the tag names or tag sources as controlled by the Source/Names toggle on the right side of the Filter field. The toggle also controls the Selection field, allowing the user to select a tag by typing its TagName or TagSource.

The Display Both/One toggle switches the view to display both the TagName and TagSource, or just one of them based on the current Sort By setting. If tags are sorted by the tag name, the TagName is shown in the Display One mode. If tags are sorted by the tag source, the TagSource is displayed.

The Unique Tag Sources/Names toggle controls if multiple tags with identical tag sources (when sorting by tag sources) or tag names (when sorting by tag names) are shown in the list. By default, the toggle is unchecked and all instances of tags with the same tag source or tag name will be displayed in the Tag Browser. If the toggle is checked, only the first instance of tags with the same tag source or tag name will be displayed.

Editing the value of a single tag in the Builder will not affect the other entries with the same TagSource. However, when a tag value is supplied at runtime via its TagSource, all value of all tags with the same TagSource will be updated.

To see all object's tags, select the object and use either Object, Tags or the Tags toolbar button to bring the Tag Browser dialog, see page 401. To see tags of the whole drawing, unselect the object by pressing the Esc key. Selecting another object while the Tag Browser is up will show its tags in the Tag Browser.

Refer to Tag-Based Data Access and Data Connectivity on page 232 for details of different ways of using tags for accessing data.

Adding and Deleting Data Tags

Adding a Tag

To add a tag to an object's attribute:

1. Select an object.
2. Use Object, Properties or use the Properties button to see the attributes of the object.
3. Select an object's attributes by clicking on the attribute's ellipsis button .
4. Click on the Add Tag button.
5. Enter values for the tag's attributes in the Data Tag dialog.

To add a tag to a resource:

1. Use Object, Resources or click on the Resources button to see the resource hierarchy.
2. Locate the attribute resource you want to tag, and click on it to select it.
3. Click on the Add Tag button.
4. Enter values for the tag's attributes in the Data Tag dialog.
Editing a Tag

To edit a tag attached to an attribute, bring the Attribute dialog for the attribute and click on the Edit Tag button to activate the Data Tag dialog. Alternatively, click on the "T" button on the right side of the attribute row in the Properties dialog.

The Data Tag dialog has entries for editing the TagName, TagSource and TagComment attributes of the tag object. The Type field displays the type of the attribute (D, S or G) the tag is attached to.

The InLow and InHigh entries become active if the attribute the tag is attached to has a range transformation. In this case, the InLow and InHigh entries of the Data Tag dialog provide direct access to editing the InLow and InHigh parameters of the range transformation. This is convenient when editing tags via the Tag Browser, since the user can assign a datasource and define its value range in one dialog.

Deleting a Tag

To delete a tag attached to an attribute object, follow the following steps:

1. Use Object, Tags or click on the Tags button to see a list of tags.
2. Locate the tag you want to delete and click on it to select it.
3. Click on the Delete Tag button in the Data Tag dialog.

Alternatively, display the Attribute dialog for the attribute or resource the tag is attached to, click on the Edit Tag button to display the Data Tag dialog and click on the Delete button. The "T" button on the right side of the attribute row in the Properties dialog may also be used to access the attribute's Data Tag dialog.

The Arrange, Delete Data Tags menu option of the Enterprise Edition of the Graphics Builder may be used to delete all data tags of the selected object.

Using Alarms

Alarms may be used to monitor an object's attribute value. A change alarm generates an alarm message when an attribute value changes, and a range alarm generates a message when the value goes outside of the specified range. At runtime, the application code receives alarm messages and processes them according to the application logic. An alarm label may be defined in the Builder to help identify the alarm source at runtime.

The Builder provides an Alarm Browser which shows alarms attached to the selected object; if no object is selected, the Alarm Browser shows all alarms defined in of the drawing. If no object is selected and the editing focus is in a child viewport, the alarms of that viewport will be shown in the Alarm Browser.

An alarm may be added to any attribute or resource object by clicking on the Add Alarm button in the Attribute dialog and selecting an alarm type.

The alarms's AlarmLabel attribute may be set to any custom string that will help the user identify the alarm when browsing alarms in the Builder, as well as at runtime. The alarm's Enabled attribute may be used to enable or disable the alarm.

When an alarm is added, its AlarmLabel is initially set to the string "undefined" and may be edited in the Edit Alarm dialog. To edit an existing alarm, click on the Edit Alarm button of the Attribute dialog. All added alarms are shown in the alarm browser.

The Alarm Browser dialog shows a list of alarms. Each alarm's entry shows its AlarmLabel. Clicking on an alarm entry selects it and shows the Edit Alarm dialog for editing the alarms's attributes, as well as the Attribute dialog for editing the attribute object the alarm is attached to.

The Filter field may be used to display only a subset of alarms matching a regular expression that may contain the ? (any character) and * (any sequence of characters) wild cards.

To see all alarms attached to an object, select the object and use either Object, Alarms or the Alarms toolbar button to bring the Alarm Browser dialog, see page 401. To see alarms of the whole drawing, unselect the object by pressing the Esc key. Selecting another object while the Alarm Browser is up will show its alarms in the Alarm Browser.

Refer to Alarm Object on page 196 for description of all available alarm types.

Adding and Deleting Alarms

Adding an Alarm

To add an alarm to an object's attribute:

1. Select an object.
2. Use Object, Properties or use the Properties button to see the attributes of the object.
3. Select an object's attribute by clicking on the attribute's ellipsis button .
4. Click on the Add Alarm button.
5. Enter values for the alarm's attributes in the Edit Alarm dialog.

To add an alarm to a resource:

1. Use Object, Resources or click on the Resources button to see the resource hierarchy.
2. Locate the attribute resource you want to add the alarm to, and click on it to select it.
3. Click on the Add Alarm button.
4. Enter values for the alarms's attributes in the Edit Alarm dialog.
Editing an Alarm

To edit an alarm attached to an attribute, bring the Attribute dialog and click on the Edit Alarm button to activate the Edit Alarm dialog. Alternatively, click on the "A" button on the right side of the attribute row in the Properties dialog.

The Edit Alarm dialog lists the alarm's attributes. The AlarmLabel field may be used to assign a custom alarm name, and the Enabled field may be used to enable or disable the alarm. For range alarms, the high and low ranges are also displayed.

Deleting an alarm

To delete an alarm attached to an attribute object, follow the following steps:

1. Use Object, Alarms to see a list of alarms.
2. Locate the alarm you want to delete and click on it to select it.
3. Click on the Delete Alarm button in the Edit Alarm dialog.

Alternatively, display the Attribute dialog for the attribute or resource the alarm is attached to, click on the Edit Alarm button to display the Edit Alarm dialog and click on the Delete button. The "A" button on the right side of the attribute row in the Properties dialog may also be used to access the attribute's alarm dialog.

Animating a Drawing

Animation brings the drawing to life by linking a source of data outside the Builder with a resource or tag in the drawing.

When you change the value of an object's attribute, it alters the object's appearance. Animating an object supplies a continually changing series of values to a particular attribute of the object, so the object's appearance is continuously altered. The attribute is addressed via the resource hierarchy; the attribute to animate must appear in the resource hierarchy. The attribute may also be addressed via its tag name.

For example, to animate the radius of a circle named Circle, you would use an external data source to provide a series of values to the $Widget/Circle/Radius resource object. Executing the animation results in a circle that changes its size. If the radius attribute has been assigned a radius tag name, the same animation may be performed by providing values to the radius tag.

You may also use a dynamic transformation to animate an object. The simplest way to animate a transformation is by naming its controlling Factor by specifying a Variable Name in the Add Dynamics dialog (the name gets assigned to the Factor parameter of the transformation in the Edit Object Dynamics dialog). At runtime, you can animate the Factor parameter (usually in the range of 0 to 1) to dynamically transform the object.

At run time, the animation is performed by updating resources of the drawing with new values using the GLG Standard API. The C/C++, Java, C#/.NET, JavaScript or ActiveX version of the API is used depending on the choice of the GLG container used to load the drawing. At design time, the GLG Builder provides a Run mode and a data generating tool (called datagen) for prototyping the drawing right in the Builder. A custom proto DLL can also be used to supply real-time data for prototyping, see the Custom Run Module DLL section on page 343.

Use Run, Start to prototype the drawing with test data and enter the run command for datagen. When prototyping a widget drawing loaded from the palette, the run command is usually preset to the correct value. To animate a custom drawing or resource, change the run command. To animate tags, use the -tag option. For the full syntax for datagen, see GLG Programming Tools and Utilities. For an example of using datagen to animate a drawing, see the Drawing a Simple Example section of this chapter. Refer to The Data Generation Utility of the GLG Programming Reference Manual for more details.

Reusing Objects, Attributes, and Transformations

The Builder provides a variety of ways to replicate the elements of a drawing. You can reuse entire objects, attribute values, or transformations.

Reusing an Object

The Builder provides a variety of methods for making copies of the selected object. These methods include:

Copying or cloning an object that is a named resource adds a duplicate branch to the resource hierarchy. If the duplication causes a naming conflict, rename the copy.

To copy more than one object in a single operation, first create a group object that contains the objects, using Arrange, Group. When you have finished the operation, select the group and use Arrange, Explode, Object to delete the group object and restore the independence of the objects.

A temporary group may also be used by either selecting objects by dragging a rectangle with the mouse, or by using Ctrl+click to add or delete objects from the selection. The temporary group is automatically destroyed when it is unselected.

If you are copying the objects because you want to create a set of identical objects that can be edited in one place as a single object, you should consider using a series, reference or other advanced object; see page 315.

Saving an Object to a File

You can save the selected object to a file, as a GLG drawing. Loading the saved object adds it to the current drawing, adding all its attributes to the object hierarchy of the current drawing. With this method, the object's availability persists across Builder sessions, because the object is in an external file. Use File, Save Object to create a new file that contains the selected object, and use File, Load Object to add the object to the current drawing; see page 351.

When you load an object from a file, the object is placed by using its coordinates in the coordinate system of the current level of the hierarchy. For example, if you select a viewport and then load a circle with a center at 0,0,0, the circle is drawn in the middle of the viewport.

Cutting, Copying, and Pasting an Object

You can cut or copy an object to a temporary storage area, and then paste it into the drawing. The clipboard holds a single object, which stays on the clipboard until you cut or copy another object. With this replicating method, the object can be copied from one level of the traversal hierarchy to another.

Use Edit, Cut and Edit, Copy to copy the selected object to the clipboard; cutting it deletes the original object while placing it on the clipboard, but copying it leaves the original intact and places a copy on the clipboard.

Use Edit, Paste to retrieve the object. When you copy and then paste an object, the object is placed directly over the selected object, at the current level of the hierarchy. You can then drag it into position. The Paste Clone Type option of the Options menu controls a constrain type of the copy's attributes.

The Cut, Copy and Paste toolbar icons may be used for fast access.

Cloning an Object

You can clone an object, which adds another copy of the object to the drawing. Cloning gives you more control over the nature of the copy; you can constrain the clone, place it using a specified offset from the original, or transform it as it is created.

The Builder provides several varieties of cloning:

Each attribute or control point has a Global attribute, which appears in the Attribute dialog. This attribute has three possible values that interact with the strong and weak clone types to provide a range of possibilities for constraining while cloning:

To control the position where the clone appears, use Edit, Clone Offset. To define a static transformation to apply to the clone as it is created, using Edit, Clone Transformation. The clone transformation may use rotational or other offsets.

Adding an Object to the Custom Object palette

To add an object to the Custom Object palette, simply save it in the widgets/custom_objects directory. The object will automatically be added to the Custom Objects palette when the builder is restarted or the palette is re-opened.

It's also possible to add your own palettes of objects to the Builder. Refer to the Palettes section of GLG Graphics Builder Menus for more details and options.

Marking Transformations, Rendering Attributes and Other Objects

The Builder includes a marking mechanism for marking attributes and resources, as well as transformation, aliases, custom properties, rendering and text box attributes, color and font tables, and other objects. Marking attributes is used for constraining to a marked attribute, as well as for reusing its value. Marking transformations, aliases, custom properties, rendering attributes and other objects is used for replicating these objects as well as for attaching constrained transformations or rendering attributes to several objects. The marking mechanism parallels the copy and paste mechanism, but its clipboard is entirely independent. The marking of attributes, transformations, aliases, custom properties and other objects are completely independent, but have similar uses.

Marking an attribute, transformation or other object for copying is similar to cutting and pasting with a clipboard; the marked entity stays marked until you mark another.

Marking an Attribute

The Builder lets you make the value of an attribute available for constraint or reuse with another attribute, if the two attributes use the same data type. You can mark up to five separate attribute values for reuse.

To mark an attribute value for reuse:

1. Select the object with the value you want to mark.
2. Use Object, Properties or click on the Properties button in the toolbar to show the Selected Object Properties dialog. This dialog shows a list of attributes, with a for attributes that can be modified.
3. Click on the to see the Attribute dialog.
4. Select the Mark button. The Builder prompts you with a list of marks, ranging from Mark0 to Mark4. Make a note of the marks you assign; they are not named.
5. Click on the mark to which you want to assign the attribute's current value.

The attribute value has been marked, and assigned to the mark number you specified.

Using Marked Attributes

There are two ways to use a marked attribute value: you can constrain the attributes, or set the second attribute's value to the marked value. To use a marked attribute:

1. Show the list of attributes for the object:
a. For an attribute, use Object, Properties to show the Selected Object Properties dialog, and click on the to see the Attribute dialog.
b. For a control point, use Shift+click to see the Control Point dialog.
2. Click on either the Constrain One, Constrain All or the Use Object button. The Builder prompts you with Use Resource and Use Marked buttons. If Constrain All is used, not only the attribute itself, but also all attributes constrained to it will be constrained to a new object. (Constrain One is enabled only if activated in the glg_config file.)
3. Click on Use Marked. The Builder prompts you with a list of marks, ranging from Mark0 to Mark4.
4. Click on the mark to use for the new attribute value.

The attribute value from the mark is applied to the current attribute.

When the drawing is reloaded, the marked attributes point to the attributes of the old drawing. Therefore, you can still reuse their values, but can't use them for constraining.

Unconstraining an Attribute

To unconstrain an attribute:

1. Show the list of attributes for the object:
a. For an attribute, use Object, Properties to show the Selected Object Properties dialog, and click on the to see the Attribute dialog.
b. For a control point, use Shift+click to see the Control Point dialog.
2. Click on either the Unconstrain button. If an attribute has a transformation attached to it, the Attribute Clone Type entry in Options controls cloning type of the transformation's attributes. The default is Constrained Clone, which means that while the attribute itself is unconstrained, the transformation's parameters will still be constrained.
Marking a Transformation

You can mark a transformation in a way that parallels the marking of an attribute; however, the two mechanisms are entirely separate.

The Builder lets you copy the definition of a transformation from one graphical object to another. You can also copy the definition from one data object to another, if the two data objects use the same data type. Marking a transformation for copying is similar to cutting and pasting with a clipboard.

In the object hierarchy, reusing a transformation definition produces another independent transformation object, attached to the object you select. The parameters of two transformation objects may be constrained by the reuse operation as described below, producing "linked" transformations changing synchronously and transforming several objects by changing just one controlling parameter.

To mark a transformation definition:

1. Select the object to which the transformation is currently attached.
2. Show the list of transformations for the object:
a. For a graphical object, use Object, Edit Dynamics or click on the Xform button in the Status Panel to see a list of transformations.
b. For an attribute, use Object, Properties to show the Selected Object Properties dialog, and click on the to see the Attribute dialog (properties that have a transformation attached are annotated with an X on the right side of the property in the Properties Dialog). Finally, click on the Edit Dynamics button.
c. For a control point, use Shift+click to see the Control Point dialog, and click on the Edit Dynamics button.
3. In the Transformation List dialog, use the Mark Object button to mark a single transformation, or use Mark List to mark all transformations in the list.

The transformation(s) you marked can be reused for any graphical or data object with the same data type.

To reuse marked transformations:

1. Select the object to which you want to attach the marked transformation(s):
a. For a graphical object, use one of the transformation options on the Object Menu or the Toolbar (Transform Points, Add Static Transformation, or Add Dynamics).
b. For an attribute, use Object, Properties to show the Selected Object Properties dialog, and click on the to see the Attribute dialog (properties that have a transformation attached are annotated with an X on the right side of the Properties dialog). Finally, click on the Add Dynamics button.
c. For a control point, use Shift+click to see the Control Point dialog, and click on the Add Dynamics button.
2. For an object or control point, click on the Transformation Type list, select Use Marked and the cloning type. Selecting Full Clone creates a new transformation with the same attribute values but without constraining. Selecting the Constrained cloning type creates a new transformation with attribute constrained to the original transformation. The Strong clone type constrains attributes of the transformation whose Global flag is Global or Semi-Global, and Weak clone constrains only Global attributes.

For attributes, click on the Use Marked button and then select a clone type from a popup menu.
3. For an object or control point, click on the Apply button to attach the marked transformation(s).

The marked transformation(s) stay marked until you mark another transformation. When the drawing is reloaded, the attributes of the marked transformation point to the attributes of the old drawing. Therefore, you can still reuse the transformations using Full Clone, but can't reuse constraints implied by the rest of the cloning types.

Marking Rendering and Text Box Attributes, Fonttables and Light Objects

Rendering and Text Box Attributes, as well as viewport's Fonttables and Light Objects can be marked for reuse by using the Mark button in the Properties dialog for these objects. To reuse the marked object, select Edit, Add or Use Marked Object, then select an option that matches the type of the marked object.

The Options, Attribute Clone Type menu controls constraints of the new instance's attributes: if it is set to Constrained Clone, all attributes will be constrained to the corresponding attributes of the original object. For example, to add constrained copies of rendering attributes to several objects, add Rendering Attributes to one object, mark the Rendering Attributes object, create a temporary group containing the objects, select Options, Attribute Clone Type, Constrained Clone, then select Edit, Add or Use Marked Object, Rendering Attributes. It will attach constrained copies of rendering attributes to all objects in the group: changing a rendering attribute of one object will affect rendering of all these objects.

Marking Aliases

Marking aliases is a convenient way of copying a list of aliases from one object to another.

For marking aliases attached to an object, select the object, then select Aliases, Mark Aliases from the Object pull-down menu. To add marked aliases to another object , select a new object, then choose Aliases, Add Marked Aliases from the same pull-down menu.

Marking Custom Properties

Marking custom properties provides a way to copy a list of custom properties from one object to another.

For marking custom properties attached to an object, select the object, then select Custom Properties, Mark Custom Properties from the Object pull-down menu. To add marked custom properties, select another object, then choose Custom Properties, Add Marked Properties from the same pull-down menu.

The custom property lists can contain lists of lists of custom properties. For example, an option menu object may have a list of custom properties that contains another list named InitItemList. The InitItemList contains items to be displayed in the option menu. To mark this inner list, select the option menu object, select Custom Properties, Edit Custom Properties from the Object pull-down menu, select InitItemList with a single mouse click and press the Mark List button. To add the marked list of custom properties as a list to another object, select a new object, then select Custom Properties, Add Custom Properties, Add Marked List from the Object pull-down menu.

Controlling the View

A GLG drawing is a set of three dimensional objects defined in limitless space. However, the Builder renders these objects in two dimensions on the screen.

To present a drawing, the Builder applies a set of transformations to the objects in the drawing. To get a different view of the drawing, you can change some of the parameters for these transformations, including the view projection, scale, coordinate system, and center.

For example, the Builder's main view shows the X and Y axes, with the Z axis perpendicular to the screen. In this projection, the control points of objects you create in the main view are positioned only with X and Y coordinates, with their Z coordinates set to zero. Using the mouse to edit objects in the default view only affects the X and Y values for the objects; the Z dimension is unaffected.

The Builder saves the current view for a viewport as part of the drawing. The view has no effect on the definition of the objects in the drawing, however.

To change your view of a drawing, use the options on the View Menu, or the Pan, Zoom, and Rotate controls.

Changing the View Projection

The Builder uses a view projection to transform the drawing from its three dimensional definition into the two dimensional rendering that appears in the drawing area. Your access to objects is limited by the view projection; the objects you draw are drawn in that plane. To get access to other planes for drawing, you change the view projection.

The Builder includes a set of six predefined view projections, but you can also define and use your own. Use the options on the View, Set View submenu to switch between predefined projections; see page 366.

To define your own projection, use either View, Adjust View (see page 366) or the buttons and sliders on the lower left side of the Builder window. The menu option gives you precise control over the projection, but the sliders let you change the projection interactively.

Note that these view sliders are stateless. The middle of the slider range always represents the drawing view before the slider is activated. This means that wherever you move the slider, it returns to the middle of its range when you release the mouse button, ready for the next move.

Customizing the View Projection

If you want to switch between several projections, you may want to save the transformation for the projections into files. When you want to view a drawing using a particular projection, you load the view projection. Use View, Save Viewing Transformation and View, Load Viewing Transformation to create and load a projection file; see page 367. Because the Builder saves the current view projection along with the drawing, you only need this option if you switch projections frequently.

To save or load a viewing transformation of a particular viewport, move editing focus into it using the Set Focus button or go down into it using the Hierarchy Down button.

To transform a viewport dynamically from a program, add a parametric transformation to the viewport as a view transformation. Changing parameters of the transformation will change the view projection. Alternatively, the program may use the GlgSetZoom method.

Viewing Using Different Coordinate Systems

By default, the Builder uses the coordinate system of the entire drawing for specifying points and transformations. However, you can view the drawing using the coordinate system of any object in the drawing to clarify the relationships between the objects. For example, changing the coordinate system allows the rotation of objects in different coordinate systems.

Use the options on the View, Coordinate System submenu to select a coordinate system. The effect of these options depends on the content of the drawing and the object you select. For example, consider a drawing that contains a group of three polygons; such a drawing has separate coordinate systems for each polygon, for the group object, and for the viewport. For this drawing, all the View, Coordinate System submenu options are applicable. However, for a drawing containing one polygon, only the Object option applies.

Changing the Viewing Area

To control the scale of the drawing, use the options on the View, Zooming submenu, or the Zoom and ZoomTo buttons in the Control Panel.

To use a different point as the center of the Builder window, use the View, Pan To option. Alternatively, you can use scrollbars or Ctrl+click in the drawing to drag it with the mouse.

Using Advanced Objects

The Builder includes certain objects that can be used for specialized functions. They simplify the construction of complex drawings.

The functions and the objects that provide them are:
Function
Object type

Associate objects together, either temporarily or permanently

Group

Create a set of replicated objects from a template, spacing them equally along a path

Series

Create a set of replicated objects from a template, arranging them on a grid

Square Series

Provide a container with one control point for holding objects

Container, Reference

Replicate instances of a template object

Object Reference

Replicate instances of a sub-drawing

File Reference

Create a line with a defined number of points, or a segmented line

Polyline

Create a patched surface

Polysurface

Create a frame to which other objects may be constrained

Frame

Connecting points or nodes with a recta-linear or arc path

Connector

Rendering gradient fill, arrowheads, cast shadows and fill dynamics

Rendering

Rendering a box around a text object

Box Attributes

Scrolling matching attributes of a collection of objects

History

Rendering GIS map data

GIS Object

Attaching custom properties

No dedicated object type

Defining logical resource names

Alias

Associating Objects Together

To associate objects, you create a group object that acts as a container. A Group object does not contribute to the drawing visually; it is primarily an editing tool with three main purposes:

Use Arrange, Group to create a group. The Builder prompts you to draw a rectangle that touches or encloses all the objects to be included in the group. A group object does not appear as a visible graphical object, but the control points of objects in a group appear as hollow squares. Clicking on any member of a group selects the group.

To release one object from a group, use the options on the Arrange, Explode submenu. To release all the objects from a group and delete the group object, select it and use Arrange, Explode, Object.

Editing Group Members

Although the members of a group are associated, they can still be edited individually. You can move the control points of a group member by dragging or editing them.

For more intensive editing, use the options on the Traverse and Arrange Menus to get access to an individual object:

Temporary Groups

A temporary group may be used for quick editing of several objects. A temporary group may be created by dragging a rectangle around objects in the drawing with the mouse; all objects that intersect a rectangle will be included into the group. Alternatively, Ctrl+click may be used to add or delete objects from the selection. The Edit and Arrange menus contain additional options for creating temporary groups. The Permanent Group toggle in the Arrange menu may be used to change the type of the group from temporary to permanent and vice versa.

The temporary group is automatically destroyed when it is unselected.

Generating Objects from a Template

To create a set of objects that share characteristics, you can generate objects from a template instead of cloning or copying an original. With generated objects, you can change the whole set just by editing the template, and position the set automatically.

The Series, Square Series, and Reference objects all consist of a set of instances and a template that controls the characteristics of the instances. The instances are created dynamically from the template. The number and positioning of the instances depends on the object type.

To create a series, square series, or reference object, you first create and select an object to act as the template. When you create the instances, the Builder moves the template and the instances into a new object. You can get access to the template using the Traverse, Hierarchy Down menu option.

The attributes of the template override any changes you make to an instance. To customize the instances, explode the series using Arrange, Explode, Object; see page 375. Then edit the attributes of the members of the resulting group.

The Series Object

A series presents a set of instances arranged along a line.

The number of instances is controlled by a factor, and their positions are determined by distributing them along a line or path. The instances are named using the template object name and an index; for example, a template named Rect with a factor of 3 creates three instances named Rect0, Rect1, and Rect2.

A Series object has four control points. Two points control the location of the line along which the series instances are distributed. A third point controls the position of the first instance's origin; it is constrained to one of the path points. A fourth point is visible only if you use Traverse, Hierarchy Down to see the series template; this point provides an alternative way to position of the first instance's origin.

To create a series:

1. Select an object to use as a template.
2. Select Object, Properties to name the object, and to set the attributes of the template object so that its instances will inherit appropriate characteristics.
3. Select Object, Create, Series to create the instance objects.
4. Click on two points to specify a path on which to arrange the series instances.
5. Enter a factor to specify the number of instances to create.

To edit the template object, use Traverse, Hierarchy Down. When you finish editing, use Traverse, Up to see the instance objects.

Alternatively, the Create, Path Series menu option may be used to create a series that uses an arbitrary transformation. For example, a rotate transformation can be used to position series instances around a circle.

The Square Series Object

A square series is a series with its instances organized into rows and columns. The number of rows and columns determines the number of instances in the square series.

A Square Series object consists of a template and a set of generated instances. The instances are named using the template object name and an index; for example, a template named Rect with two rows and two columns creates four instances named Rect0, Rect1, Rect2, and Rect3.

To create a square series:

1. Create and select an object to use as a template. For example, create a rectangle that occupies most of the drawing's [-1000; +1000] extent.
2. Select Object, Properties to name the object, and to set its attributes so that its instances will inherit appropriate characteristics.
3. Select Object, Create, Square Series to create the instance objects.
4. Click in the upper left corner of the drawing to define the square series origin.
5. Click in the upper right corner to define the length of the series' rows, then click in the lower left corner to define the length of the series' columns. These two vectors define arrangement of the series instances.
6. When prompted, enter the number of rows, then the number of columns. These values specify the number of instances to create.

To edit the template object, use Traverse, Hierarchy Down. When you finish editing, use Traverse, Up to see the instance objects.

The HandleInvisible and FillSpace series attributes can be used to adjust layout of the elements inside the series when visibility of some elements changes. Refer to the Square Series section on page 104 for more information.

The Reference Object: Containers and SubDrawings

A reference is essentially a series with a single element. Like the series, it uses a template object, but only one instance (the Reference object) is created.

A reference is most useful when there is a need to replicate an object throughout a drawing or multiple drawings. It may also be used to implement subdrawing or object dynamics, changing the displayed object based on some condition. There are several types of reference objects:

Container
A Container object is used to encapsulate a set of objects, protect them from accidental editing and provide a control point which may be used to move or constrain objects. When a container is copied, its template object is copied as well. To create a container, select an object to use as a template, click on the Container icon in the Object Palette and click in the drawing to position the container.
Included SubDrawing
An Included SubDrawing is used to replicate instances of a template in a drawing. Copying or cloning the subdrawing creates a new instance that uses the same template. Editing the template modifies all the instances of the subdrawing in the drawing.

To create instances of the template, first create an included subdrawing: select an object to use as a template, click on the SubDrawing From Object icon in the Object Palette and click in the drawing to position the subdrawing. If the template contains several named objects used as icons for object dynamics, enter two colon-separated resource paths, to one of the objects (ObjectPath) and its anchor point (OriginPath), and press OK. To display the whole template press OK without entering ObjectPath.
File SubDrawing
A File SubDrawing is used to replicate instances of another drawing used as the subdrawing's template. Editing the template drawing changes all instances of it in other drawings. To create a file subdrawing, click on the SubDrawing From File icon in the Object Palette, click in the drawing to position the subdrawing and define the drawing file to be used as the template. If the template drawing contains several named objects used as icons for object dynamics, enter colon-separated resource paths to one of the objects (ObjectPath) and its anchor point (OriginPath), and press OK. To display the whole template drawing press OK without entering ObjectPath.
Palette SubDrawing
The Palette SubDrawing uses some object in the drawing (palette) as a template. To create a palette subdrawing, select Object, Create, SubDrawing, SubDrawing From Palette and click in the drawing to define the subdrawing's position. If the palette contains several named objects used as icons for object dynamics, enter two colon-separated resource paths, to one of the objects (ObjectPath) and its anchor point (OriginPath), and press OK. To display the whole palette, press OK without entering ObjectPath. Edit the subdrawing's properties and enter palette object's resource path in the SourcePath attribute.

To edit the template of a container or subdrawing object, select it and use Traverse, Hierarchy Down. For File SubDrawings, traversing down loads the referenced drawing, and traversing back up saves it. For Palette SubDrawings, traversing down performs Hierarchy Down into the palette object. To delete the subdrawing's wrapper and replace it with the template, use Arrange, Explode, Object; see page 375.

To adjust the position of the subdrawing's (or container's) graphics relative to its control point, you can move their template to change its position relative to the center of the drawing or the Origin point (a round marker). You can also adjust the anchoring by pressing Shift+Control and moving the subdrawing's control point relative to its graphics, without traversing down to edit the template.

Containers and subdrawings may either be scalable or have fixed size, as controlled by their FixedSize attribute.

Containers and subdrawings may be used as nodes connected with connector objects constrained to their control point.

Attachment points can be added to the reference objects to define points that can be used for attaching other objects. For example, attachment points of a tank symbol may be used for attaching pipes. Refer to the the Attachment Points section on page 114 for more information.

Creating Animated Lines and Surfaces

For animated lines and surfaces, use the polyline and polysurface objects. A polyline is a line or set of line segments, with a defined number of points. A polysurface is a set of polygons. These are special objects used in graphs that may be animated by using a history object to address their points or segments; see page 322.

The polyline and polysurface objects use two templates. The Marker template is used for the control points of the objects. The Polygon template controls the line segments of the polyline, and the surface polygons of the polysurface. Each instance of the object is named using the template object name and an index. For example, for a two-segment polyline, there are three marker instances (Marker0, Marker1, and Marker2) and two line instances (Polygon0 and Polygon1).

The Polyline Object

A polyline is a specialized series that consists of a line or set of line segments and points.

To create a polyline, click on two points to specify the beginning and end of the polyline. The Builder prompts you for the factor, which controls the number of points along the line.

The number of segments in the polyline is controlled by its Segments attribute.

To edit the Marker template object, use Traverse, Hierarchy Down. When you finish editing, use Traverse, Up to see the instance objects. To edit the Polygon template, use Object, Resources.<

The Polysurface Object

A polysurface is a specialized, three-dimensional series object. It defines a set of surface patches.

To create a polysurface, click on a point to specify the center of the polysurface, and click on two points to specify two vectors from the center point. The Builder prompts you for the number of rows and columns in the surface; these values control the number of surface polygons.

To edit the Marker template object, use Traverse, Hierarchy Down. When you finish editing, use Traverse, Up to see the instance objects. To edit the Polygon template, use Object, Resources.

Attaching Objects to a Frame

A frame is a configuration of points that can be adjusted and positioned as a single object. Each segment of the frame is populated with frame points that let you use the frame's geometry to position objects by constraining them to the frame points. The Reference object may be used as a container to hold several objects connected to a frame, in which case the Reference's control point is attached to the frame.

There are five types of frames, which provide different configurations of frame points:

A frame has two sets of points: its own control points for controlling its geometry, and the constrained frame points for use by other objects. Use Options, Show Frame Points to toggle between the control points and the frame points; see page 418. Note that for the free frame and the point frame, the frame points and the frame's own control points coincide.

Connecting Objects with a Path

The Connector object can be used to connect other objects with a recta-linear or arc path. To create a connector, select one of the Recta-Linear Edge buttons, or an Arc Edge button, then click in the drawing to define the connector's points. The connector connects its points with either a recta-linear or arc path.

The end points of the connector can be constrained to other objects. For example, you can use reference objects as nodes and constrain the end points of a connector to the control points of references. The connector will maintain the connecting path when the nodes are moved.

The recta-linear connector also provides access to its constrained points. These points can't be edited since their position is defined by the connector's control points. However, they may be used to constrain other objects to the middle point of a connecting path. Use Options, Show Frame Points to toggle the selection display between the control points and the constrained points. Note that some constrained points (at the start and end of each path segment) coincide with control points.

Defining Extended Set of Rendering and Text Box Attributes

The Rendering object is used to define optional rendering attributes, such as gradient fill, cast shadow, arrowheads and fill dynamics. For the text object, the Box Attributes object may also be used to define attributes of the box drawn around the text.

To add rendering attributes to an object:

1. Select the object to which you want to add rendering attributes.
2. Click on the Add Rendering button at the end of the object's properties. If the Rendering object has been already added, the button name will be Edit Rendering: in this case, click on it to edit rendering attributes.
3. Change rendering attributes to define gradient fill, cast shadow, arrowheads and fill dynamics parameters.
4. To delete rendering attributes, click on the Delete Rendering button in the Rendering Properties dialog.

To add text box attributes to a text object:

1. Select the text object to which you want to add the box to.
2. Click on the Add Box Attributes button at the end of the object's properties. If the Box Attributes object has been already added, the button name will be Edit Box Attributes: in this case, click on it to edit the box attributes.
3. Change the box attributes to define the text box's appearance.
4. To delete box attributes, click on the Delete Box Attributes button in the Box Attributes' Properties dialog.

Scrolling Attributes of Objects with Index-based Names

The history object provides a way to animate resources that use numeric values in their names. When such a resource is animated, the history object provides access to each value in turn. The most obvious application for the history object is for series objects, polylines, and polysurfaces, since these objects append a numerical index to names of its template's instances. The history object can also address named resources in a group if they use the same type of naming convention and the group object's HasResources flag is turned on.

To create a history object:

1. Select the object to which you want to add a history object.
2. Select Object, Add History. The Builder prompts you for the resource name.
3. Enter the resource name, replacing the numeric part with a percent (%) sign. If the resource is not a direct child of the object you selected, specify a relative "path" to the resource.
4. The Builder adds a resource named EntryPoint to the resource hierarchy. The History object is not represented visually; its existence is indicated by EntryPoint.

For example, consider a series named S with its HasResources flag set to YES and with a template named Triangle. Its instances are named Triangle0, Triangle1, Triangle2, and Triangle3. To animate the fill color of the instances, you add a history object to S, and specify Triangle%/FillColor as the resource name. The datagen command line to animate the fill color of the instances would send data to the EntryPoint object defined at the same level as the Triangle object ($Widget/S/EntryPoint).

To animate the resource, provide input data to the EntryPoint resource. Each member of the numeric series is updated in turn.

To access a list of history objects attached to the selected object, use Object, Edit History menu option or click on the Hist button in the Status Panel. To delete a history object, select the parent object and use Object, Delete History. The Builder deletes the first history object in the list. You can also use the Delete button at the bottom of the History List to delete the highlighted history object from any position.

If you explode a series, polyline, or polysurface object that has a history object, the group that remains after exploding it retains the history object. Exploding that group discards the history object.

Rendering GIS Map Data

The GIS Object provides a way to utilize functionality of the GLG Map Server in a GLG drawing, embedding GIS map displays into GLG drawings in both the Builder and an application. The GIS Object transparently handles all aspects of low-level map-server interaction to display, zoom and pan the map.

To create a GIS Object, select a GIS Object button in the Object Palette, then click in the drawing area to define two points that specify the rectangular area to be used for the map display. Then enter the dataset file, which tells the Map Server what GIS data to render. The GIS Object provides attributes to control the projection, center and extent of the map, as well as the layers to be displayed on the map.

To set the GIS Zoom Mode, select the GIS Object and use the Arrange, GIS Zoom Mode, Set as parent viewport's GIS Object menu option. In the GIS Zoom Mode, the zoom and pan controls of the Builder zoom and scroll the map displayed in the GIS Object instead of zooming and scrolling the drawing. Refer to Integrated Zooming and Panning on page 215 and Integrated GIS Object, GIS Rendering and GIS Editing Mode on page 216 for more information.

Adding Custom Properties to Objects

Custom Data Properties may be used to associate application-specific information with an object. This information is persistent and may be saved with the drawing, or accessed using the resource access functions. The available data types of custom properties (D, S and G) match the data types of object attributes and may be used to keep information in the form of numerical values or strings.

To add custom data properties to an object:

The Data button of the Status Panel may be used to access a list of custom properties of the selected object.

Defining Logical Names using Aliases

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 a logical resource name instead of a complete path name. The alias can also be used to create convenient shortcuts for long path names.

To define an alias for a resource hierarchy:

The Alias button of the Status Panel may be used to access a list of aliases defined for the selected object.

The Mark Object and Mark List buttons in the Alias List dialog may be used to mark the currently selected alias object or the whole alias list for reuse. To add marked aliases to a different object, select the object and use Object, Aliases, Add Marked Aliases from the main menu.

Drawing a Simple Example

The following example shows how to draw and animate a couple of valves. It incorporates several of the most typical tasks encountered in building and animating a GLG drawing.Where the instructions below use the choices available from the Builder menus, you can also use toolbar and object palette buttons.

Attribute Animation

The first task is to create a drawing for the valve handle and to animate some of its simple attributes.

1. Create a viewport and name it "$Widget." Use Object, Create, Viewport to create the viewport (or click on the Viewport button in the object palette), and use the mouse to specify the viewport's corner points. Use Object, Properties or click on the Properties button on the toolbar to show the Selected Object Properties dialog. You can use this dialog to specify the viewport's name.
2. Select the viewport with the mouse (if you have just specified its name, it is already selected). Use Traverse, Hierarchy Down or the down arrow button in the hierarchy controls to go "down" into the viewport.
3. Inside the viewport, create a polygon that looks like a valve handle to you and name it "handle." Use Object, Create, Polygon to create the polygon, and use the mouse to specify the polygon's points. Press the right mouse button when you are finished specifying points. You can use the Selected Object Properties dialog to specify the polygon's name.
4. Select Traverse, Up. Open the resource browser with Object, Resources, or with the Resources toolbar button , and note that both the $Widget name and the handle name are on the same level of the resource hierarchy.
5. Close the resource browser, select the viewport, bring up the Selected Object Properties dialog, and set the viewport's HasResources flag to YES.
6. Now check the resources again. Open up the resource browser again, and note that while the $Widget resource still appears at the top level of the hierarchy, the handle resource is gone. If you double-click on the $Widget name, its subsidiary resources appear, now including the missing handle resource. This illustrates the use of the HasResources flag: it defines where in the resource hierarchy an object's children appear.
7. Double-click on the handle resource, and observe the default polygon attributes (LineWidth, FillColor, and so on) below it. Unlike named resources, these default attributes appear below the polygon object whether or not the polygon's HasResources flag is set to YES.
8. Select Run, Start and at the run prompt, issue the command:
$datagen -sin d 0 10 $Widget/handle/LineWidth
9. Select Run, Stop to stop the line width animation. Select the viewport, then Traverse, Hierarchy Down. Select the handle polygon, and bring up the Selected Object Properties dialog.
10. Next to the LineWidth attribute, there is a button labeled . The button indicates that the attribute name refers to an object. If you press it, an object dialog appears, where you can type a name for the object. Give this the name "handle_width."
11. If you were to examine the resource hierarchy now, you would see that the handle and handle_width resources are on the same level as each other. To make the handle_width appear as the child of the handle resource, use the Selected Object Properties dialog to set the HasResources flag of the handle polygon to YES.
12. Check the resource browser. You can see there the $Widget at the top level, then the handle resource below it, and the handle_width below that.
13. Select Run, Start and at the run prompt, change the default attribute name LineWidth to the resource name handle_width, and issue the command:
$datagen -sin d 0 10 $Widget/handle/handle_width

Geometrical Transformation Animation

Now that you have seen animating simple attributes and resources, we will add a geometrical transformation and animate that. Most valve handles turn, so we will add a rotation transformation.

1. If it is still going, stop the animation with Run, Stop. Select the viewport, select Traverse, Hierarchy Down, and select the handle polygon.
2. Open the Selected Object Properties dialog, and press the Add Dynamics button in it (or just click the Add Dynamics toolbar button). This opens the Add Dynamics dialog.
3. In the transformation dialog, click on the Transformation Type pulldown list, and select "Rotate." The Rotation Axis pulldown list appears. Select "Z" from that list to make the rotation happen in the plane of the drawing.
4. Press Center In Drawing and notice a prompt at the bottom of the screen. Select a point around which the polygon will rotate. A round red marker with a cross appears at that spot.
5. Set the Variable Name field to read "rotate_factor," and press the Apply button at the bottom of the dialog. This will attach the transformation and opens the Edit Dynamics dialog for editing its parameters. The dialog may later be accessed by using the Edit Dynamics button of the Properties dialog, or using the Edit Dynamics toolbar button.
6. The attributes of the rotation transformation are displayed in the dialog. The center point around which the object is rotated is there, as well as two other attributes: Factor and Angle. The angle circumscribed by a rotation transformation is given by the product of these two attributes. The Factor attribute is usually used as a normalized value, while the Angle is usually the maximum angle, in degrees. You can animate the transformation with either attribute. Note that if you press the button next to the Factor attribute name, you can see a dialog that says that this attribute is named rotate_factor, the name you typed in the previous step.
7. Use Traverse, Up to go to the top level of the drawing, and open the resource browser. You can see that rotate_factor is now a resource of the handle object, which is a resource of the $Widget viewport.
8. Select Run, Start and at the run prompt issue the command:
$datagen -sin d 0 1 $Widget/handle/rotate_factor
9. Stop the animation, select the viewport, Traverse, Hierarchy Down, select the polygon, bring up the Selected Object Properties dialog, and press Edit Dynamics.
10. Set Factor to 1. Press the button next to the Angle attribute, and give it the name, "rotate_angle."
11. Select Run, Start and at the run prompt issue the command:
$datagen -sin d 0 90 $Widget/handle/rotate_angle
Notice that the data range is from 0 to 90 now.

Creating Copies and Animating Them

Now we will add a base to the valve handle, and reproduce it so we have two valves.

1. Stop the animation, select the viewport, Traverse, Hierarchy Down, and draw another polygon to represent the base of a valve.
2. Select Arrange, Group. Click in the drawing and drag the cursor to display a box. Any objects within or touching the box will be placed into the new group. Use this to group the handle polygon, and the new polygon for the base. Display the Selected Object Properties dialog for the group, name it "valve1," and set its HasResources flag to YES.
3. Set the valve1 group's MoveMode to STICKY MODE. This setting is important when the object is moved by dragging it with the mouse. When the valve group's MoveMode is set to MOVE POINTS, moving the group moves all objects in the group by changing coordinates of their points, but it does not move the center point of the rotation transformation together with the rest of the objects. This means that after the valve is moved, it will still rotate around the original point in the drawing. If MoveMode is set to STICKY MODE, the center of rotation will move with the object, and the handle will rotate around the same position relatively to the valve.
4. Create a copy of the valve1 group. You can use Edit, Cut and Edit ,Paste, or just Edit, Full Clone. Move the copy somewhere that doesn't obscure the original.
5. Use the Selected Object Properties dialog to rename the new group "valve2."
6. Animate the valve (use Run, Start) with the command:
$datagen -sin d 0 90
$Widget/valve1/handle/rotate_angle
7. Stop the animation and try it again with:
$datagen -sin d 0 90
$Widget/valve2/handle/rotate_angle
8. Try it again with:
$datagen
-sin d 0 90 $Widget/valve1/handle/rotate_angle
-sin d 0 90 $Widget/valve2/handle/rotate_angle
9. Create an ordinary text file called "valve" containing:
-sin d 0 90 $Widget/valve1/handle/rotate_angle
-sin d 0 90 $Widget/valve2/handle/rotate_angle
Now animate the valve with the command:
$datagen -argf valve
10. To use this drawing in a program, you would use "valve1/handle/rotate_angle" and "valve2/handle/rotate_angle" as input resource names for GlgSetDResource or GlgGetDResource.

Constraining Attributes

Here we will add a constraint to the rotation of the two valves, so they will always rotate together. Constraints like these are the heart of the GLG drawing architecture.

1. Select the viewport, Traverse, Hierarchy Down, select the valve2 group, Traverse, Hierarchy Down, select the handle polygon, display the Selected Object Properties dialog, and press the Edit Dynamics button.
2. Press the [...] button next to the Angle attribute, and press the Constrain button on the left side of the Attribute dialog.
3. Press the Use Resource button in the Attribute dialog, then use the resource browser to select the resource: $Widget/valve1/handle/rotate_angle.
4. Animate the valve with the command:
$datagen -sin d 0 90
$Widget/valve1/handle/rotate_angle
Notice that both valves move together.

This example is only meant to illustrate some of the basic procedures involved in using the GLG Graphics Builder to create and animate a GLG drawing, and it only scratches the surface of what is possible. You may find it profitable to work out some similar simple exercises before starting in on a large project.

Builder Setup and Customization

Environment Variables

Environment variables may be used to define the location of the GLG installation directory and other GLG components. The version-specific environment variables that define the location of the installation directory, configuration file, palette location and log directory have two forms: a generic form (i.e. GLG_DIR) and a version-specific form (i.e. GLG_DIR_X_Y, where X and Y are the major and minor GLG version numbers). The version specific form may be used to prevent conflicts when one machine has more than one version of the GLG Builder installed.

In addition to environment variables, a number of command-line options is also supported for both the Graphics Builder and the HMI Configurator. Some of the options are listed below; use the -help command-line option to list all options. On Windows, the output is saved into the glg_error.log file.

The following lists the most frequently used environment variables. Refer to Appendices on page 423 of the GLG Programing Reference Manual for a full list of global configuration resources that can be defined in the Builder or HMI configuration file (described in the Builder Configuration File section), as well as the corresponding environment variables.

GLG_DIR
Defines the location of the GLG installation directory, is set by default on Windows.
GLG_CONFIG_FILE
GLG_HMI_CONFIG_FILE
Defines the location of the configuration files for the Graphics Builder and HMI Configurator, if it is different from the default.
GLG_PALETTES_LOCATION
GLG_HMI_PALETTES_LOCATION
Defines the location of the GLG widgets directory for the Graphics Builder and HMI Configurator, if it is different from the default.
GLG_LOG_DIR
Defines the directory of the GLG error log file, if it is different from the default.
GLM_LOG_DIR
Defines the directory of the error log file for the Builder's Map Server component, if it is different from the default.
GLG_VERBOSE
If set to True, enables additional output when troubleshooting OpenGL driver, editor setup, loadable editor extension DLLs and other editor extensions. The -verbose command-line option may also be used.
GLG_OPENGL_MODE
If set to True, enables the OpenGL renderer. If set to False, a native windowing system renderer will be used. The -glg-enable-opengl and -glg-disable-opengl command-line options may also be used.
GLG_OPENGL_VERSION
Specifies the value of GlgOpenGLVersion which requests the specified OpenGL version. The -glg-opengl-version <NNN> command-line option may also be used.
The shader-based Core OpenGL profile is used for OpenGL versions higher than 3.00, and the Compatibility profile is used for older OpenGL versions. The Core profile is used by default, switching to the Compatibility profile if an older graphics card doesn't support the Core profile.
GLG_DEBUG_OPENGL
If set to True, generates extended diagnostic output for the OpenGL driver in the glg_error.log file.
GLG_OPENGL_HARDWARE_THRESHOLD
Specifies the value of GlgOpenGLHardwareThreshold. The -glg-opengl-hardware-threshold <N> command-line option may also be used.

All viewports with a non-zero value of the OpenGLHint attribute, less than or equal to GlgOpenGLHardwareThreshold, will be rendered using the hardware OpenGL renderer (if available). Viewports with the attribute value between GlgOpenGLHardwareThreshold and GlgOpenGLThreshold will be rendered using the software OpenGL renderer (if available).
GLG_OPENGL_THRESHOLD
Specifies the value of GlgOpenGLThreshold. The -glg-opengl-threshold <N> command-line option may also be used. All viewports with a value of the OpenGLHint attribute greater than GlgOpenGLThreshold will be rendered using the GDI renderer.
GLG_DISABLE_HARDWARE_OPENGL
If set to True, disables hardware OpenGL. The -glg-disable-hardware-opengl command-line option may also be used. If the OpenGL driver is enabled, only the software-based OpenGL renderer will be used.
GLG_DISABLE_SOFTWARE_OPENGL
Disables software OpenGL. The -glg-disable-software-opengl command-line option may also be used. If the OpenGL driver is enabled, only the hardware-based OpenGL renderer will be used.
GLG_X_RESOURCE_FILE
Specifies location of a custom X resource file for customizing XFT fonts used by native input objects on Linux.
GLG_DISABLE_TIMERS
Disables timer transformations in the drawings for debugging purposes.
GLG_WIDGET_EDITING_MODE
If set to True, widgets loaded from the palettes with Ctrl+click may be saved into the original drawing files, facilitating convenient editing of widgets in the custom widget palettes. Without this option, a copy of a modified widget is saved in the current directory by default, to avoid permanently overwriting widgets in the GLG Builder palettes. The -widget-editing-mode command-line option may also be used.

Note: Environment variables that control diagnostic output and driver rendering modes modify the behavior of both the GLG Builder and the GLG applications at run-time. To modify only the Builder's behavior, use the corresponding global environment variables settings in the Builder configuration file, if possible.

Builder Configuration File

The glg_config configuration file contains the most common initial settings for customizing the GLG Builder, such as a number of colors in the color palette, color RGB entries format, modality of the Builder's dialogs and other options. The configuration file is located in the GLG installation directory by default. On Unix, it may be named ".glg_config" and placed into the users' home directory to allow per-user customization. The GLG_CONFIG_FILE environment variable described in the previous chapter may be set to point to a configuration file in a non-standard location. The Builder configuration file affects only the GLG Graphics Builder. It does not affect GLG applications at run time, which must use GLG Programming API for its customization.

To avoid conflicts between several versions of the GLG Toolkit installed on the same machine, a version specific configuration file may be provided in the form glg_config_X_Y, where X and Y are the major and minor GLG version numbers.

For the HMI Configurator, the glg_hmi_config configuration file and GLG_HMI_CONFIG_FILE environment variable are used.

Configuration File Syntax

Each line of the configuration file contains a name of the configuration variable followed by the "=" sign and the variable's value. A string is expected as a value for variables of the S type, a double value must be specified for variables of the D type, and a triplet of three double values must be specified for variables of the G type.

The configuration file also provides access to the GLG global configuration resources. The variables in the configuration file whose name starts with the "Glg" prefix provide initial setting for the corresponding global configuration resource. For example, the GlgPickResolution variable in the configuration file sets the value of the GlgPickResolution global configuration resource. Refer to Appendices of the GLG Programming Reference Manual for a list of the global configuration resources.

Comment lines may be introduced by using the "#" character at the beginning of the line.

Configuration Variables

Configuration variables for the Graphics Builder and HMI Configurator are described in the self-documented configuration files, glg_config and glg_hmi_config, respectively.

UTF-8 Locale and XFT Fonts Support on Linux

On Linux, both the GLG Graphics Builder and the GLG HMI Configurator support UTF-8 locale and can be used with multiple languages without a need to change font settings. The text input boxes in the GLG editors use XFT fonts that transparently support multiple charsets.

X resources can be used to customize XFT fonts used by text boxes and other native input objects in both the GLG editors and the C/C++ executables. Instead of defining X resources in the system configuration files, a custom X resource file can be supplied by using the -glg-x-resource-file command-line option, as well as setting either the GLG_X_RESOURCE_FILE environment variable or the GlgXResourceFile global configuration resource described in the Appendices of the GLG Programming Reference Manual. A sample glg_x_resource_file file with default settings is provided in the src directory of the GLG installation.

The XFT fonts used for text objects inside GLG drawings are defined by the font table of the viewport's Screen object. The default font table can be modified to customize a list of fonts used in the drawing. Refer to the Editing a Font Table section on page 163 for more information.

Custom Widget Palettes

Custom widgets can be added to the existing palettes by editing .pal palette files. Custom palettes can also be integrated into the GLG Builder and HMI Configurator by adding them the palettes.pls file, refer to Adding Custom Widgets and Custom Palettes on page 357 for more information.

OEM Customization

OEM Customization features allow extending GLG editors' functionality with application-specific features. It may be applied to both the GLG Graphics Builder and GLG HMI Configurator.

The simplest customization includes defining a custom color palette and custom dynamics options for the OEM version of the GLG editor. For more elaborate customization, the OEM integrator may provide custom components with a predefined set of properties for use with the GLG HMI Configurator. For even further customization, loadable DLLs may be provided to extend GLG editors with custom OEM functionality, such as connecting to a custom data source or supplying application-specific menu options, toolbar icons and dialogs.

Custom Color Palettes

In addition to the default color palette, GLG editors provide a custom color palette. The custom color palette may be activated by using Options, Color Options, Swap Color Palettes. If the color palette is displayed, Ctrl+click on it also toggles the displayed palette.

To supply your own custom color palette, edit the custom color palette template drawing provided in the editor_extensions/drawings/custom_color_palette.g directory of the GLG installation and copy it to the main directory of the GLG installation. The -custom-color-palette command-line option may also be used to supply a custom color palette drawing for the Builder or HMI configurator:

-custom-color-palette editor_extensions/drawings/custom_color_palette.g

The custom color palette drawing can also be specified in the GLG configuration file using the CustomColorPalette variable, or by setting the GLG_CUSTOM_COLOR_PALETTE environment variable.

The template drawing contains a GLG palette widget with the GlgPalette interaction handler. The widget contains two groups: the PaletteObject group containing objects whose FillColor attribute defines the palette's colors, and an optional Labels group that contains text labels used for annotating the color names. To change the palette, add or delete the objects in each group as needed and change their colors. Refer to the GlgPalette section on page 259 for details of the GlgPalette input handler.

Indexed Color Palette

Specifying Indexed Colors for GLG Editors

A custom color palette can also define indexed colors. To define indexed colors, a color palette should define an IndexedColorGroup resource, which is a group containing objects named Item1, Item2, and so on. The FillColor resource of each item should contain the RGB value of a corresponding indexed color. For example, FillColor of Item1 defines the RGB value of the indexed color specified by (-1,0,0), and FillColor of Item2 defines RGB of the index color (-2,0,0).

The provided custom_color_palette.g palette sample file described above defines the IndexedColorGroup resource and indexed color items. When it is used as a custom color palette (which is the default), the indexed color list is populated with RGB values of the indexed colors defined in the palette. This allows the user to experiment with indexed colors by entering their values manually, such as (-3,0,0) to use the third color from the palette, but an RGB value will still be used when a color is selected from the custom palette using the mouse. That can be changed by defining a resource named UseIndexedColors and setting the value of the resource to 1 in the custom palette drawing. The custom_color_palette.g drawing defines this resource, but has its value set to 0 by default to use RGB values for custom color instead of indices. This avoids a need to define a list of indexed colors at run time if indexed colors are not used.

The indexed_color_palette.g file in the editor_extensions/drawings directory of the GLG installation is an exact copy of the custom_color_palette.g file, but with the UseIndexedColors resource set to 1. When this file is used as a custom color palette, an indexed color value is used instead of color RGB when a color is selected from a custom palette in the Builder using the mouse.

A custom color palette with indexed colors can be used in the GLG editors via a command-line option or by specifying it in the GLG configuration file, as described in the previous section. When used, the custom palette provides both a custom color palette and a list of indexed colors. An ASCII file option described below can also be used to define a list of indexed colors for drawings displayed in the GLG editors. The ASCII file specifies a list of indexed colors without supplying a custom color palette.

Specifying a List of Indexed Colors at Run Time

The indexed color palette drawing used to define a custom color palette for the Graphics Builder can be used to define a list of indexed colors at run time by setting either the GlgIndexedColorTable global configuration resource or the GLG_INDEXED_COLOR_TABLE_FILE environment variable (for C/C++ and ActiveX) to the filename of the palette drawing file. The GLG_PATH is used to search for the file if a relative filename is used.

A human-readable ASCII file can also be used to define indexed colors for run time. The indexed_colors.txt file in the editor_extensions/drawings directory of the GLG installation provides self-documented example that demonstrates the use of different decimal and hexadecimal formats. An ASCII indexed color list can be used at run time be setting either the GlgIndexedColorFile global configuration resource or the GLG_INDEXED_COLOR_FILE environment variable (for C/C++, ActiveX and also the GLG editors). The GLG_PATH is used to search for the file if a relative filename is used.

The global configuration resources that specify a list of indexed colors at run time should be set at the beginning of a program right after initializing the Toolkit with GlgInit and before the hierarchy setup of the drawing.

OEM Version of the Graphics Builder

The OEM version of the GLG Graphics Builder provides additional functionality for defining public properties. The public properties feature makes it possible to create custom components with a predefined set of properties for simplified editing. The component's properties exposed as public properties are displayed in the Public Properties dialog for easy editing.

Since this functionality is used only for OEM customization, it is provided only when requested via a command-line option to avoid cluttering user interface for the rest of the users. The OEM version may be started by using the -oem command-line option of the Enterprise Edition of the Graphics Builder:

GlgBuilder  -oem

Once a component's public properties are defined using the OEM version of the Builder, they may be used for editing the component in all GLG editors, including the HMI Configurator.

Export Tags

Export tag is a special type of a tag object that can be attached to an object's attribute to mark it as an exported public property. Public properties of an object may be displayed using the Object, Public Properties menu option of the OEM version of the Graphics Builder. Public properties are also displayed in the GLG HMI Configurator, which allows creating custom components with user-defined properties for use with the HMI Configurator.

Instead of a single button to add data tags, the OEM version of the Builder provides two buttons for adding tags: the DT button for adding Data Tags and ET for adding Export Tags. If a data or export tag has been added to the attribute, the corresponding button's label changes to DT+ or ET+ to indicate the presence of a tag. If a tag is present, it may be edited by clicking on the corresponding button.

The export tag's TagName attribute defines the name of the public property. This name will be displayed as a property name for the attribute in the Public Properties dialog. The export tag's TagType attribute may have the following values:

EXPORT
Used to mark the attribute as a public property.
EXPORT_DYN
Used to mark the attribute as a public property of predefined dynamics, action commands and action data sets. Refer to the Custom Predefined Dynamics section below for more information.

When accessing attributes of an object via resources, the export tags may be accessed only for resources that use default attribute names and not for named resources.

Public properties are global: all public properties appear in the object's public properties list regardless of the hierarchy level they are defined at. The GlgQueryTags and other GLG API methods may be invoked with the tag_type parameter set to GLG_EXPORT_TAG to query object's public properties.

The Arrange, Delete Public Properties button of the Enterprise Edition of the Graphics Builder can be used to delete all public properties of the selected object.

Public Properties

Public properties defined in the OEM version of the Builder via export tags are used to create custom components that can be used in all versions of the GLG Builder and the HMI Configurator. Public properties of a custom component can be conveniently edited using the Public Properties dialog.

The Graphics Builder provides two menu choices and two toolbar buttons for displaying object properties: Properties displays an object's attributes and Public Properties displays its public properties.

The HMI Configurator has only one Properties toolbar button by default. If the selected object has public properties, the button will display its public properties, otherwise it will display regular properties of the selected object. This allows a system integrator to simplify widget editing by exposing only a limited set of essential widget properties. To enable both Properties and Public Properties toolbar buttons, set HMISinglePropertyButton = 0 in the glg_hmi_config configuration file.

The Palettes, Custom Widget Samples menu displays a palette with samples of custom components that have public properties. The Object, Public Properties menu option or the Public Properties toolbar icon may be used to browse public properties of a selected component.

To prevent slow response times when a viewport with a large number of public properties is selected, the Public Properties dialog displays only the first 50 public properties of the selected object by default. This number can be changed using the GlgPublicPropertiesMaxNum variable in the glg_config or glg_hmi_config file.

Custom Components with User-Defined Properties

Custom components are objects with public properties defined using export tags described in the previous chapter. Custom components with user-defined properties provide end users with application-specific building blocks with properties that are related to the application logic. Refer to the previous chapter for more information on using custom components in the HMI Configurator.

To create a custom component:

1. Start the OEM version of the Graphics Builder by using the -oem command-line option of the Enterprise Edition of the Graphics Builder.
2. Create graphics to represent the component. If the graphics contains several objects, use a group or a container object to encapsulate the graphics as one object. Add any required dynamics.
3. Add export tags to the attributes of the graphics or dynamics to define public properties.
4. Name the top level object $Drawing to use it in the GLG editors' palettes and provide an optional $Icon graphics if desired. Refer to Palettes on page 355 for more information on palette drawing conventions.
5. Save the drawing and copy it into one of the GLG palettes directories. Refer to Adding Custom Widgets and Custom Palettes on page 357 for more information.
Group Object Settings for the HMI Configurator

Objects created in the HMI Configurator are marked with an internal HMIFlag flag to differentiate them from the custom components and objects created in the Graphics Builder. The HMI Configurator imposes restrictions on editing objects created in the Graphics Builder. For example, the HMI Configurator allows to explode group objects only if they were created in the HMI Configurator. The Options, OEM Options, Toggle Object's HMI Flag option may be used to change HMIFlag setting if required.

Custom Predefined Dynamics

GLG editors provide 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 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 are implemented using custom transformations which represent a collection of several stock transformations wired together to implement 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.

Predefined Dynamics Template Drawing

The editor_extensions/drawings/custom_xform_templates.g file of the GLG installation provides a template that contains the default predefined dynamics. To add custom predefined dynamics, this drawing may be edited using the OEM version of the Enterprise Edition of the Builder (use the
-oem command-line option to start the Builder in the OEM mode).

When finished, copy the drawing to the main directory of the GLG installation. The -xform-templates command-line option may also be used to supply the drawing containing a custom predefined dynamics template for the Builder or HMI configurator:

-xform-templates <glg_dir>/editor_extensions/drawings/custom_xform_templates.g

The drawing containing a custom predefined dynamics template can also be specified in the GLG configuration file using the CustomXformTemplates variable, or by setting the GLG_CUSTOM_XFORM_TEMPLATES environment variable.

The predefined dynamics template drawing contains the XformTemplates viewport, which contains several groups of objects, one for each transformation subtype:

All groups are optional and some of the groups can be removed if necessary. Each object in the group defines a certain type of predefined dynamics, and the name of the object in the group defines the label displayed in the predefined dynamics menu. The order of predefined dynamics in the menu is defined by the drawing order of the objects in each group, not by the visual order of their appearance in the drawing. The Arrange, Reorder menu options may be used to change the drawing order of the objects in a group.

Each object in a group has a transformation named XformObject attached to one of the object attributes, as indicated by the "X" button on the right side of an attribute row in the object's Properties dialog. For objects in the GeomXform group, the transformations are added to the objects themselves instead of their attributes. The transformation defines custom predefined dynamics and may contain a complex collection of transformations wired together to perform a custom dynamic action.

The object must also define an S type resource named XformLabel which defines a custom transformation type shown in the Edit Dynamics dialog. The XformLabel resource is usually defined as a custom object property accessible via the Data button in the status panel.

Some transformation (such as Flow in the LineTypeXform group) may have InitFromObject custom property attached to the object. Setting the value of InitFromObject to 0 ensures that the transformation is not modified when it is attached to an object. By default, the first element of a list transformation is initialized to the value of the attribute the list transformation is attached to. This preserves the color of the object when a list transformation is attached to its color attributes, or preserves the text string when a list is attached to the TextString attribute. For some transformations, such as Flow, such initialization would interfere with the transformation's logic, and setting InitFromObject to 0 prevents the transformation from being modified when it is attached to an attribute.

The XformObject transformation uses export tags to define public properties visible in the Edit Dynamics dialog. Export tags are attached to the attributes of the transformation that need to be visible to the user. The export tag's TagName defines the property name that will be shown in the Edit Dynamics dialog. The export tag's TagType must be set to EXPORT_DYN to export the attribute as a public property of the predefined dynamics. Refer to the OEM Version of the Graphics Builder section above for more information on export tags.

Once export tags are added to a transformation, its Edit Dynamic dialog will list the transformation's exported public properties instead of its attributes. The Options, Dynamics Options, Full Display of Predefined Dynamics menu option toggles the display of predefined dynamics between public properties and attributes. This option can be used for getting access to the attributes of the transformation for editing.

To allow accessing the attribute via resources in the HMI Configurator, the attribute is usually named the same way as the public property name specified by the TagName attribute of the export tag. Data tags may be added to the exported public properties for use with the HMI Configurator. The name of a data tag is specified via the data tag's TagName attribute and usually matches the TagName of the attribute's export tag.

Predefined dynamics are usually constructed by wiring together several transformations, with second-level transformations added to the attributes of the top-level transformation. Public properties are global: public properties defined by export tags of transformations on any level are listed as a flat list of public properties for the top-level transformation.

If predefined dynamics are added to a transformation's attribute as a second-level transformation instead of a stock transformation, public properties of the second-level transformation are not listed as the properties of the parent transformation due to the setting of an internal flag. To unset the flag and make public properties of the second-level transformation listed as properties of its parent, uncheck the Options, OEM Options, Toggle Custom Xform Flag option for the second-level transformation object.

The LineTypeXform group defines additional transformation for the LineType attribute, in addition to the transformations from the DXform group that will be automatically appended to the list.

Adding Predefined Dynamics

To add or delete predefined dynamic options, add or delete objects from the corresponding groups in the template drawing and edit the XformObject transformations attached to the objects' attributes. To define new predefined dynamics:

1. Start the OEM version of the Graphics Builder by using the -oem command-line option of the Enterprise Edition of the Graphics Builder and load the predefined dynamics template drawing from the <glg_dir>/editor_extensions/drawings/custom_xform_templates.g file.
2. Add a new object to a corresponding group and define its name and XformLabel property as listed above.
3. Make sure that the Options, Dynamics Options, Full Display of Predefined Dynamics option is checked to display the transformation's attributes instead of public properties.
4. Add a stock transformation to the object.
5. Add transformations to any of its attributes as required to implement custom dynamic behavior. Use stock transformations to simplify the process of defining public properties.
6. Add export tags to the attributes of a transformation that need to be shown as transformation's properties. To add an export tag to a transformation's attribute, click on the ellipses button next to the attribute in the Edit Dynamics dialog, then press the ET (Export Tag) button the Attribute dialog.
7. Uncheck the Options, Dynamics Options, Full Display of Predefined Dynamics option and verify the list of the transformations' public properties.
8. Use the modified drawing with the -xform-templates command-line option to test the new predefined dynamics.

Custom Data Sets and Custom Commands

Custom data sets may be used to define predefined sets of data to be added to objects as custom data, action data or action commands. Custom data sets are contained in a group object that holds individual data elements. Data elements of action and command data have EXPORT_DYN export tags attached to export them as public properties visible in the Public Properties dialog for editing action or command data.

Predefined Custom Command Template

The editor_extensions/drawings/custom_command_templates.g file of the GLG installation provides a template that contains predefined commands and data sets. To add custom data sets and/or custom commands, this drawing may be edited using the OEM version of the Enterprise Edition of the Builder (use the -oem command-line option to start the Builder in the OEM mode).

When finished, copy the drawing to the main directory of the GLG installation. The -command-templates command-line option may also be used to supply the drawing containing a custom predefined commands template for the Builder or HMI configurator:

-command-templates <glg_dir>/ditor_extensions/drawings/custom_command_templates.g

The drawing containing a custom commands template can also be specified in the GLG configuration file using the CustomCommandTemplates variable, or by setting the GLG_CUSTOM_COMMAND_TEMPLATES environment variable.

The predefined command template drawing contains three groups of objects:

Each object in the group defines a command or a predefined data set, and the name of an object will be used as a label displayed in the list of choices in the Builder. The order of commands or data sets in the list is defined by the drawing order of the objects in each group, not by the visual order of their appearance in the drawing. The Arrange, Reorder menu options may be used to change the drawing order of objects in a group.

Each object in a group has a custom data attached to define a corresponding command or data set. The custom data attached to each object define data elements of the corresponding command or data set. Data elements of command or action data sets use export tags to define public properties visible in the Edit Command or Edit Action Data dialog. The export tag's TagName defines the property name that will be shown in the edit dialog. The export tag's TagType must be set to EXPORT_DYN to export the attribute as a public property of the predefined data set. Refer to the OEM Version of the Graphics Builder section above for more information on export tags.

The Options, Selection Options, Edit Action Data as List menu option toggles the way action and command data of the SEND_COMMAND and SEND_EVENT actions are displayed for editing: as a public properties dialog, or a list of properties that allows adding and removing individual properties. A button in the upper right corner of the Action Properties dialog provides a convenient shortcut.

To allow accessing data elements of each data set via resources, each data element is named. For the command and action data sets, the name is the same as the public property name specified by the TagName attribute of the export tag.

Adding Custom Commands and Custom Data Sets

To add or delete commands or custom datasets, add or delete objects from the corresponding group in the command template drawing. To define new commands or custom data sets:

1. Start the OEM version of the Graphics Builder by using the -oem command-line option of the Enterprise Edition of the Graphics Builder and load the command template drawing from the <glg_dir>/editor_extensions/drawings/custom_command_templates.g file.
2. Add a new object to a corresponding group, define its name and add custom data with data elements as described above.
3. Use the modified drawing with the -command-templates command-line option to test the new commands and custom data sets.
4. Uncheck the Options, Selection Options, Edit Action Data as List menu option, add new command or custom event data set and verify the list of its properties.

OEM Editor Extensions

GLG editors support OEM editor extensions in the form of loadable DLLs (or shared libraries on Linux/Unix platform). The same DLL may be used for all editions of the GLG Graphics Builder as well as the GLG HMI Configurator.

The following extensions are available and described in the next sections:

The GLG installation includes examples of all available extensions in the editor_extensions directory. All examples contain a run script for starting a GLG editor with the extension DLL. They also contain self-documented source code, a makefile and/or project file for building the extension, and a README file with more information. The Editor Extension API Files section of this chapter describes common files used by all DLL examples.

All OEM Extension DLLs may use both the GLG Standard and Extended API for implementing the extension. Since the DLLs are used with the GLG editor and use its Extended API, the extension DLLs themselves are royalty-free and do not require any additional GLG libraries.

The custom extension DLLs may be deployed in the Graphics Builder or HMI Configurator by using the command-line options or configuration file variables listed in the corresponding sections below. Each DLL may also be deployed by using a default DLL name and placing the DLL into the directory where the editor executable is located. On Linux/Unix, an extension DLL with a default name may also be placed into any location where it will be searched for by the dynamic linker (such as /usr/lib or a location specified by a LD_LIBRARY_PATH environment variable). On Windows, an extension DLL with a default name may also be placed into any location where it will be searched for by the LoadLibrary function.

The default name of an extension DLL is formed by a base name and extension. The following lists the default base names of the custom extension DLLs:

Custom Data Browser DLL
libglg_custom_data    (Linux/Unix)
glg_custom_data         (Windows)
Custom Run Module DLL
libglg_custom_proto    (Linux/Unix)
glg_custom_proto         (Windows)
Custom Editor Options DLL
libglg_custom_option    (Linux/Unix)
glg_custom_option         (Windows)

The extension uses a platform's standard extension for dynamic libraries: .dll on Windows, .so on Linux and most Unix platforms, .sl on HPUX. For example, the default name of the Custom Data Browser DLL is glg_custom_data.dll on Windows and libglg_custom_data.so on Linux.

Custom Data Browser DLL

A custom data browser DLL may be provided for connecting to proprietary data sources to browse available tags in a GLG editor to select a tag's data source. The Browse button in the Data Tag dialog starts a Data Browser that will use the supplied custom data DLL for selecting a tag source. When the tag selection is made, the selected tag is inserted into the data tag's TagSource field. The DLL is also used by the Data Browser widget available at the application runtime.

The example is located in the editor_extensions/data_browser_example directory and works with both the GLG Graphics Builder and the GLG HMI Configurator.

The run_data_example script in the example's directory may be used to run the GLG Builder with a custom data browser. The script can be edited to define the version of the GLG editor to run. To test the data browser, run the script to start the Builder, add a tag to an object's attribute and click on the Browse button of the Data Tag dialog to start the tag browser. Select a controller, tag group and tag, then press Select to insert selected tag into the TagSource field.

The example source code is self-documented and provides an example of browsing a hierarchical process database with several levels of hierarchy: controller, tag group and tag. The syntax used to separate the controller, tag group and tag entries in the selected TagSource is just an example and may be changed to fulfill custom application requirements.

A custom data browser DLL can be deployed via the -data-lib command-line option as shown in the README file, via the CustomDataLib variable of the glg_config and glg_hmi_config configuration files, or by placing a DLL with a default name in the directory of the GLG Editor or application program executable. The GlgCustomDataLib global configuration resource can also be used at run time to specify the custom data browser DLL.

Custom Run Module DLL

A custom proto DLL may be provided for animating the drawing with real data in the Run mode of the GLG editor, as well as handling user interaction. object selection and custom runtime dialogs with an application-specific runtime logic.

The module has access to a complete GLG API, both the Standard and Extended, making it possible to implement a complete application integrated with a GLG editor. The application will function in the editor's Run mode, while the Edit mode may be used for editing the application's drawing.

For even further customization, the -run command-line option or the StartRun configuration file variable can be used to start the GLG editor in the Run mode. The -run-window command-line option or the RunWindow configuration file variable can be used to start the Run mode in a separate window, hiding the GLG editor's menus and toolbars. The custom option DLL described in the next section may be used to add custom OEM menu options for the Run mode.

Since the module uses the GLG API supplied by the GLG editor's executable, it may use both the GLG Standard and the Extended API with no additional GLG libraries required. When the module is used with the GLG Graphics Builder or HMI Configurator, the editors provide the module with the Run-Time license for the Extended API.

The example is located in the editor_extensions/custom_proto_example directory and works with both the GLG Graphics Builder and the GLG HMI Configurator.

The run_proto_example script in the example's directory may be used to run the GLG Builder with a custom data browser. The script can be edited to define the version of the GLG editor to run.

The sample source code is self-documented and provides an example of animating objects in the drawing via tags. The code queries a list of all tags defined in the drawing and animates them with random data. In a real application, the code can animate the tags with real data from a process database based on the tags' TagSource. Tags based data access allows an application to animate an arbitrary drawing without any knowledge about its structure or resources. The example also demonstrates the use of resources, custom popup dialogs and handling user interaction.

To check the proto DLL's functionality, run the run_proto_example script to start the Builder, then start the Run mode. The DLL will load and display the popup dialog from the dialog.g file, updating it with the status information using resources. The DLL receives and processes all input events. When the user presses the Stop button, the DLL stops the Run mode of the Builder and returns to the Edit mode.

A custom proto DLL can be deployed via the -proto-lib command-line option as shown in the README file, via the CustomProtoLib variable of the glg_config and glg_hmi_config configuration files, or by placing a DLL with a default name in the directory of the GLG Editor executable.

In addition to the cross-platform GLG-based dialogs, the module may also use native dialogs, based on Windows' Win32 API or Xt/Motif on Linux/Unix.

Custom Editor Options and Dialogs DLL

The custom editor options DLL may be provided for adding custom icons, menu options and dialogs with application-specific logic to the GLG editors. The module may also be used to verify the drawing against a custom set of rules before saving it into a file, as well as remove unwanted editor icons and menu options.

The example is located in the editor_extensions/data_browser_example directory and works with both the GLG Graphics Builder and the GLG HMI Configurator.

The run_data_example script in the example's directory may be used to run the GLG Builder with a custom data browser. The script can be edited to define the version of the GLG editor to run.

The sample source code is self-documented and demonstrates how to add a custom OEM menus and toolbar icons to a GLG editor. The code provides examples of implementing both push buttons and toggle buttons, as well as cascading sub-menus. It also shows how to change sensitivity of the menu options depending on an object selection and the GLG editor's mode: Edit or Run.

One of the OEM menu options demonstrates how to implement a custom OEM dialog that performs a custom OEM action in the editor's Edit mode. The example also includes code samples showing how to customize the GLG editor by removing unwanted icons and menu options.

To check the proto DLL's functionality, run the run_proto_example script to start the Builder and notice the OEM Sample Menu appearing after the Edit menu. It will also appears in the popup menu. A custom OEM icon (a red square with the OEM label) will appear near the right side of the editor's toolbar. The OEM icon and menu entries become active when an object is selected.

Create an object, select it and try the OEM menu options. The Add/Edit Custom Value menu option and the OEM toolbar icon activate an OEM dialog that adds an OEM property to the selected object and allows the user to edit its value. The property is visible in the Resource Browser as OEMProperty. The sample code also checks and sets the object's HasResources flag if necessary. The code demonstrates how to implement both modal and non-modal custom dialogs.

The OEM menu contains options for both the Edit and Run modes. Starting the Run mode disables edit options and enables runtime options of the OEM menu. The custom editor options DLL may also implement the functionality of the custom run mode DLL described in the previous section, making it possible to provide a single DLL that handles both the OEM editor options and the OEM runtime mode.

A custom options DLL can be deployed via the -option-lib command-line option as shown in the README file, via the CustomOptionLib variable of the glg_config and glg_hmi_config configuration files, or by placing a DLL with a default name in the directory of the GLG Editor executable.

Refer to the ADDING CUSTOM ICONS section of the README file for information on the process of defining custom icons used by the module.

In addition to the cross-platform GLG-based dialogs, the module may also use native dialogs, based on Windows' Win32 API or Xt/Motif on Linux/Unix.

Editor Extension API Files

All extension DLL examples project files (and makefiles on Linux/Unix) for building the extension DLL. The following files are provided in the example directories:

sample.c
Example's source code.
glg_custom_dll.o
Provides GLG API for the custom DLL. Don't delete this file when cleaning the project directory.
glg_custom_dll.h
An include file for using the GLG API in a custom DLL.

The Custom Run Mode and Custom Editor Options examples also provide the following files:

glg_custom_editor_dll.o
Provides GLG Editor Extension API for the custom DLL. Don't delete this file when cleaning up the project directory.
glg_custom_editor_dll.h
An include file for using the GLG Editor Extension API in a custom DLL.


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