GargoyleDoc.tioga
Last edited by Bier on August 14, 1986 0:34:41 am PDT
Pier, August 28, 1986 3:51:45 pm PDT
The Gargoyle Reference Manual
Eric Allan Bier and Ken Pier
Introduction
This manual (GargoyleDoc.tioga) provides a description of the features which have been implemented in Gargoyle thus far, as seen by the user. A tutorial introduction is also available (GargoyleTutorial.tioga); this document is a reference manual rather than a tutorial. The Gargoyle implementors recommend that you execute the tutorial and read this manual before cutting loose with Gargoyle.
To startup Gargoyle:
bringover -p [Cedar]<CedarChest6.1>Top>Gargoyle.df
Gargoyle
A single Gargoyle viewer should appear, iconic.
The remainder of this document describes terms used in Gargoyle, the Gargoyle features which are available via the mouse, the features provided by the menus in the order in which the menu buttons appear, and the features provided via keyboard input.
Terms
Control Panel. The set of buttons and menus at the top of the Gargoyle viewer.
Scene. The set of graphical objects currently in the Gargoyle viewer. The scene includes the graphical objects created by the user and alignment lines created by Gargoyle for the user.
Segment. A single straight line segment, circular arc, piece of a conic, cubic Bezier curve, or interpolating spline. A segment has two endpoints called joints.
Joint. An endpoint of a segment. Every segment has two joints. Joints are drawn in Gargoyle as small squares which are normally invisible, become solid white squares with a dot in the center as needed for attracting the caret or when a related object is selected, and become solid black squares when they are selected.
Control point. Curved segments have additional points associated with them, called control points, which define their shape. Control points are drawn in Gargoyle as small solid squares which are normally invisible, become solid white squares as needed for attracting the caret or when a related object is selected, and become solid black squares when they are selected.
Trajectory. A connected sequence of line segments and/or curve segments.
Outline. A set of trajectories considered as a group for some purposes. Most outlines contain a single trajectory, but a closed trajectory with holes in it is represented by a single outline composed of several trajectories.
Holes. An outline may consist of a single closed trajectory, called a fence, and a number of subsidiary closed outlines called holes. The fence and its holes are rendered using wrap numbers; the graphical effect is that of a window or hole through the opaque fence through which scene objects behind the fence appear. See Holes in the Hierarchy menu below.
Fence. See Holes.
Slice. A graphical object which is not a part of the segment/trajectory/outline hierarchy. Slices currently do not participate in groups of graphical objects. Slices usually have special behavior defined via a classing mechanism supported in the implementation of Gargoyle. Text strings, boxes, circles, and pieces of Interpress files are currently implemented as slices.
Top level object. A set of outlines or slices considered as a group for some purposes.
Caret. The upside-down V shaped object which appears during most interactive operations. The caret is used as the first endpoint of new segments, the insertion point for new text strings, the center of new circles, -- in general, the start point of new graphical objects. It also acts as a kind of tugboat, pulling selected objects toward some object to which it is attracted by gravity. The anchor is always created at the caret position.
Anchor. The center of rotation and the center of scaling. Currently appears as four arrows pointing away from a circle. The anchor is gravity-active and hot.
Hot Objects. A joint or segment is hot if it triggers alignment lines. Hot joints can trigger slope lines, and compass circles. Hot segments can trigger angle lines and parallel "distance" lines. The anchor acts as a hot joint. Segments and joints are made hot or cold by explicit user actions and by heuristics based on the operation being performed. Hot joints are drawn in Gargoyle as white squares larger than the squares used to show control points.
Alignment line. A greyed straight line or circle for use during an operation which requires precision, such as dragging, rotating, scaling, and rubberbanding. Which lines appear depends on the objects in the scene which generate the lines (explicitly hot objects and objects chosen by heuristics based on the operation being performed), and which types of alignment objects the user has activated on the control panel. Alignment lines are gravity active.
Gravity. The mapping from cursor position to caret position. This mapping often lands the caret onto a trajectory in the scene or an alignment line; the caret is "snapped" to a gravity active object when the cursor moves to within the gravity extent of that object. Two types of gravity are available, called Prefer Points gravity and Strict Distance gravity. The user interactively chooses the desired type. The user may also turn gravity off completely.
Gravity Active. An object is gravity active if the caret will "snap" to that object during a caret positioning operation or an operation using caret motion such as dragging, rotating, scaling, and rubberbanding. All objects in a scene which are not themselves in motion will be gravity active.
Gravity Extent. The farthest the cursor can be from a gravity sensitive object and still map the caret onto that object. The user interactively sets the gravity extent.
NYI. Not yet implemented.
Interactive Features
A summary of the Gargoyle mouse actions can viewed at any time by clicking the Help! button on the control panel; a Tioga viewer will open up summarizing the Gargoyle commands.. Grow the help viewer for a more complete summary of Gargoyle commands. User actions can be aborted by typing DEL before releasing mouse buttons or SHIFT/CONTROL keys, just like in Tioga. In the following, Ctrl indicates holding down the CTRL key, Shift indicates holding down either SHIFT key. User actions are:
Select Joint. Hold down the left mouse button and move around. If gravity snaps the cursor onto a joint or control point, the joint or control point will temporarily be highlighted (appear as a filled black square). If a point is highlighted, its related joints and control points will also appear, unhighlighted. Releasing at this point will cause all previously selected objects to be deselected and that joint or control point to become selected. This operation is called selecting at the joint level.
Select Segment. Hold down the middle mouse button and move around. If gravity snaps the cursor onto a segment, its end joints will temporarily be highlighted (appear as a filled black square) and the segment will be highlighted using a black stroke twice the width of the actual segment stroke width.. If the segment is a curve its control points will appear. Releasing at this point will cause all previously selected objects to be deselected and that segment to become selected. The segment, joints, and control points will remain highlighted as selection feedback. This operation is called selecting at the segment level.
Select Trajectory. Double click the middle mouse button, holding down on the second stroke. Then move around as in Select Joint. If gravity snaps the cursor onto a trajectory, all of its joints and segments become hightlighted. Releasing at this point will cause all previously selected objects to be deselected and that trajectory to become selected. This operation is called selecting at the trajectory level.
Select TopLevel. Double click the left mouse button, holding down on the second stroke. Then move around as in Select Joint. If gravity snaps the cursor onto a top level object, all of its trajectories, joints and segments become hightlighted. Releasing at this point will cause all previously selected objects to be deselected and that top level object to become selected. Outlines and slices are selectable at the top level. Top level selection may be extended to any number of top level objects. This operation is called selecting at the top level.
Extend Selection. Hold down the right mouse button and move around. If gravity snaps the cursor onto an object of the same level as the initial selection level, releasing at this point will ADD the object to the current selection. Extend selection operations are often repeated to build a temporary collection of objects for operands to an interactive operation. Note that extending at the segment level within a single trajectory will make a new selection of all segments in that trajectory between the original selected segment and the extended segment. Since trajectories are ordered, extend segment selection may wrap around from the end to the beginning of a trajectory.
META Extend Selection. Hold down the SWAT key and initiate a selection operation (Select Joint/Segment/Trajectory/TopLevel). Continue just as before with selection feedback. When you release the mouse button and the SWAT key, the selected object will be ADDED to the existing selection rather than replacing the existing selection. It is thus possible to (meta)select heterogeneous objects, say a mixture of joints, segments, and trajectories, for a subsequent operation like Drag or Delete.
Select with Box. Double click the right mouse button, holding down on the second stroke. A box will appear which may be rubberbanded exactly as in the Add Box command (below). When the button is released, the box will disappear and all objects whose bounding box lies within the box will become the current selection.
Deselect Joint/Segment/Trajectory/TopLevel. Hold down CTRL and SHIFT to convert selection operations into deselection operations. Use the same mouse buttons as in the corresponding selection operations.
ExtendDeelection. NYI.
Caret Position. ShiftLeftMouse initiates caret positioning. The caret will interactively follow the cursor and use gravity to snap onto gravity active points and lines as long as the mouse is held down and moved.
Add Line. Create a new straight line segment whose endpoints are the caret and the current cursor position. ShiftMiddleMouse initiates AddLine. Holding down the mouse button causes new alignment lines of the activated types to appear (if the Heuristics option is on) and the caret to jump to the cursor so the new endpoint can be placed with precision.
Add Box. Create a new box object whose corners are the caret and the current cursor position. ShiftRightMouse initiates AddBox. Holding down the mouse button and moving the mouse causes alignment lines to appear (if the Heuristics option is on) and the caret to jump to the cursor corner of the box, so the new corner can be placed with precision. Boxes may be translated/rotated/scaled as usual and will retain their box characteristics. Boxes are displayed with control points at their corners. Dragging a corner or an edge of a box will grow/shrink the box rectilinearly. Transforming a box selected as a trajectory or top level object will transform the entire box.
Drag. CtrlLeftMouse initiates dragging. All selected objects are translated, maintaining a constant relationship to the caret. Dragging is usually performed in stages. First, select the objects to be dragged (if parts of trajectories are selected, then those trajectories will be rubberbanded). Second, place the caret on that joint or segment which must be positioned with precision if the selection operation has not already positioned the caret for you. Next, position the cursor as desired. As the mouse button is pushed down, the caret will snap to the cursor. Finally, continue to hold down the CTRL key and the mouse button and move the mouse. The caret will be attracted to gravity-sensitive objects as usual, taking all of the selected objects with it.
Rotate. CtrlMiddleMouse initiates rotation. Very much like Drag. Rotate requires one extra preliminary step -- the anchor must be placed to be used as a center of rotation. This can be done using the DropAnchor command in the HotSpots menu, or from the keyboard (CtrlA drops the anchor at the caret. CtrlShiftA deletes the anchor). Select the objects to be rotated (if parts of trajectories are selected, then those trajectories will be rubberbanded). Because the objects move with 1 degree of freedom while the mouse has two, the caret does not remain in a constant relationship with the objects being rotated. However, the caret does snap to the cursor when the operation begins so objects can be rotated with precision. The angle of rotation is the angle between two vectors: the Anchor to initial-caret-position vector, and the Anchor to current-caret-position vector.
Scale. CtrlRightMouse initiates scaling. Very much like rotate. The Anchor is the center of scaling. The scaling factor is the ratio of <the current caret to Anchor distance> to <the initial caret to Anchor distance>.
Skew. CtrlDoubleRightMouse initiates an interactive skewing transformation. Skew is similar to Drag. The (imaginary) horizontal line through the Anchor is invariant to the skew. The scene point at which the caret was placed before the operation is translated to stay with the caret, skewing everything else as necessary. This operation is experimental and will probably be bound to a different mouse button in the near future.
Copy And Drag. CopyAndDrag is initiated by CtrlDoubleLeftClick. Hold down the CTRL key and double click. A copy of the selection is created and then selected. It may be immediately dragged by moving the mouse without releasing the button. The copy will first appear translated from the original by the vector defined by the caret and cursor when Copy And Drag is initiated.
Scroll, Zoom, Fit, and Prev. The BiScrollers package provides horizontal and vertical scrolling for Gargoyle scenes and also provides some temporary view operations via the first button line of the control panel. These operations (Scale, Rotate, Fit, Reset, Edge, Prev) should not be confused with the permanent operations applied to Gargoyle scene objects using Gargoyle operations. BiScrollers transformations and how to use them to help view a scene are described in BiScrollersDoc. These buttons are PopUpButtons; holding the mouse button down over one of them for about one second will cause a pop-up menu to appear. See PopUpButtonsDoc for more information. There are two additional buttons, CenterSel and FitSel, on this line. CenterSel will cause the bounding box of the currently selected Gargoyle objects to be centered in the viewer. If there is no selection, the caret position will be centered in the viewer. FitSel will cause a BiScrollers Fit operation so that the bounding box of the currently selected Gargoyle objects is scaled and translated to fit in the viewer. The Prev button is like the Tioga PrevPlace button; it returns the viewport to where it was at the last BiScrollers operation with the exception of Scroll, Scale, and Rotate. In other words, scrolling, scaling, and rotating do not change the previous place; other BiScroller operations remember their current place before transforming the viewport. Invoking the Prev button causes the previous place and the current place to swap.
WARNING: Scaling and rotating by uneven values (i.e. non-integer values) will cause Gargoyle refresh to slow to a crawl.
Interactive feedback is provided in the scene and in the feedback line. When doing a caret positioning operation or a selection operation or a drag, objects will highlight their joints and control points as the cursor is attracted to them, unless they are themselves in motion. If an object has a part of it selected or made hot, it will continually highlight its joints and control points. During interactive selection/deselection operations, highlighting will reflect the selection/deselection that will occur when the mouse button is released. This flicking on and off of joints and control points is required in order to keep a scene from becoming completely cluttered with joint and control point feedback.
Whenever the caret is moving around, the feedback line will be continually updated with a description of the object that the caret is on or attracted to.
Menu Features
Control Panel Overview
[Artwork node; type 'ArtworkInterpress on' to command tool]
The Gargoyle control panel uses a variety of buttons and menus for state display and manipulation. Familiar "menu style" buttons are displayed in the usual Cedar Viewer menu style. Menu items Clear, Reset, Get, Merge, Store, Save, Stuff, Refresh!, Revive!, Help! work like standard menus.
Pop-up menu names appear in bold face in the control panel. The pop-up menus will appear near their name when clicked with the left mouse button. To select a pop-up menu action, move the cursor over the menu item and click with any mouse button. To abort a pop-up menu, click anywhere outside the menu. Menus Interpress, Script, Hierarchy, Transform, Overlap, Shapes, Debug, LineWidth, Fill, Select, Curve, Text, HotSpots, Units are pop-up menus.
Fine Print: Selecting a pop-up menu name with right click will cause the menu to stick until it is aborted. Repeated selections within the menu may be invoked. The operations will not affect the scene until the menu is aborted. This is useful for invoking a series of similar operations, such as Overlap or Shapes operations.
Menu items which represent binary modes are displayed as buttons with borders. The mode is on or enabled when the button is video reversed with white text on black background. Menus ShowColors, Gravity, Alignments, Midpoints, Heuristics are binary state menus.
Multiple choice menus consist of a button and a read-only field which contains the current mode of choice. ScreenStyle: and GravType: are the two current multiple choice menus, although GravType has only two choices. It is possible to move forwards (left click over button) and backwards (right click over button) through the choices.
Menu GravExtent is a special menu called a graphics button. The accompanying display is a graduated slider showing the current gravity extent value in units of points (1/72 of an inch). Clicking over the display with left button will double the gravity extent; clicking with right button will halve the extent. Clicking with middle button will restore the default extent (currently 25 pixels). For values greater than 25 pixels, the slider pointer will "disappear" to the left.
There are four alignment menus: Slope:, Angle:, Radius:, and LineDistance:. Each menu consists of a label, three command buttons (Get!, Add!, Delete!) and a viewer full of Tioga buttons which indicate values and states for the four types of alignment lines. The alignment menus are explained in detail below in the section on activating and deactivating alignment lines. Each alignment menu has a corresponding text viewer in the last line of the control panel. These viewers are automatically updated during various Gargoyle operations and may be explicitly updated as an editable Tioga viewer by the user. The viewer contents are used as operands by the Add! commands. The "units" of distance for these commands is usually inches, but the units can be set to any value via the two buttons ScaleFromSegment and ResetScale.
File Commands
Clear, Reset, Get, Merge, Store, Save, Stuff
These commands all mimic the corresponding Tioga commands.
Clear deletes all objects from the scene.
Reset does a Clear, then reloads the latest version of the current Gargoyle file into the viewer. The current file name appears in the Gargoyle viewer caption.
Get does a Clear, then loads the selected Gargoyle file into the viewer. The file name for loading is taken from the current Tioga selection. If not specified, the directory is assumed to be the directory in which the Gargoyle command was given. If no extension is specified, ".Gargoyle" will be used.
Merge. Select a filename as in the Get operation and double click Merge. All objects represented by that file will be added to the current scene (on top of the existing ones). If not specified, the directory is assumed to be the directory in which the Gargoyle command was given. If no extension is specified, ".Gargoyle" will be used.
Store writes all objects in the current scene to the selected filename (again, the startup directory is the default directory and ".Gargoyle" is the default extension.).
Save writes all objects in the current scene to the current filename, which appears in the Gargoyle viewer caption.
Stuff uses the bounding box of the current Gargoyle selection as a clipping box. The Gargoyle scene is stuffed into the current Tioga viewer at the Tioga caret. Invoking Stuff with the left mouse button causes print fonts to be used; invoking Stuff with the right mouse button causes screen fonts to be used.
Interpress Menu
FromIP
Select the file name of an Interpress master. File names are formed as in the Get command, with the default extension being ".IP". FromIP tries to turn that master into a set of editable Gargoyle objects. This doesn't work very well yet. If the Interpress master was made by Gargoyle then each trajectory ends up as n trajectories, one for each segment, and closed trajectories come back as both a closed Gargoyle trajectory AND a set of n trajectories, one for each segment. Doing this better is a subject of ongoing research.
AddIP
Select the file name of an Interpress master. File names are formed as in the Get command, with the default extension being ".IP". AddIP reads the Interpress master into a single slice and adds that slice to the picture. The innards of the slice are not Gargoyle objects; the slice may be selected and transformed and written out (by "reference" to the full file name; this may cause problems if you transport the Gargoyle file). This is useful for reading in "background" IP masters that you do not want in the scene but may want to see for tracing or ruling purposes.
ToIP, ToIPScreen
Select a file name. File names are formed as in the Get command, with the default extension being ".IP". The picture visible in the Gargoyle viewer minus control points, anchor, and caret will be saved to the named Interpress master. ToIP sends all text strings to Interpress as /xerox/pressfont/ (print) fonts. ToIPScreen sends all text strings to Interpress as /xerox/tiogafonts/ (screen) fonts.
Script Menu
OpenScript, CloseScript, PlaybackScript, FastPlayScript
OpenScript saves all of the subsequent editing actions of a session. Select a file name as for an Interpress file; no default extension is used (.script is the current convention; it used to be .log). Click OpenScript. Until you click CloseScript, all of your actions will be saved in the named file.
To playback the session, select the file name (again, no default extension is provided) and click PlaybackScript. The results will be identical if, when playback begins, Gargoyle is in the same state it was in when you clicked OpenScript (e.g. the same alignment lines are selected and the same gravity extent and type are active). Gargoyle could store its state in the log as well, but this is NYI.
FastPlayScript is the same as PlaybackScript except that Refresh is turned off during playback so it will be faster. If Playback fails for some reason, this could leave Gargoyle with Refresh turned off. In this case, hit Revive! to set things right.
Hierarchy Menu
Delete
Delete the currently selected objects. Also available via the DEL key.
Undelete
Try to restore the scene to its state just before the latest delete command; some subsequent commands (like translations of objects) will not be undone. NOTE THAT MOST OPERATIONS PERFORMED SINCE THE LAST DELETE COMMAND WILL BE LOST. Users should be careful using Undelete; thus, it requires special confirmation in the Message Window. We hope to implement a wonderful UnDo facility in the grand and glorious future. Meanwhile, Undelete does what you want in the common case, which is recovering immediately after an erroneous delete before doing anything else. If you do a series of consecutive deletes, you can try doing multiple undeletes to recover. The current limit on the number of consecutive undeletes is 20.
Fine Point: It may be useful to know how the current implementation works: the system saves a snapshot of the scene before each Delete command is executed. When Undelete is invoked, that scene becomes the current scene. Thus, new objects that have been added since the last Delete are lost. However, some operations such as moving or changing line width of an object will not be undone.
AddHoles
First select an outline (TopLevel select using DoubleLeft click). It must be closed. It can already have holes. Extend the selection as many times as you like, to other closed outlines (they shouldn't have holes). Open the menu and click AddHoles. The first outline will now have as holes all of the rest of the outlines (in addition to the holes it already had). Holes are drawn using wrap number. Nothing horrible happens if the holes are not completely contained in the outline. N.B.: nothing keeps holes within an outline. Selecting TopLevel will select an outline and all of its holes if you want to see where they are.
UnionCombine
In order to use this operation, the module BasicCombiner.bcd must be in the Cedar loadstate. Draw some trajectories in a counter-clockwise direction. Make sure they are convex. Make sure they are closed. Select them. Click UnionCombine. They will be replaced by one or more closed trajectories which represent the union of their areas. This is a slow and expensive operation.
Describe Selected
A human sensible description of the selected object is printed in the feedback line.
Transform Menu
All of these operations work like their interactive counterparts, but use as argument the current Tioga selection interpreted as a real number. Rotate and Scale(s) require the Anchor, as usual. ScaleX and ScaleY provide anamorphic scaling for which there is no interactive equivalent at this time.
Rotate
Place the Anchor and select some objects. In a text viewer somewhere, select a real number. Click Rotate. The selected objects (or parts of objects) be rotated about the Anchor by the number of degrees selected.
Scale, ScaleX, ScaleY
Place the Anchor and select some objects. In a text viewer somewhere, select a real number. Click Scale or ScaleX or ScaleY. The selected objects (or parts of objects) will be scaled about the Anchor by the factor selected. If you clicked Scale, the object will be scaled by the same factor in X and in Y. ScaleX scales only in the X (horizontal) direction, and ScaleY scales only in the Y (vertical) direction.
Caution: if you use a negative scalar, the selected objects may end up off the window. Don't panic. They are still selected. Immediately after a ScaleX, drag from left to right. The objects should come back.
TranslateX, TranslateY
Place the Anchor and select some objects. In a text viewer somewhere, select a real number. Click TranslateX or TranslateY. The selected objects (or parts of objects) will be translated (in X or Y, as appropriate) by the number of "radius units" selected. The default "radius unit" is one inch, but it may be set to the length of any segment via the "RadiusUnitFromSegment" button in the control panel.
Six Point
Select trajectories that have two segments each, and make them hot. Call these two double-segment trajectories A and B (A is the first trajectory you selected, B is the second). Deselect them. Select the objects to be transformed. The selected objects will be transformed with the unique affine transformation with takes the first point of trajectory A to the first point of trajectory B, the second point of A to the second point of B, and the third point of A to the third point of B. Unfortunately, this means you have to remember the order in which the double-segment trajectories were drawn, since this determines which is the first point and which is the second in each of the trajectories A and B. You can discover the order by selecting joints and observing the feedback line. Joint 0 comes first, then Joint 1. You also have to remember the order that A and B were selected when you made them hot. This is both a curse and a blessing—by selecting the trajectories in the other order, you can run the transformation backwards.
Four Point
Select two single-segment trajectories, and make them hot. Deselect them. Call these two single-segment trajectories A and B. Select the objects to be transformed. The selected objects will be transformed with the unique rotation and translation transformation with takes the first point of trajectory A to the first point of trajectory B, the second point of A to the second point of B. Unfortunately, this means you have to remember the order in which the single-segment trajectories were drawn. You can discover the order by selecting joints and observing the feedback line. Joint 0 comes first, then Joint 1. You also have to remember the order that A and B were selected when you made them hot. This is both a curse and a blessing—by selecting the trajectories in the other order, you can run the transformation backwards.
Overlap Menu
Top, Bottom, UpOne, DownOne
Gargoyle maintains a priority order for scene objects. When one of these operations is invoked the selected objects will move in the priority order. This is just like Griffin's overlap menu.
Curves Menu
Straight, Arc, Conic, Bezier, B-Spline, Natural Spline
All selected segments will become segments of the named type. This may require them to change shape. Arc, Conic, Bezier, and Spline(s) create segments with control points on or near the line between the selected segment endpoints. The control points may then be selected and rubberbanded to form the desired shape.
Shapes Menu
Triangle, Square, Pentagon, Hexagon, Octagon
Shapes menu entries are a convenience for making regular polygons. The selected polygon type will be constructed, closed, and filled. The polygon will be centered on the caret and be about 72 pixels square.
FromSelectedCount
A regular polygon of number of sides equal to the current Tioga selection (interpreted as a positive integer) will be constructed, closed, and filled. The polygon will be centered on the caret and be about 72 pixels square.
Knotched Line
Creates a trajectory made of 8 segments, each 0.5 inches long. All of the segments are horizontal. Knotched lines are useful when a number of things must be spaced equally. Also, two knotched lines placed at right angles to each other can be used to trigger all sorts of grids (just turn on two kinds of slope line).
Box
A new box object with center at the caret will be constructed. This is the same kind of box object that can be interactively created with the AddBox operation. See AddBox (above) for documentation on boxes.
Circle
A new circle object with center at the caret will be constructed. Circles may be translated/rotated/scaled as usual and will retain their circular characteristics, or turn into ellipses if unevenly scaled. Circles are displayed with control points at the center and at 90 degree intervals around the circle. Selecting and dragging a single control point on the circumference will grow/shrink the circle about its center. Selecting and dragging the circle center will translate the circle. Transforming a circle selected as a trajectory or top level object will transform the entire circle.
8.5 by 11
A new unfilled box object with line width = 9 will be added to the scene. The box is positioned so that the "inner" lower left corner is at location [0.0, 0.0]. The "inner" dimension of the box is 8.5 inches by 11.0 inches. This frame is helpful for positioning Gargoyle objects onto a standard printed page; any objects within the inner frame should appear on the printed page. Be reasonable and don't put objects in the extremes of the frame; mechanical printing devices are not that exact and your edges will be chopped. Don't forget to delete the frame before saving or printing.
Text Menu
AddText
The text string in the Tioga selection is copied to the Gargoyle caret in the default font (currently Helvetica10). This is NOT the only way to get text into Gargoyle; see the section below on keyboard features.
FontNameFromSelection
All selected text strings acquire the font name in the Tioga selection. Font names should be a string with the font family, size, and face such as Helvetica14BI or TimesRoman36B or Gacha10.
PrintSelectedFontName
Prints the font name of the selected text in the feedback line.
DefaultNameFromSelection
The default text font acquires the font name in the Tioga selection. Font names should be a string with the font family, size, and face such as Helvetica14BI or TimesRoman36B or Gacha10. Any strings subsequently added to the scene will be rendered with the new default font.
PrintDefaultFontName
Prints the default font name in the feedback line.
Debug Menu
Test Gravity, Test MultiGravity, PerformanceStats, ResetStats, Draw Touch Points, Describe Touch Points, Draw Bounding Boxes, Draw Outline Boxes, Draw Selection Box, Draw Moving Box, Typescript, SlackLog, Describe Caret Object, FSM Info, Print All Input, Reset All Input
The only user-oriented entry are Typescript and Print/Reset All Input; the remainder are various debugging aids for use by Gargoyle implementors. If Typescript is clicked, a typescript viewer will be opened and messages for the user will be sent to the typescript instead of to the feedback line. This is useful as a record of what Gargoyle does for you. The typescript may be destroyed at any time. If Print All Input is clicked, the typescript will show every atom, number, character, and mouse coordinate that the Input Notify procedure in Gargoyle sees. Click Reset All Input to return to normal user messages. The mouse coordinates are in Gargoyle client coordinates, so printing all input is useful for finding out exactly what the cursor/caret coordinates are.
Abort!
The Abort menu has been replaced by a high priority process that looks for the key combination SHIFT-SWAT when any painting is initiated AND the cursor is in the Gargoyle action area. To abort script playback, painting, or gravity testing hold down SHIFT-SWAT for at least two seconds with the cursor in the Gargoyle action area.
Refresh!
Refresh the Gargoyle viewer from scratch.
Revive!
A very important button. If Gargoyle is not responding (usually after an ERROR window has been aborted) or if Gargoyle is acting confused (e.g. displaying objects which you're sure you deleted), this button is for you. It creates a new slack process, restores some invariants and presses on. It almost always works. Invoking Revive with the left mouse button will cause a full repaint; invoking with the right button will avoid repaint which is useful in case it is the refresh itself that is causing the ERROR.
Help!
A very important button. On-line documentation. Displays a short reminder of the function of each of the 12 mouse button, SHIFT, CTRL combinations and double click combinations as well. Grow the Help viewer for a full summary of the META commands and the remainder of the Gargoyle user operations.
LineWidth Menu
These operations set the stroke width of currently selected segments.
0 pt, 1 pt, 2 pt, 3 pt, 4 pt.
Sets the line width of all selected segments to the given number of screen points. The four functions are available from the keyboard as LOOK 0, LOOK 1, LOOK 2, LOOK 3, and LOOK 4. Segments of line width zero will normally disappear, but will be highlighted if selected.
FromSelection
Sets the line width of all selected segments to the number of screen points in the Tioga selection. The Tioga selection should be a positive real number.
PrintSelected
Prints the line width of the selected segment in number of screen points.
Color Menu
These operations set the color of selected segments. Some of them require that the ColorTool be in the Cedar loadstate.
None, Black, White, Gray
Sets the color of all selected segments to the given color.
FromColor Tool
Sets the color of all selected segments to the color displayed by the ColorTool.
FollowColorTool
Sets the color of all selected segments to the color displayed by the ColorTool, and follow that color as the ColorTool manipulates the color. To terminate FollowColorTool when the desired color is reached, click FromColorTool. The "following" only works when ShowColors is on and the color display is in 8 bits per pixel and dithered mode and the colorpatch is visible on the display.
ToColorTool
Sets the ColorTool color to be the color of the first selected segment.
FromSelectedName
Sets the color of all selected segments to the color in the current Tioga selection as interpreted by the Color Naming System (CNS). CNS is documented at the bottom of the ColorTool. A CNS name consists of up to three descriptive terms: Saturation, Lightness, and Hue.
PrintSelected
Prints the color of the current selected segment as an RGB triple and a color name in the feedback line.
Fill Menu
These operations fill all the currently selected closed trajectories. Some of them require that the ColorTool be in the Cedar loadstate.
None, Black, White, Gray
Sets the area color of all selected closed trajectories to the given color.
FromColor Tool
Sets the area color of all selected closed trajectories to the color displayed by the ColorTool.
FollowColorTool
Sets the area color of all selected closed trajectories to the color displayed by the ColorTool, and follow that color as the ColorTool manipulates the color. To terminate FollowColorTool when the desired color is reached, click FromColorTool. The "following" only works when ShowColors is on and the color display is in 8 bits per pixel and dithered mode and the colorpatch is visible on the display.
ToColorTool
Sets the ColorTool color to be the color of the first selected closed trajectory.
FromSelectedName
Sets the area color of all selected closed trajectories to the color in the current Tioga selection as interpreted by the Color Naming System (CNS). CNS is documented at the bottom of the ColorTool. A CNS name consists of up to three descriptive terms: Saturation, Lightness, and Hue.
PrintSelected
Prints the color of the current selection as an RGB triple and a color name in the feedback line.
AreaSelect Menu
These operations change the current selection. Object "A" is said to be within Object "B" when Object A's bounding box is completely contained in the bounding box of Object B.
New
Selects all objects within the current selection(s) and deselects the original selection(s).
NewWithDelete
Selects all objects within the current selection(s) and deletes the original selection(s).
Extend
Adds all objects within the current selection(s) to the current selection(s).
All
Same as SelectAll (CTRL-D)
Degenerate
Selects all objects with zero size bounding boxes. Useful for locating point sized objects.
Edit Menu
Close
Select the end joint of an open trajectory. Click Close. A straight line will be added to make the trajectory closed and filled.
Weld
Select two open trajectories. Click Weld. The second one selected will be translated to the nearest end point of the first one selected. They will become a single trajectory. A trajectory may be welded closed to itself if its endpoints are coincident.
Add CP
Place the caret on a segment of a curve type which has control points. Click Add CP. A new control point will appear at the caret and the curve will be adjusted accordingly.
Delete CP
Select a control point. Click Delete CP. The control point will disappear and the curve will be adjusted accordingly. You cannot delete a CP by selecting it and hitting the DEL key.
Add Joint
Place the caret on a segment. Click Add Joint. A new joint will appear at the caret and the curve redefined with an additional segment.
ReplaceSegment
Select any number of segments. Position the caret where you will. Each selected segment will be replaced by two segments, one from the lower endpoint of the segment to the caret, and a second from the caret to the upper endpoint of the segment.
Splice
Select any number of contiguous segments (runs) within some trajectories. Click Splice. Each run of segments will be replaced by a single straight line segment.
HotSpots Menu
Hot objects trigger alignment lines. Users explicitly make objects hot and cold (not hot) using these commands. This menu also includes Anchor commands. The anchor is always considered a hot point.
MakeHot, MakeAllHot, MakeCold, MakeAllCold
Makes (respectively) the current selections hot, every object hot, the current selection cold, all objects cold. You will quickly find yourself using the keyboard accelerators for these commands (CtrlS for MakeHot and CtrlShiftS for MakeCold; CtrlDoubleS for MakeAllHot and CtrlShiftDoubleS for MakeAllCold).
ShowHot, HideHot
Hot objects can have their joints highlighted with large white squares around the joints. ShowHot causes these highlights to appear; HideHot hides the highlights. This is really a display mode.
DropAnchor, LiftAnchor
Drop Anchor, Lift Anchor. Drop Anchor puts the Anchor at the current caret position (same as CtrlA). Lift Anchor removes the anchor from the scene altogether (same as CtrlShiftA).
StandardAlignments
Standard Alignments replaces the current alignment menus with the default or standard ones that come with a fresh Gargoyle viewer.
Units Menu
All of the dimensionless fractions (1/8, 1/4, etc.) on the Radius: alignment menu (see below) and the distances on the LineDistance: alignment menu initially have a scale factor of inches. The scale factor may be changed via the Units menu.
FromSegment
The length of a segment in the scene can be used to change the scale factor. Select a segment, then click FromSegment, and length 1 will be normalized to the length of this segment. Useful for constructing midpoints and for editing shapes which have been scaled since they were made.
FromRadiusValue
The value in the RadiusValue menu can be used to change the scale factor. Click FromRadiusValue and the new scale factor will be the RadiusValue multiplied by the current scale factor.
FromSelection
The scale factor in points can be set directly from the Tioga selection interpreted as a positive real.
Inches
Inches sets 1 unit = 1 inch.
Centimeters
Centimeters sets 1 unit = 1 centimeter.
PrintCurrent
Displays the current scale factor in points, inches, and centimeters in the feedback line.
ShowColors Toggle Button
When ShowColors is off all motions should appear smooth and continuous. The user has no perception of the order in which things are being drawn. However, smooth motion relys on cached bitmaps which are not implemented for the color display. So, to see a Gargoyle scene in living color you must turn ShowColors on (and move the viewer to the color display, of course). You can still execute interactive operations, but you will not get interactive feedback on the display and the caret will leave tracks wherever it goes during an interactive operation.. Turning ShowColors on can also help with debugging, and can give the user an idea of what is taking so long in repainting.
ScreenStyle Menu
PrintFonts, ScreenFonts, WYSIWYG
A set of schemes for deciding how to paint the screen. The ScreenStyle button cycles through the three choices (left click to cycle forward, middle or right click to cycle backward). PrintFonts causes use of printer fonts and font metrics to display text. ScreenFonts causes display of more readable text, but the hit testing and other bounding box operations still use the printer font metrics. WYSIWYG causes the display to mimic an Interpress master; no control points or selections are shown and printer fonts are used for display.
GravType (Gravity Choice) Menu
Strict Distance, PreferPoints
A set of schemes for deciding which, of the objects that are close to the cursor, should be snapped to. Strict Distance simply chooses the closest object. PreferPoints prefers to map to points rather than lines if the points are sufficiently close. The GravType button toggles between Points Preferred and Strict Distance.
Gravity Extent
Left-Clicking in this small window doubles the gravity extent. Right-Clicking halves the gravity extent. Middle-Clicking resets the gravity extent to its default value. The picture in the window is of a caret placed <gravity extent> units from the right edge of the window.
Gravity Toggle Button
Clicking this button toggles gravity on and off. The button is video reversed when Gravity is on. Gravity toggling can also be invoked interactively with CtrlSPACE, ShiftSPACE, or CtrlShiftSPACE while in the midst of other interactive operations.
Alignments Toggle Button
Clicking this button toggles alignments on and off. The button is video reversed when Alignments are on. When Alignments are off, no alignment lines will be generated or displayed. The state of the alignment menus is unaffected by toggling Alignments.
Midpoints Toggle Button
When Midpoints is on (video-reversed) the midpoints of all segments will be gravity-active. When the caret has snapped to a midpoint, the message "Caret on midpoint of segment .." will appear in the typescript or message window.
Heuristics Toggle Button
When Heuristics is on (video-reversed), Gargoyle will attempt to be smart about generating alignment objects automatically. When Heuristics is off, only the Anchor and hot objects will generate alignment lines.
Alignment Menus: Activating and Deactivating Alignments
Slope Menu
Clicking any of the buttons 0 30 45 ... 150 (or buttons added by the user) will make that button turn bold and will activate that slope. All hot vertices will now trigger alignment lines of the specified slope. Clicking again deactivates a particular slope. Any number of slopes may be active simultaneously. Clicking the word "Slope:" at the beginning of the line deactivates all slope alignment lines.
Angle Menu
Clicking any of the buttons 90 60 ... -90 (or buttons added by the user) will make that button turn bold and will activate that angle. All hot segments will now trigger alignment lines at the specified angle to themselves, not to the horizontal. Clicking again deactivates a particular angle. Any number of angles may be active simultaneously. Clicking the word "Angle:" at the beginning of the line deactivates all angle alignment lines.
Radius Menu
Clicking any of the buttons 1/8 1/4 ... 1 2 4 (or buttons added by the user) will make that button turn bold and will activate that radius. All hot vertices will now trigger alignment circles of the specified radius. Clicking again deactivates a particular radius. Any number of radii may be active simultaneously. Clicking the word "Radius:" at the beginning of the line deactivates all alignment circles.
LineDistance Menu
Clicking the button 0 (or buttons added by the user) will make that button turn bold and will activate that distance line. All hot segments will now trigger two alignment lines parallel to the hot segment at the specifed distance from the segment. Clicking again deactivates a particular distance. Any number of distance lines may be active simultaneously. Clicking the word "LineDistance:" at the beginning of the line deactivates all parallel alignment lines.
Turning All Alignments Off
CtrlQ toggles alignments. It is equivalent to clicking the Alignments menu button. CtrlShiftQ turns all alignment menu items off. It is equivalent to clicking "Slope:", "Angle:", "Radius:", and "LineDistance:" in succession.
Alignment Menus: Adding and Deleting Your Own Alignment Objects
Slope Menu
You may click the "SlopeValue" text viewer button on the bottom line of the control panel and type a slope value (in degrees in the range [0..180) ) into the viewer. Click the Add! button on the Slope: menu line. Your special slope will be added to the list and activated. Alternatively, if you are interested in the slope of an existing line segment, you can select that segment and click Get! on the Slope: menu line. The slope of the selected segment will be added to the list and made active.
Any item on any of the lists can be deleted by activating it and clicking Delete! on the associated line.
Angle Menu
You may click the "AngleValue" text viewer button on the bottom line of the control panel and type an angle (in degrees in the range (-180..180] ) into the viewer. Click the Add! button on the Angle: menu line. Your special angle will be added to the list and activated. Alternatively, if you are interested in the angle between adjacent lines in a trajectory, you can select adjacent segments in that trajectory (or the entire trajectory) and click Get! on the Angle: menu line. The angle(s) between selected adjacent lines in the trajectory will be added to the list and made active.
Any item on any of the lists can be deleted by activating it and clicking Delete! on the associated line.
Radius Menu
You may click the "RadiusValue" text viewer button on the bottom line of the control panel and type a radius value (in "units", a real number) into the viewer. Click the Add! button on the Radius: line. Your special radius will be added to the list and activated. Alternatively, if you are interested in the length of an existing line segment to use as a radius, you can select that segment and click Get! on the Radius: menu line. The length of the selected segment will be added to the list and made active.
Any item on any of the lists can be deleted by activating it and clicking Delete! on the associated line.
LineDistance Menu
You may click the "LineDistanceValue" text viewer button on the bottom line of the control panel and type a distance value (in "units", a real number) into the viewer. Click the Add! button on the LineDistance: line. Your special distance will be added to the list and activated. Alternatively, if you are interested in the length of an existing line segment, you can select that segment and click Get! on the LineDistance: menu line. The length of the selected segment will be added to the list and made active.
Any item on any of the lists can be deleted by activating it and clicking the Delete! on the associated line.
Alignments and Measuring
At the beginning of every command which moves the caret, the initial position of the caret is recorded by Gargoyle, and the previous initial position is remembered as well. Gargoyle then follows the moving caret and updates (interactively, but somewhat infrequently) the four text viewers to reflect the caret motion. Call the "previous" initial position A and the "current" initial position B. Call the current (interactive or final) position of the caret C. The distance between B and C is posted in the RadiusValue text viewer. The slope of the line BC is posted in the SlopeValue text viewer. The angle ABC between the two line segments AB and BC is posted in the AngleValue text viewer. The perpendicular distance between the line AB and the point C is posted in the LineDistanceValue text viewer. Slopes and angles are measured counterclockwise. Slopes are converted to the range [0..360); angles are converted to the range (-180..180].
Feedback Line
One line at the bottom of the control panel has been reserved for short messages to the user. These are particularly handy while dragging or place the caret when a description of the object to which the caret is snapping appears in this region.
Keyboard Features
The following summarizes keyboard actions. These may be augmented or altered in future as Gargoyle evolves. Text is admittedly primitive at this time.
Unless a LOOK or CTRL/SHIFT sequence (see below) is typed, text may be entered directly into Gargoyle at the caret by typing on the keyboard. BS will work during type-in. The caret will remain at the origin while text is entered. Any mouse action terminates text input. An existing text string may be edited in place by first selecting it and then typing BS. The selected string will be restored to the state it was in before it was terminated; more characters may be added to the end of the string by type-in and BS will work to edit existing parts of the string.
A text object has seven "segments" and twelve "joints" associated with it. The following picture shows the numbered joints and the named and numbered segments.
[Artwork node; type 'ArtworkInterpress on' to command tool]
Text Points as shown
Text Edges: 0 => left, 1=> top, 2=> right, 3=> bottom, 4 => baseline, 5 => horizontal centerline, 6 => vertical centerline
SHIFT-SWAT: Abort
If the cursor is in the Gargoyle action area and SHIFT-SWAT is held down for about two seconds, an abort action will occur. Painting will cease, the event queue will be flushed, gravity testing will cease (if it is in progress), and Gargoyle will regain its composure.
SHIFT-SHIFT-SWAT: Emergency Save
Emergency save is provided by the Viewer package; it works for Gargoyle files as well as other (Tioga, for example) files. Hold down SHIFT-SHIFT-SWAT until the cursor changes to a black square. Gargoyle should do a Save operation. If there is no file name associated with the Gargoyle viewer, Emergency.Gargoyle will be used as the short file name.
DEL: Delete
Deletes all selected objects. Equivalent to the Delete menu command in the Hierarchy menu.
LOOK 0,1,2,3,4:
Hold down the LOOK key (Spare1 on Dorado keyboards) and type one of the digits. Selected segments will acquire stroke width of the digit typed.
ShiftSpace, CtrlSpace, CtrlShiftSpace: Toggle Gravity
Equivalent to pushing the Gravity toggle button.
CtrlBS, ShiftBS, CtrlShiftBS: Delete caret segment
If the caret is on the end of an open trajectory, deletes the caret segment and positions the caret on the end of the previous segment in the trajectory.
CtrlA/CtrlShiftA: Drop/Lift Anchor
Drop or Lift Anchor. Equivalent to the DropAnchor and LiftAnchor menu commands in the HotSpots menu.
CtrlB: Toggle ShowColors
Equvalent to pushing the ShowColors toggle button.
CtrlC or CR: Close
If the current caret trajectory is open, close it with a straight line segment and fill it with gray color.
CtrlD: Select All
Similar to the Tioga CtrlD. Selects all objects in the scene.
CtrlG, CtrlShiftG: Toggle Gravity Choice
Equivalent to pushing the GravType button.
CtrlH: Add Holes
Equivalent to the AddHoles command in the Hierarchy menu.
CtrlJ: Add Joint
Equivalent to the AddJoint command in the Edit menu..
CtrlP: Add Control Point
Equivalent to the Add CP command in the Edit menu..
CtrlShP: Delete Control Point
Equivalent to the Delete CP command in the Edit menu..
CtrlQ: Toggle Alignments
Equivalent to pushing the Alignments toggle button.
CtrlShiftQ: Kill Alignments
Equivalent to clicking "Slope:", "Angle:", "Radius:", and "LineDistance:" menu buttons in succession.
CtrlS/CtrlShiftS: Make Hot/Make Cold
CtrlDoubleS/CtrlShiftDoubleS: Make All Hot/Make All Cold
Equivalent to pushing the corresponding button in the HotSpots menu.
CtrlW: Weld
Equivalent to pushing the Weld item in the Hierarchy menu.
ESC: Interpress Snapshot
Writes a snapshot of the current screen on file Snapshot.IP in the local directory.
Known Deficiencies
Many and various are the plans for further development of Gargoyle, including implementing structure editing as well as object editing, hierarchical clustering of objects, graphical style, and integration with Tioga text editing. Patience.