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 139
Start the Builder, and identify its features	page 140
Create a drawing and add objects to it	page 139
Edit an object, including changing its geometry and setting its attributes	page 146
Create constraints between object attributes	page 152
Apply transformations to objects and to attributes	page 155
Define objects as resources, and arrange them in a hierarchy	page 160
Animate a drawing	page 167
Work with advanced objects	page 176
Creating and animating objects: a tutorial example	page 185

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:

The dialogs for editing a graphical object's attributes and transformations provide access to the objects below it in the hierarchy; see page 147.

For a drawing with named resources, the Builder lets you browse a hierarchy of resources, very similar in appearance to a file and directory structure; see page 160.

For a transformed object, the Builder lets you view the original, untransformed object. The drawing area shows a single level of the hierarchy of graphical objects, and you use Traverse , Transformation Down and Traverse , Up to move between the levels; see page 155.

For a composite object, the Builder lets you view the different parts of the object; use Traverse , Hierarchy Down and Traverse , Up to move between the levels; see page 176.

Starting and Stopping the Builder

For UNIX users, start the Builder by opening a command line window and typing:

$ GlgBuilder

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

$ GlgBuilder filename

For Windows NT users, start the Builder by choosing GLG Graphics Builder from the Start Menu.

The following command-line options are also supported:

-help (Unix only)

prints available command-line options.

-verbose

generates extended diagnostic output.

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

A verbose mode may also 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.

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 Object Palette contains buttons for drawing 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.

The Hierarchy Controls navigate through these objects.

The zoom , and rotate controls let you control your view of the drawing area.

The Status Panel displays information about the selected object, as well as messages and prompts for action.

Stopping the GLG Graphics Builder

On both platforms, you use File , Exit to close the Builder; see page 199.

Creating a Viewport

Although the Builder's drawing area is an infinite space, a drawing should be contained within a defined area. A viewport sets the boundaries of a drawing, acting as a backdrop and container for other objects. The Builder itself does not require that you draw the objects within a viewport, but you must use one if you want to display the drawing with another 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 menu option. You'll see this viewport when you save the drawing.

When you start a new drawing using the File, New menu option, we recommend that you draw a viewport first, to act as a container for other objects. To draw the viewport:

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:

If the viewport is not selected, select it by clicking on it with the mouse.

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.

Saving a Drawing

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

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.

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.

P stands for position . Click on a spot to specify the position of the new point. This method is the default.

C stands for constrain. Click on an existing control point to constrain the new point to the existing control point; see page 152.

U stands for use position. Click on an existing control point to use the same coordinate values for the new point. The points merely use the same coordinates; they are not constrained, so moving one point has no effect on the other.

V stands for value . The Builder prompts you to specify the position of the new point by typing values in a dialog.

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

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 244. 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:

The text object, which presents string data.

Simple graphical objects, which are just shapes, such as polygons, parallelograms, arcs, and markers.

Advanced objects, which are specialized arrangements of objects that provide special behaviors. The advanced objects are viewport, group, reference, series, square series, polyline, polysurface, connector and frame objects; see page 176.

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

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

The Selection Display button in the Options menu ( Ctrl-N accelerator) can be used to toggle 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.

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

To select objects that are located close to each other, use Shift+click to bring a menu that allows you to select an object out of several potentially selected objects. If the Properties dialog is open, the arrow button in the upper right corner of the dialog may be used to select an object when several objects are potentially selected.

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 MS Windows environment, some viewports require special treatment to move. For instructions on dealing with this special case, see page 227.

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 pull-down 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 to allow defining the selection rectangle with the mouse.

The Arrange pull-down menu provides the Permanent Group option for changing the group type from temporary to permanent and back. It also provides explicit options for creating both temporary and permanent groups, and 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 177 for information on how to perform an action on objects in a group.

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 change its appearance, edit its attributes.

To change its size, move its box points.

To change its geometry, move or edit its control points.

To flip the object, click on one of the Flip Object icons in the Control Panel on the left of the Drawing Area.

To rotate the object, move its rotate point.

To scale or rotate the object by a precise amount, click on the Transform Object icon in the Control Panel on the left of the Drawing Area, then select a desired transformation type and define its parameters.

