This manual provides an exhaustive description of the features which have been implemented so far, as seen by the user. A tutorial introduction will be written later. To startup gargoyle:
The remainder of this document describes first our terms. second the Gargoyle features which are available only via the mouse, and third the features provided by the Menus, listed in the order in which the menu buttons appear.
Terms
Trajectory. A connected sequence of line segments and/or curve segments.
Segment. A single straight line segment, circular arc, piece of a conic, cubic Bezier curve, or Interpolatory spline. A segment has two endpoints called joints.
Joint. One of the two endpoints of a segment. Joints are drawn in Gargoyle as small squares, which are normally hollow but become black when they are selected.
Alignment line. A greyed straight line or circle which appears during an operation which requires precision, such as dragging, rotating, scaling, and rubberbanding. Which lines appear depends on the operation being performed and on which types of alignment line the user has activated on the control panel.
Control Panel. The set of buttons at the top of the Gargoyle viewer.
Gravity. The mapping from cursor position to caret position. This mapping often lands the caret onto an alignment line or trajectory. Two types of gravity are available (see below).
Gravity Extent. The farthest the cursor can be from a gravity sensitive object and still map the caret onto that object.
Caret. The upside-down V shaped object which appears during most interactive operations. The caret is used as the first endpoint of a new trajectory. It also acts as a kind of tugboat, pulling the object it is sitting on toward some object which it is attracted to (i.e. by gravity). Also used as an insertion point (e.g. when trajectories are copied, the copy is placed at the caret position. The anchor is always created at the caret position.
Anchor. The center of rotation and the center of scaling. Currently appears as a largish black square (yuk).
NYI. Not yet implemented.
Hot Joints, Hot Segments. A joint or segment is hot if it triggers alignment lines during Select Point, Add Line, Drag, Rotate, and Scale operations. Hot joints can trigger slope lines, compass circles and can attract the caret themselves. Segment can attract the caret themselves.
Interactive Features
A summary of the Gargoyle mouse actions can viewed at any time by clicking the TIPTable button on the control panel. The actions are these:
Select Point. This button serves two purposes. First, it is a way of placing the caret. Hold down the mouse button and the caret follows the cursor arrow. Any selected alignment lines will become gravity sensitive, so the caret may be placed with precision. One important reason to place the caret is to begin a new trajectory (see Add Line below). Second, it is a way of selecting joints and segments. If gravity sucks the caret onto a joint, the joint will temporarily be highlighted (appear as a filled black square). Releasing at this point will cause all selected objects to be deselected expect that joint. Likewise, if the caret gravitates to the middle of a segment, both of its end-joints are highlighted. Releasing leaves only that segment selected.
Select Trajectory. Clicking the button down near (the bounding curve of) a trajectory will select the entire trajectory. All of its joints become hightlighted. This feature is not fully implemented; the selection takes place on the button down-stroke (unlike Select Point).
Extend Selection. Not yet implemented. Someday you will be able to select multiple objects and multiple parts of objects. The selection code will already allow this. The user interface won't.
Copy Select Point. Not yet implemented.
Copy Select Trajectory. Clicking the button down near (the bounding curve of) a trajectory will cause that trajectory to be copied. The copy will be placed so that its first joint is on the caret. (First joint is not a very intuitive concept. If the trajectory is open, the first joint is one of the ends -- the end which the user started at when the trajectory was made.) This feature is not fully implemented; the selection takes place on the button down-stroke.
Extend Copy Select. Not yet implemented.
Add Line. Create a new straight line segment whose endpoints are the caret and the current cursor position. Holding down the mouse button and moving the mouse causes alignment lines to appear and the caret to jump to the cursor end of the segment, so the new endpoint can be placed with precision. If the caret was initially on the end-joint of an open trajectory, the new segment is appended to that trajectory. Otherwise, a new trajectory is begun. Since multiple trajectories can end at the same joint, adding a new segment can be ambiguous. Currently this ambiguity is resolved randomly (yuk).
Drag. All selected objects are translated, maintaining a constant relationship to the caret. Dragging is usually performed in three stages. First, select the objects to be dragged (if parts of trajectories are selected, then those trajectories will be rubber-banded). Second, place the caret near that joint or segment which must be positioned with precision. As the mouse button is pushed down, the caret will use the current gravity function to snap to that joint or segment. Finally, hold down the mouse button and move the mouse. The cursor will be attracted to gravity-sensitive objects as usual, taking all of the selected objects with it.
Rotate. 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. 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 jump to the nearest object 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. Very much like rotate. The Anchor is the center of scaling. The scaling factor is the ratio of the current distance of the caret from the Anchor over the distance from the caret to the Anchor at the beginning of the Scale operation.
Scroll and Zoom. Not Yet Implemented.
Menu Features
File Commands
Clear, Reset, Get, Store, Save, Split
Not yet implemented. Gargoyle has no file format.
Interpress
Select a file name. If a short file name is given, the directory which Gargoyle was started in is assumed. The picture visible in the Gargoyle viewer will be written as an interpress file. This is not really what you want. You want the joints and caret to not appear. Coming soon.
OpenLog, CloseLog, Playback, FastPlay
Save all of the editing actions of a session. This can be used as an interim file format. Select a file name as for an interpress file. Click open log. Until you click CloseLog, all of your actions will be saved in the name file.
To Playback the session, select the file name and click Playback. The results will be identical if, when playback begins, Gargoyle is in the same state it was in when you clicked OpenLog (e.g. the same alignment lines are selected), and if no non-deterministic commands were performed (e.g. creating curved segments). Gargoyle could be written to store its start state in the log as well, but this has not been done.
FastPlay is the same as Playback except that Refresh is turned off during playback so it will be faster. If Playback fails (ERROR window), this could leave Gargoyle with Refresh turned off. In this case, hit Revive! to set things right.
Two files: BigG.log, StarOfDavid.log, and Hexagons.log are provided as examples. Before playing any of them, delete all objects, turn off all alignment lines and reset gravity back to its default extent (25.0).
Hierarchy Menu
Delete (nothing else in this menu is implemented).
Delete the currently selected trajectories. Deleting parts of trajectories is NYI; Gargoyle will complain and ignore that particular selected object.
Curve Menu
Straight, Arc, Conic, Bezier, Spline
All selected segments will become segments of the named class. This may require them to change shape. Arc, Conic, Bezier, and Spline use a random number generator to create the intermediate control points.
Transform Menu
The menu isn't even implemented.
Overlap Menu
No aspects of priority ordering are implemented. This can be quite annoying.
Edit Curve Menu
Show Points, Hide Points, Close
Show Points. Joints of the selected objects will henceforth be displayed as hollow squares at all times except: 1) Selected joints will appear as filled squares. 2) Joints which are being rubber-banded are not drawn.
Hide Points (the default). Joints will not be shown at all except: 1) Selected joints will appear as filled squares, when not rubberbanded. 2) During Add Line or Rubberband operations joints will be shown which are hot (i.e. which are gravity sensitive).
Close. If the caret is on an open trajectory, the trajectory will become closed by the addition of a straight line segment and filled with the color gray. If the trajectories endpoints are already coincident, the code goes ahead and adds a lenght zero line (on the list of things to fix), but nothing horrible happens.
View Menu
Not yet implemented.
Debug Menu
Test Gravity, Draw Touch Points, Describe Touch Points, Draw Bounding Boxes, Draw Selection Box, Typescript, SlackLog, Describe Caret Object
Test Gravity. Draw a scatter-gram of the current gravity field.
Draw Touch Points, Describe Touch Points. Gargoyle keeps track of joints touching joints, and joints touching segments. Draw Touch Points draws a '+' sign at each point where it thinks two or more objects are touching. Describe Touch Points describes these touching points in English, giving information about how many objects are touching and which parts. Touching constraints are hard to debug, so every little bit helps.
Draw Bounding Boxes, Draw Selection Box. Draw Bounding Boxes draws the bounding box around every trajectory in the scene. Draw Selection Box draws the box which bounds all selected objects.
Typescript. Opens a gargoyle typescript which will display all of the messages which Gargoyle sends to the MessageWindow and some other messages as well.
SlackLog. Prints into the typescript the last 20 actions received by the slack process. Useful for understanding the slack process.
Describe Caret Object. Describe the object which the caret is currently on. This can help find mysterious invisible objects which grab the caret.
Abort!
Doesn't do much yet. Aborts the Test Gravity operation.
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.
TIPTable
On-line documentation. Displays a short reminder of the function of each of the 12 mouse button, SHIFT, CTRL combinations.
Line Width Menu
1 pt, 2 pt, 3 pt, 4 pt, other.
Sets the line width of all selected segments to the given number of screen points. Other is a reminder that we need a popup menu package which can handle type-in. For now, "other" makes lines of width 5 pts. The first four functions are available from the keyboard as LOOK 1, LOOK 2, LOOK 3, and LOOK 4.
Area Color Menu
Color From Color Tool - NYI
Black, White, Gray
Sets the area color of all selected closed trajectories to the given color.
Gravity Choice
Strict Distance, Points Preferred, None
A set of schemes for deciding which, of the objects which are quite close to the cursor, should be mapped to. Strict Distance simply chooses the closest. Points Preferred prefers to map to points rather than lines if the points are sufficiently close. None means that no mapping is done. An odd consequence of turning gravity off is that objects may not be selected. This should probably be fixed (at least for the Select Trajectory command).
Gravity Extent
(See Terms above for a definition)
Left-Clicking in this window doubles the gravity extent. Right-Clicking halves the gravity extent. The picture is of a caret placed <gravity extent> units from a vertical alignment line.
Hot Spots Menu
Make Hot, Make Cold, Drop Anchor, Lift Anchor
Make Hot, (Make Cold). Makes all selected objects hot (cold). Hot objects trigger alignment lines and are themselves gravity sensitive. Gargoyle allows certain objects to trigger alignment lines without being hot (e.g. the unselected parts of a trajectory which is being rubberbanded), but usually making an object hot is the only way to be able to snap to it or to alignment lines triggered by it. Objects are not hot by default. You will quickly find yourself using the keyboard accelerators for these commands (CTRL-S and CTRL-SHIFT-S).
Drop Anchor, Lift Anchor. Drop Anchor puts the Anchor at the current caret position. Lift Anchor removes the anchor from the scene altogether.
DoubleBuffer
When DoubleBuffer is on (video-reversed) all motions should appear smooth. The user has no perception of the order in which things are being drawn. Turning DoubleBuffer off can help with debugging, and can give the user an idea of what is taking so long.
AlwaysOn
When AlwaysOn is video-reversed, operations which use alignment lines draw all of them on the screen as soon as the command begins. Otherwise, the alignment lines are drawn one at a time as the cursor comes close to them. Many people find the latter mode too flickery. Since drawing alignment lines takes time, the second mode always makes the caret move less smoothly.
Adding Slopes and Radii
You may type a slope (in degrees in the range [0..180)) next to Slope and click Add!. Your special slope will be added to the list. You must still select it to make it active. Alternatively, if you are interested in the slope of an existing line segment, you can select that segment and click GetSlope!. The slope of the selected segment will be added to the list. Again, you must still select it to make it active.
Similarly you may type the radius of a compass circle (in screen dots, 72 to the inch (yuk)), and click Add! or select a segment whose straight line length (from end to end) is of interest, and click GetRadius! to add these numbers to the Radius list.
Coordinates
At the beginning of every command which moves the caret, the initial position of the caret is stored in the lastCaret: slot, and the current position is dynamically updated in the currentCaret: slot. The distance between the two positions is updated (more infrequently) in the distance: slot. By copying this distance into the Radius: slot above it is possible to create compass circles whose radius depends on arbitrary locations in the viewer.