BiScrollersDoc.tioga
Spreitzer, May 6, 1985 9:05:15 pm PDT
Mike Spreitzer August 26, 1986 11:20:56 am PDT
BiScrollers
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
BiScrollers
Mike Spreitzer
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: BiScrollers are a subclass of Viewers that provide two-dimensional scrolling.
Keywords: Viewer, Scroll, Two-Dimensional, User Interface, Graphic, Screen, I/O
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
1. The Client Interface
1.1. BiScrollers
The interface BiScrollers.Mesa contains the main client interface to BiScrollers.
There are different user interfaces available for a BiScroller. A BiScrollerStyle represents a user interface. They are accessed by name. If GetStyle is given a NIL name, it will choose a default.
The Cedar Viewers package is organized so that `Viewers' is a class (in the Simula or SmallTalk sense), of which clients can make subclasses (each represented by a ViewerClasses.ViewerClass). `BiScrollers' is a subclass of `Viewers', and it is also prepared for sublcassing (each sublcass is represented by a BiScrollers.BiScrollerClass). A client of BiScrollers typically creates a subclass of `BiScrollers' by calling NewBiScrollerClass, and then creating instances (i.e., actual Viewers) with CreateBiScroller.
A BiScroller is much like a Viewer. It has a PaintProc, a NotifyProc, a tipTable, and so on. The difference is in the scrolling. BiScrollers do not have ViewerClasses.ScrollProcs. The scrolling is almost entirely managed by the BiScrollers package. All the client has to do is provide a way to determine the bounds of its interesting display. This is done with a BiScrollers.ExtremaProc.
A client of BiScrollers uses its own coordinate system. In the PaintProc, the Client coordinate system of the given Imager.Context is the BiScrollers client's coordinate system. In the NotifyProc, the element corresponding $Coords in the TIP-table is a BiScrollers.ClientCoords, which is in client coordinates. In the ExtremaProc, the direction is given in client coordinates, and the results should be returned in client coordinates. The BiScrollers implementation manages the relation between the client coordinates and the Viewer's coordinates.
The ExtremaProc is how the client tells BiScrollers the bounds of the area in client coordinates that the client paints in. If a client, in its current state, will paint an area S ‚ R2, and is given a direction vector dir, it should return vmin and vmax such that v  S: dir " vmin d dir " v and dir " vmax e dir " v (where " means dot product). A client's ExtremaProc will be called whenever BiScrollers needs to know the bounds of the client's data. This will probably not be much more often than when the user clicks a mouse button.
1.2. Geom2D
Contains geometric routines that are likely to be useful for BiScrollers clients. In particular, ExtremaOfBounds should make many ExtremaProcs easy to write.
2. The User Interfaces
BiScrollers has multiple user interfaces available. Currently, there are two implemented. One of them ("Buttonned") reserves areas along the sides of the Viewer, analogously to the standard scrollbars. The other ("Buttonless") has no such reserved areas, and uses instead mouse-clicks over the contents.
BiScrollers maintains a transformation between viewer coordinates and client coordinates. This transformation can include translation, scaling (possibly different horizontally and verically), and rotation.
2.1. Common Stuff
There are some standard operations applicable to all BiScrollers. Each tool built with BiScrollers will make some or all of these available through either a menu or a set of buttons.
Scale
Doubles the apparent linear dimensions of the client's image when hit with the left mouse button. The right halves. The middle resets. If the current Tioga selection is a number (occupying more than one character), that number is used instead of 2.
Rotate
Rotates the image 90 degrees to the left when hit with the left mouse button. Rotates right when hit with the right button. Cancels rotation with the middle button. Rotates 180 degrees with shift-middle. If the current Tioga selection is a number (occupying more than one character), that number is used instead of 90.
Fit
Scales and translates the image so as to maximize magnification while fitting the entire image in the viewer.
Reset
If hit with the left or middle mouse button, the entire transformation is reset to what the tool thinks is a vanilla value. Then, if the middle or right button was used, the image is centered.
Left (menu only)
The left edge of the client area is aligned with the left edge of the viewer. This scrolls in only one dimension.
Right (menu only)
Top (menu only)
Bottom (menu only)
Edge (button only)
This will perform one of 12 alignment operations. They include the 4 edge alignments. There are also 4 corner alignments. Finally, there are 4 alignments for the centers of the edges.
Prev
Analogous to Tioga's "PrevPlace" button. There is a "previous transform" register, which gets loaded with the current transform just before certain operations. The "Prev" button swaps the current transform and the previous transform. The operations that load the previous transform register are: Fit, ResetAndCenter, Center, Vanilla, Left, Right, Top, Bottom, Prev, Thumb, Expand, and Contract.
2.2. The Buttonless Interface
The buttonless user interface is activated by mouse clicks and motions, all of which must happen while the shift-lock key is down. This reserves all the other (more normal) encodings for the client to use. Some mouse clicks depend only on where the mouse button is let up; others also depend on where the mouse button is depressed. Here are the operations available:
Scroll To Center (Left)
The location where the mouse button is let up is moved to the center of the viewer. Feedback is given while the mouse is moving.
Two-Point Scroll (Shift Left)
The location where the mouse button was depressed is moved to the location where the mouse button was let up. Feedback is given while the mouse is moving.
Thumb (Middle)
A two-D analog to the standard scrollbar. The viewer area is considered mapped onto all of the client area, and a grey patch is shown for the client area currently visible. This patch tracks the mouse. When the mouse button is let up, the transform is appropriately adjusted.
Expand (Right)
The location where the mouse button is depressed specifies the center of a rectangle; the location where the mouse button is let up specifies a corner. The scale and offsets are adjusted to maximize scale factor while keeping all of the image under the indicated rectangle visible.
Contract (Shift Right)
The location where the mouse button is depressed specifies the center of a rectangle; the location where the mouse button is let up specifies a corner. The scale and offsets are adjusted so that the part of the image previously visible now occupies the rectangle.
2.3. The Buttonned Interface
The buttoned user interface has scrollbars along the left and the bottom edges. Here's what they do:
Vertical Scrollbar (left edge)
Similar to the standard scrollbar. Operation depends on the mouse button used:
Here-to-Top (Left)
The location where the mouse button is let up is mapped to the top of the viewer.
Top-To-Here (Right)
The top of the viewer is moved down to where the mouse button is let up.
Thumb (Middle)
The vertical range of the client area is mapped onto the vertical extent of the scrollbar. The location corresponding to where the mouse button is let up is moved horizontally to the horizontal center of the viewer.
Horizontal Scrollbar (bottom edge)
Analogous to the Vertical scrollbar: Here-To-Left, Left-To-Here, and Thumb.
3. Installation
Bringover the public part of [Cedar]<CedarChest6.0>Top>BiScrollers.DF into the working directory you wish to use it from. Invoke BiScrollers.Load.