Constrain the object (or any of its attributes) to another object or attribute; see page 152.

Define and attach dynamic transformations to the object or to its attributes; see page 155.

For gradient fill, cast shadows, arrowheads and fill dynamics, attach Rendering to the selected object; see page 182.

Attach Box Attributes to the selected text object; see page 182.

Attach Custom Properties , Aliases and History objects to the selected object; see page 184, page 185 and page 183.

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

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 the <Return> key or press the 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:

Select the object.

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:

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 Marked Object option of the Edit menu described on page 206 may be used to reuse these objects.

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. Attribute objects may also have transformations attached, in which case they are annotated with an " X " on the right side of the Properties dialog.

For attributes that are objects, an ellipsis button lets you open a separate attribute object dialog for editing the attribute value and other attribute properties.

Attribute Object 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:

Text boxes for entering attribute name and value.

Text fields showing an attribute's data type (D, S or G) and transformed value.

A way to change the attribute value via a palette, a menu with list of possible values or a spinner.

Toggles for setting the attribute's HasResources and Global attributes.

A button for adding or editing a tag and a text field showing tag information.

Buttons for reusing attributes of other objects in the drawing.

A button for marking the attribute for reuse; see page 171.

Buttons for constraining the attribute; see page 153.

Buttons for adding, editing, or deleting transformations for the attribute; see page 157.

If an attribute object has a transformation attached, it is annotated with an " X " on the right side of the Properties dialog.

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 160. For a complete list of the objects' attributes and their default attribute names, see Appendix C: GLG Object's Attribute Table on page 301 of the GLG Programming Reference Manual.

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.

In Drawing positions the point where you click in the drawing area.

Use Position gives the point the same coordinate values as another control point that you click on.

Use Value positions the point using a named resource or a marked point. The value must be another geometric value; see page 171.

Constrain replaces the point's existing constraints with a constraint to the point you click on; see page 152.

Merge combines the point's existing constraints with the constraints of another point you click on; see page 152.

Unconstrain removes all constraints from a point.

Mark records the coordinate value of the point on a "clipboard." You can mark up to five values; see page 171.

Print Info lists basic information about the point (in Unix/Linux versions of the Toolkit only).

Add Dynamics , Edit Dynamics , and Delete Dynamics manipulate transformations of the control point; see page 157.

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.

Defining Transformations

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). SeeGLG Objects for descriptions of the different transformation objects.

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

Transform points makes an immediate and permanent change to the definition of the object, without creating a transformation object.

A static (or matrix) transformation changes the appearance of the object immediately. A static transformation doesn't change the object definition, however. The transformation cannot be edited.

A dynamic (or parametrical) transformation has a resource that you can animate. The transformation occurs at runtime, when you provide input data to the transformation; see page 167. Dynamic transformations may be edited.

A transformation can be attached to an entire object, to an attribute of an object, to a control point, or to the entire drawing. Defining a static or dynamic transformation adds a transformation object to the object hierarchy, below the object you attach it to.

Transforming an Object

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

To make a permanent change to its definition, transform its points.

To make a one-time, reversible change to its geometry, add a static transformation.

To make its geometry change temporarily, or to animate it, add a dynamic transformation.

Transforming Object's Points

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

Select the object and use Object , Transform Points . Alternatively, open the Selected Object Properties dialog for the object, and click on the Add Dynamics button, or click on the Transform Object Points toolbar icon. The Transform Points dialog appears.

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.

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.

Click on the Apply button to change the definition of the object by applying the transformation to the object.

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:

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.

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.

Click on the Apply button to change the definition of the object by applying the transformation to the object.

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 .

Defining a static or dynamic transformation adds it to the transformation list, so you can edit 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 172.

The MoveByXform Flag

The MoveByXform flag is used to protect the 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 MoveByXform flag is set, moving or otherwise transforming the object 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.

For example, an object rotating around its center with MoveByXform set to YES will still rotate around its center after being moved. Without MoveByXform set, the center of rotation wouldn't move and the object would rotate around the old position of the center even after the object has moved.

The MoveByXform flag is in the Selected Object Properties dialog. When you turn it on, moving the object with the mouse attaches a static transformation to the object, instead of changing the coordinates of the object's control points.

