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 127
Start the Builder, and identify its features	page 128
Create a drawing and add objects to it	page 127
Edit an object, including changing its geometry and setting its attributes	page 134
Create constraints between object attributes	page 139
Apply transformations to objects and to attributes	page 142
Define objects as resources, and arrange them in a hierarchy	page 146
Animate a drawing	page 153
Work with advanced objects	page 161
Creating and animating objects: a tutorial example	page 170

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

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

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

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

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 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 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 pan , zoom , and rotate controls let you control your view of the drawing area.

The status area shows information about the selected object, messages, and prompts for action.

Stopping the GLG Graphics Builder

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

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

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

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

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

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

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

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 area 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 162 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 flip the object in any direction, move one of the box points to another side of the object.

To rotate the object, move its rotate point.

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

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

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

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

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

Attach Custom Properties , Aliases and History objects to the selected object; see page 169, page 169 and page 168.

To change the object's behavior dynamically, you can animate it; see page 153.

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.

For attributes that are objects, an ellipsis button lets you open a separate dialog for editing the attribute value. The contents of these 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 tag name.

A way to change the attribute value, such as an entry box, a palette, a list of possible values, or a selectable graphic.

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

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

Buttons for constraining the attribute; see page 140.

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

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

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

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

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

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

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

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.

Creating Constraints

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

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

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

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

Constraining Similar Attributes

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

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

Select the object that has the attribute you want to constrain.

Use Object , Properties or click on the Properties button to show the Selected Object Properties dialog. This dialog shows a list of attributes, with a for attributes that can be edited in a dialog.

Click on the to see the Attribute Object dialog.

Click on the ConstrainOne button in the Attribute Object dialog. To keep existing constraints, use the ConstrainAll button instead.

The Builder prompts you for the object to constrain to. To do so, click with the mouse on an object in the drawing.

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

Merging Constraints

If you use the ConstrainOne button, any existing constraints are replaced by the one you create. However, you can add another constraint without removing the existing constraints; use the ConstrainAll button instead of the ConstrainOne button.

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

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

However, if you select C and use the ConstrainAll button instead of the ConstrainOne button, the constraint between C and D is preserved.

Constraining Different Attributes

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

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

To constrain two different attributes:

Open the Selected Object Properties dialog for the object.

Open the Attribute Object dialog for the attribute that you want to reuse.

Click on the Mark button, and select a mark number to assign to the attribute value. The attribute value is now marked.

Open the other object's Selected Object Properties dialog.

Open the Attribute Object dialog.

Click on either the ConstrainAll button or the ConstrainOne button in the Attribute Object dialog. The Builder prompts you to select either a resource or a marked value.

Click on Use Marked and select the mark number you assigned earlier (if only one mark was assigned, it'll be used automatically). To use a named resource instead of a marked value, click on Use Resource and select the resource from the Resource Browser dialog.

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

Constraining Control Points

Control points are constrained just like other attributes. Use Shift+click to see the attributes for the control point, and then use either the ConstrainAll or the ConstrainOne button.

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

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.

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

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

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

Using View and Screen Transformations of the Viewport (advanced)

A Viewport uses two types of transformations: the "outside" transformation is used to position the viewport itself, and the "inside" one is used to draw the objects inside the viewport. When the viewport is selected, the Add Dynamics button of the Properties dialog attaches an outside transformation. If the editing focus is inside the viewport with no objects selected, the Add Dynamics button adds a transformation as the inside transformation which may be used to zoom, pan or rotate all objects in a viewport without creating a group to hold them. After the 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 can't 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 215. To see a branch of the resource hierarchy that starts with the selected object, use Object , Object Resources ; see page 215.

The Resource Selection dialog shows the resources organized like a file and directory structure, with levels of hierarchy corresponding to the HasResources=YES settings. You can navigate between the layers by double-clicking on the entries with the >> symbol at the end.

>> following a resource name means that it either has its HasResources flag set to YES or the resource is a geometrical object (i.e. polygon, arc, etc.) with a set of default attributes. In either case, double clicking on such a resource opens another level of hierarchy, showing the resources of the selected object.
Entries with no >> symbol are usually named attributes. Clicking on such entries selects them, showing the Resource Object dialog for editing that attribute object.

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.

This notation lets you specify a "path" to a resource, just as you would specify a path to a file. These entries are available only in the Builder 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 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 Selection 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 Selection dialog shows Group as having child objects.

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 names, 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 tag names provide mapping between resources of the drawing and fields of a process database. A tag name 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 name and new tag value to one of the SetTag functions. If multiple attributes share the same tag name, 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. Giving a tag name to an object's attribute makes it a tag and adds it to the list of tags in a tag browser.

The Tag Selection dialog shows the list of tags. Clicking on tag entries selects them, showing the Resource Object dialog for editing the tagged attribute object.

The resource browser provides a Unique Tag Names toggles which can be used to control the display of tags with identical names. By default, the toggle is unchecked and all instances of tags with the same name will be displayed in the tag browser. If the toggle is checked, only the first instance of a tag with this name 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 name will change when the tag value is set with the SetTag functions at run-time.

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

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 .

Type a tag name for the attribute in the Tag box.

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.

Type a tag name for the attribute in the Tag box.

Deleting a Tag

To delete a tag, simply unname it. To remove the name from a tagged 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.

Delete the characters from the Tag box of the Resource Dialog. If there was only a single tag with this tag name, the tag will no longer appear in the tag list. If there several tags with the same name, repeat steps 2 and 3 until no tags with this name appears in the tag list.

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.

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

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

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.

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 to see the 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.

Controlling the View

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

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

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

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

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

Changing the View Projection

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

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

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

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

Customizing the View Projection

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

To transform a viewport dynamically from a program, add a parametrical transformation to the viewport as a view transformation.

Viewing Using Different Coordinate Systems

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

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

Changing the Viewing Area

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

To use a different point as the center of the Builder window, use the View , Pan To option. Alternatively, you can use scrollbars or click on a point in the panning selector.

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

Using the GLG Graphics Builder