BiScrollersDoc.tioga
Last edited by Spreitzer, March 30, 1985 2:20:23 pm PST
BiScrollers
CEDAR 5.2 — 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 coordinate system of the given Graphics.Context is the 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 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.
1.3. BetterBridge
This is a fix to ImagerBridge.SetViewFromGraphicsContext. This is needed because ImagerBridge.SetViewFromGraphicsContext doesn't work right if the coordinate system of the Graphics.Context does not match that of the Viewer (which is in general the case when using BiScrollers).
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 (rotation is not available through the buttonless interface).
2.1. Common Stuff
All BiScrollers have a menu containing buttons for standard operations:
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. 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.
ResetAndCenter
Scale and rotation are reset. The image is then centered.
Center
The center of the client data is aligned with the center of the viewer.
Vanilla
The entire transformation is reset.
Left
The left edge of the client area is aligned with the left edge of the viewer.
Right
Top
Bottom
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 [Indigo]<CedarHacks5.2>Top>BiScrollers.DF into the working directory you wish to use it from. Invoke BiScrollers.Load.