Transforming an Attribute

The data type of an attribute controls the type of transformation you can apply to it. For geometric values, the dialogs are similar to those for transforming objects. For attribute objects with scalar or string values, there is no separate dialog for specifying the transformation.

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

Select the graphical object that has the attribute you want to transform.

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.

Click on the for an attribute, to see the Attribute Object dialog.

Click on the Add Dynamics button in the Attribute Object dialog. A list of transformation types appears. The content of the transformation list depends on the data type of the attribute. See GLG Objects for specifications of the transformations.

Click on the transformation name to add the new transformation to the list of transformations for the attribute.

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

To transform a control point, use Shift+click to see the Control Point dialog. Then use Steps 4 - 5 in the above procedure.

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 the dynamic transformations.

To edit transformations:

First, display the transformation list:

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.

For an attribute, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object dialog. Finally, click on the Edit Dynamics button.

For a control point, use Shift+click to see the Control Point dialog, and click on the Edit Dynamics button.

In the Transformation List dialog, click on a dynamic (parametrical) transformation. Its attributes appear on the right side of the dialog.

The transformations are listed in the order you created them. If you use the object's coordinate system (see page 175) when you create the transformation, it appears at the bottom of the list. Otherwise, it appears at the top of the list. 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 Delete button may be used to remove selected transformations.

If you define 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 first transformation in the list (or the last transformation if the coordinate system is set to the Object Coordinate System , see page 175). The Builder does not confirm the deletion of a transformation.

The Delete button of the Transformation List dialog may be used to delete a transformation from any position in the list.

To remove the first transformation:

For an object, select it and use the Object , Delete Dynamics menu option or click on the Delete Dynamics toolbar icon.

For an attribute, select the object, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object dialog. Finally, click on the Delete Dynamics button.

For a control point, use Shift+click to see the Control Point dialog, and click on the Delete Dynamics button.

To remove a selected transformation from a list of transformations:

Display a list of transformations as described in Editing Transformations.

Select the transformation in the list to delete.

Click on the Delete button at the bottom of the Transformation List dialog.

If you defined 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 More 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 Screen 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 the resource hierarchy for the whole drawing, use Object , All Resources ; see page 234. To see a branch of the resource hierarchy that starts with the selected object, use Object , Object Resources ; see page 234.

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

In the Builder, the following entries are also displayed:

/ represents the top level (the whole drawing area).

. represents the selected object.

~ represents the viewport with the current editing focus (as a result of the Set Focus button).

.. represents the parent of the current level of the hierarchy.

These entries let you select a subset of the drawings for browsing resources. These entries are available only in the Resource Browser and not in the API.

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.

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:

Name the object if you plan to animate it. Animation requires access to a named resource.

Name the object if it corresponds to a graphical object in the drawing that you want to access programmatically later on. This is not required, but it lets you use the resource hierarchy to locate any graphical object in the drawing, regardless of its visibility or location in the hierarchy.

Name the object if you plan to edit its attributes frequently. This is not required, but it lets you use the resource hierarchy to locate and select the object's attributes.

Name control points, if selecting them with the mouse would be difficult, or if you'll need to access the point programmatically later on. This is not required, but can simplify editing closely positioned points.

It is not usually necessary to name transformations, though you should name the attribute of the transformation that you plan to animate.

Do not assign the same name to different objects, and use care when cloning or copying objects, renaming the copies. Naming conflicts, where more than one object at the same level have the same name, can have unpredictable effects.

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:

Select the object.

Use Object , Properties or use the Properties button to see the attributes of the object.

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 Object 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:

Use Object , All Resources or click on the All Resources button to see the resource hierarchy.

Locate the resource you want to delete, and click on it to select it.

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

A tag is an attribute that is accessible by its tag name. Unlike resources, which are hierarchical, the tags are global and have a flat hierarchy, with all named 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 defined for the selected object, or the tags of the whole viewport that has editing focus if no object is selected.

A tag may be added to any attribute or resource object by clicking on the Add Tag button in the Attribute Object 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 Tag Object dialog. The values of the tag's TagName and TagSource attributes are displayed in the Tag field of the Attribute Object dialog as two fields separated by the `=' character. To edit the tag, click on the Edit Tag button of the 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 Tag Object dialog for editing the tag's attributes and the Resource Object dialog for editing the attribute object the tag is attached to.

The tag browser provides a Unique Tag Source toggles which can be used to control the display of tags with identical tag sources. By default, the toggle is unchecked and all instances of tags with the same tag source will be displayed in the tag browser. If the toggle is checked, only the first instances of tags with the same tag sources will be displayed. Editing the value of this single entry in the Builder will not affect the other entries, but all tags with the same tag source will change when the tag value is set with the SetTag functions at run-time by specifying the shared tag source.

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 Sort by button.

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

Adding and Deleting Tags

Adding a Tag

To tag an object's attribute:

Select an object.

Use Object , Properties or use the Properties button to see the attributes of the object.

Select an object's attributes by clicking on the attribute's ellipsis button .

Click on the Add Tag button.

Enter values for the tag's attributes in the Tag Object dialog.

To tag a resource:

Use Object , All Resources or click on the All Resources button to see the resource hierarchy.

Locate the attribute resource you want to tag, and click on it to select it.

Click on the Add Tag button.

Enter values for the tag's attributes in the Tag Object dialog.

Editing a Tag

To edit a tag attached to an attribute, bring the Attribute Object dialog for the attribute and click on the Edit Tag button to activate the Tag dialog.

The 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 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:

Use Object , Tags or click on the Tags button to see a list of tags.

Locate the tag you want to delete and click on it to select it.

Click on the Delete Tag button in the Tag Object dialog.

Alternatively, display the Attribute Object dialog for the attribute or resource the tag is attached to, click on the Edit Tag button to display the Tag dialog and click on the Delete button.

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:

Saving objects to a drawing file, and loading an object from a drawing file into the current drawing.

Cutting and pasting the object via the clipboard.

Cloning the object, which copies it and applies an offset or a transformation.

Saving objects to a drawing file and using them as sub-drawings with reference objects (refer to Reference of Advanced Graphical Objects for more details).

Using an objects as a template of a reference object for replicating instances of it in the drawing (refer to Reference of Advanced Graphical Objects for more details).

Saving objects to a drawing file and adding them to the Custom Object palette.

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

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

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:

A full clone is just a copy of the object, with no constraints. This is the default for copy and paste operations.

A constrained clone is a copy of the object, with all attributes and control points of the copy constrained to the corresponding attributes or control points of the original object.

A strong or weak clone is a constrained copy of the object. The Global attribute determines what attributes of the clone are constrained.

Each attribute or control point has a Global attribute, which appears in the Object Attribute dialog for the attribute. 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:

Global constrains the clones to the original for both a strong and a weak clone.

SemiGlb constrains the clones to the original in a strong clone, but not in a weak clone.

Local does not constrain the clones to the original for either a strong or weak clone. This is the default.

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 Palettes of GLG Graphics Builder Menus for more details and options.

Marking and Replicating Transformations and Other Objects

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

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:

Select the object with the value you want to mark.

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.

Click on the to see the Attribute Object dialog.

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.

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:

Show the list of attributes for the object:

For an attribute, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object dialog.

For a control point, use Shift+click to see the Control Point dialog.

Click on either the Constrain One , Constrain All or the Use Value 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.

Click on Use Marked . The Builder prompts you with a list of marks, ranging from Mark0 to Mark4 .

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:

Show the list of attributes for the object:

For an attribute, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object dialog.

For a control point, use Shift+click to see the Control Point dialog.

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:

Select the object to which the transformation is currently attached.

Show the list of transformations for the object:

For a graphical object, use Object , Edit Dynamics or click on the Xform button in the Status Panel to see a list of transformations.

For an attribute, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object 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.

For a control point, use Shift+click to see the Control Point dialog, and click on the Edit Dynamics button.

In the Transformation List dialog, use the Mark Object button to mark a single transformation, or use Mark List to mark them all.

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

To reuse marked transformations:

Select the object to which you want to attach the marked transformation(s):

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

For an attribute, use Object , Properties to show the Selected Object Properties dialog, and click on the to see the Attribute Object 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.

For a control point, use Shift+click to see the Control Point dialog, and click on the Add Dynamics button.

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.

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

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:

To keep a set of otherwise unrelated objects together. The members of a group are spatially associated, and move together.

To let you act on a set of objects collectively. The action you perform is applied to every member of the group.

To apply animation to a set of objects.

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:

Open the group using Traverse , Hierarchy Down . By navigating to the appropriate level of the hierarchy, you can edit the individual members of the group. Use Traverse , Up when you have finished.

Release or add members to the group using Arrange , Remove Object from Group and Arrange , Add Object to Group ; see page 214.

Destroy the group and replace it with its members by using the Arrange , Explode submenu; see page 216.

Edit attributes that are common to the group members using Traverse , Edit All or the button on the group's Properties dialog. The changes you make are applied to every member of the group; see page 213.

Enter group editing mode using Traverse , Select Next or the button on the group's Properties dialog. You can edit the group member you select, without having to traverse the hierarchy; see page 211.

For nested groups, move directly to the lowest level of grouping using Traverse , Select Bottom or the button on the group's Properties dialog; see page 212.

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 217. 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:

Select an object to use as a template.

Select Object , Properties to name the object, and to set the attributes of the template object so that its instances will inherit appropriate characteristics.

Select Object , Create , Series to create the instance objects.

Click on two points to specify a path on which to arrange the series instances.

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.

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:

Select an object to use as a template.

Select Object , Properties to name the object, and to set its attributes so that its instances will inherit appropriate characteristics.

Select Object , Create , Square Series to create the instance objects.

Click on the origin for the square series, and click on two points to specify two vectors from the first point; they control the arrangement of the series instances.

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 Reference Object

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 to implement subdrawing or object dynamics, changing the displayed object based on some condition. There are several types of reference objects:

Container Reference

The Container Reference is used to encapsulate a set of objects, protect them from 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.

Object Reference

The Object Reference is used to replicate instances of a template in the drawing. Copying or cloning the Object Reference creates a new instance that uses the same template. Editing the template modifies all the instances of the Object Reference in the drawing.

To create instances of the template, first create an Object Reference: select an object to use as a template, click on the Reference icon in the Object Palette and click in the drawing to position the reference. 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 Reference (SubDrawing)

The File Reference is used to replicate instances of another drawing. Editing the referenced file changes all instances of it in other drawings. To create instances of a drawing, click on the SubDrawing icon in the Object Palette , click in the drawing to position the reference and define the drawing file to be used. 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 .

and press OK without entering anything into the ObjectPath dialog.

Palette Reference

The Palette Reference uses some object in the drawing (palette) as a template. To create palette reference, select Object, Create, Reference, Palette Reference and click in the drawing to define the reference object'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 reference object's properties and enter palette object's resource path in the SourcePath attribute.

To edit the template of a reference, use Traverse , Hierarchy Down . For File Reference objects, traversing down loads the referenced drawing, and traversing back up saves it. For Palette References , traversing down performs Hierarchy Down into the palette object. To delete the reference, use Arrange , Explode , Object ; see page 217.

To adjust the position of a reference's graphics relative to the reference's control point, you can move its 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 reference's control point relative to its graphics, without traversing down to edit the template.

All types of references may either be scalable or have fixed size, as controlled by the reference's FixedSize attribute.

All types of reference objects may be used as nodes connected with connector objects constrained to their control point.

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

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 , All 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 , All 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 point frame allows anchoring to a single point.

A line frame allows anchoring to points along a line.

A 2D frame allows anchoring to points inside a parallelogram.

A 3D frame allows anchoring to points inside a parallel prism.

A free frame consists of arbitrarily placed 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 or the Toggle Frame Points toolbar icon to toggle between the control points and the frame points; see page 247. 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 or the Toggle Frame Points toolbar icon 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:

Select the object to which you want to add rendering attributes.

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.

Change rendering attributes to define gradient fill, cast shadow, arrowheads and fill dynamics parameters.

To delete rendering attributes, click on the Delete Rendering button in the Rendering Properties dialog.

To add text box attributes to a text object:

Select the text object to which you want to add the box to.

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.

Change the box attributes to define the text box's appearance.

To delete box attributes, click on the Delete Box Attributes button in the Box Attributes' Property 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:

Select the object to which you want to add a history object.

Select Object , Add History . The Builder prompts you for the resource name.

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.

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 Set as Parent Viewport's GISObject option of the Arrange menu. 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 103 and Integrated GIS Object, GIS Rendering and GIS Editing Mode on page 104 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:

Select an object to which you want to attach the custom data properties to.

Select Object , Add Custom Property and select a D , S or G property type.

The Builder adds a custom property, displays a Custom Properties List and a dialog for editing the property. Enter the property name and value. The property name will be used for accessing the property.

Add more properties using the above steps. When finished, use the Resource Browser to browse them as resources.

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:

Select the object whose resources you want to reference using the alias. The resource path will be defined relative to this object. The HasResources flag of the object must be set to YES to enable access to its named resources.

Select Object , Add Alias . The Builder adds an alias, displays the Alias List and the attributes of the added alias.

Enter the logical name into the Alias attribute field.

Enter the resource path you want to assign to the alias into the Path attribute. To define the path using the Resource Browser , select the ellipsis button for the Path attribute, select the resource and press Select .

Repeat the above steps to add more aliases. When finished, use the Resource Browser to check the aliases.

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

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.

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.

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.

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.

Select Traverse, Up . Open the resource browser with Object, All Resources , or with the All Resources button on the toolbar, and note that both the $Widget name and the handle name are on the same level of the resource hierarchy.

Close the resource browser, select the viewport, bring up the Selected Object Properties dialog, and set the viewport's HasResources flag to YES.

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.

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.

Select Run, Start and at the run prompt, issue the command:
$datagen -sin d 0 10 $Widget/handle/LineWidth

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.

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

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.

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.

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.

If it is still going, stop the animation with Run, Stop . Select the viewport, select Traverse , Hierarchy Down , and select the handle polygon.

Open the Selected Object Properties dialog, and press the AddXform button in it. This opens the transformation dialog.

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.

Press Center In Drawing and notice a prompt at the bottom of the screen. Select a point around which the polygon will rotate. A cross appears at that spot.

Set the Variable Name field to read "rotate_factor," and press the Apply button at the bottom of the dialog.

Back in the Selected Object Properties dialog, press the EditXform button. The attributes of the rotation transformation are displayed in another 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.

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.

Select Run, Start and at the run prompt issue the command:
$datagen -sin d 0 1 $Widget/handle/rotate_factor

Stop the animation, select the viewport, Traverse , Hierarchy Down , select the polygon, bring up the Selected Object Properties dialog, and press EditXform .

Set Factor to 1. Press the button next to the Angle attribute, and give it the name, "rotate_angle."

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.

Stop the animation, select the viewport, Traverse , Hierarchy Down , and draw another polygon to represent the base of a valve.

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.

Set the valve1 group's MoveByXform flag to YES. This is not important yet, but we will move this object soon, and the setting of the flag will be significant then. You move an object by clicking on its move point with the mouse, and dragging the object into its new position. Unfortunately, while you may move the valve group into a new position, you do not move the center point defined for the rotation transformation. This means that if its MoveByXform flag is set to NO, after an object is moved, it will still rotate around the original point. If MoveByXform is set to YES, the move is applied to the object as a transformation after the rotation transformation is applied. This makes the center point appear to move with the object.

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.

Use the Selected Object Properties dialog to rename the new group "valve2."

Animate the valve (use Run, Start ) with the command:
$datagen -sin d 0 90
$Widget/valve1/handle/rotate_angle

Stop the animation and try it again with:
$datagen -sin d 0 90
$Widget/valve2/handle/rotate_angle

Try it again with:
$datagen
-sin d 0 90 $Widget/valve1/handle/rotate_angle
-sin d 0 90 $Widget/valve2/handle/rotate_angle

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

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.

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 EditXform button.

Press the [...] button next to the Angle attribute, and press the Constrain button on the left side of the attribute object dialog.

Press the Use Resource button in the attribute object dialog, then use the resource browser to select the resource: $Widget/valve1/handle/rotate_angle .

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.

Using the GLG Graphics Builder