[Cyan]<PreISLCedar>Viewers>ViewerClasses.mesa!2

ViewerClasses.mesa; Written by S. McGregor

Last Edited by: McGregor, July 21, 1983 10:41 am

Last Edited by: Maxwell, January 3, 1983 2:14 pm

Last Edited by: Pausch, August 17, 1983 10:06 am

Last Edited by: Wyatt, October 27, 1983 11:10 am

DIRECTORY

Atom USING [PropList],

Cursors USING [CursorType],

Icons USING [IconFlavor],

Imager USING [Context],

Rope USING [ROPE],

TIPUser USING [TIPTable];

ViewerClasses: CEDAR DEFINITIONS

= BEGIN

Viewer: TYPE = REF ViewerRec;

Instance data for a viewer; Due to some compiler defaulting problems, please act as if the * entries were PRIVATE and ** entries READONLY

ViewerRec: TYPE = MACHINE DEPENDENT RECORD [ -- 36 words

wx, wy: INTEGER ← 0, -- position of viewer frame wrt parent's client space

ww, wh: INTEGER ← 0, -- size of the viewer on the screen

cx, cy: INTEGER ← 0, -- viewer client position wrt parent **

cw, ch: INTEGER ← 0, -- size of usable space wrt client **

lock: Lock ← [NIL, 0], -- locking information used by ViewerLocks * **

tipTable: TIPUser.TIPTable ← NIL, -- mouse and keyboard events, initialized from class

file: Rope.ROPE ← NIL, -- backing file name (optional)

menus: REF ← NIL, -- narrows to MenusPrivate.ViewerMenus * **

icon: Icons.IconFlavor ← unInit, -- picture to display when small, initialized from class

column: Column ← left, -- screen space algorithm used when viewer is open

scrollable: BOOL ← TRUE, -- optional scroll bar allocation

hscrollable: BOOL ← FALSE, -- optional horizontal scroll bar allocation

iconic: BOOL ← TRUE, -- small or large representation on screen

border: BOOL ← TRUE, -- WMgr paints a one dot black border around viewer

newVersion: BOOL ← FALSE, -- hint that the user has made new edits **

newFile: BOOL ← FALSE, -- hint that a backing file does not yet exist **

visible: BOOL ← TRUE, -- WMgr maintained hint for repaint use * **

offDeskTop: BOOL ← FALSE, -- is viewer off of the current desktop? **

destroyed: BOOL ← FALSE, -- hint that viewer has been flushed from window tree **

init: BOOL ← FALSE, -- init proc call has been completed after creation * **

saveInProgress: BOOL ← FALSE, -- the saveProc has been called but not yet returned **

inhibitDestroy: BOOL ← FALSE, -- if TRUE then window menu will not permit destroy

guardDestroy: BOOL ← FALSE, -- if TRUE then window menu will always guard destroy

clientContext: BOOL ← FALSE, -- hint that client has installed a context for this viewer * **

link: Viewer ← NIL, -- ring of linked viewers **

position: INTEGER ← 0, -- for window positioning primitives use * **

openHeight: INTEGER ← 0, -- "ideal" height hint for open viewer

parent: Viewer ← NIL, -- NIL if top level viewer **

sibling: Viewer ← NIL, -- sibling chain **

child: Viewer ← NIL, -- head of children chain **

props: Atom.PropList ← NIL, -- clients can associate properties with viewers **

data: REF ANY ← NIL -- data slot for Viewer Class implementor

];

wxmin: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.wx] };

wymin: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.wy] };

wxmax: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.wx+self.ww] };

wymax: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.wy+self.wh] };

cxmin: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.cx] };

cymin: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.cy] };

cxmax: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.cx+self.cw] };

cymax: PROC[self: Viewer] RETURNS[INTEGER] = INLINE { RETURN[self.cy+self.ch] };

Class data for a viewer:

ViewerClass: TYPE = REF ViewerClassRec;

ViewerClassRec: TYPE = RECORD [

flavor: ViewerFlavor ← NIL, -- name of viewer's class

parent: ViewerClass ← NIL, -- super-class, if any

notify: NotifyProc ← NIL, -- TIP input events parsed from tipTable

paint: PaintProc ← NIL, -- called whenever the Viewer should repaint its contents

modify: ModifyProc ← NIL, -- reports InputFocus changes

destroy: DestroyProc ← NIL, -- called before Viewer structures freed on destroy

copy: CopyProc ← NIL, -- copy data to new Viewer

set: SetProc ← NIL, -- set the viewer contents

get: GetProc ← NIL, -- get the viewer contents

init: InitProc ← NIL, -- called on creation or reset to init client data

save: SaveProc ← NIL, -- requests client to write contents to disk

scroll: ScrollProc ← NIL, -- (vertical) document scrolling

hscroll: HScrollProc ← NIL, -- horizontal scrolling

caption: CaptionProc ← NIL, -- experimental proc for user caption display

menus: LIST OF ATOM ← NIL, -- registered menus to automatically add to the viewer

tipTable: TIPUser.TIPTable ← NIL, -- table to parse mouse & keyboard events

clipChildren: BOOL ← FALSE, -- clip out children during repaint

simpleCreate: BOOL ← FALSE, -- simple creation of new instances (see below)

bltContents: BltRule ← none, -- use blt to copy screen contents (see comment below)

paintRectangles: BOOL ← FALSE, -- keep hints for the paintProc; see comment below

icon: Icons.IconFlavor ← document, -- picture to display when small

cursor: Cursors.CursorType ← textPointer -- standard cursor when mouse is in viewer

];

The bltContents rule in the class requests that the window package attempt to save some of the current screen contents of a viewer by moving the bits to the new viewer location (e.g. when the viewer is moved). Rectangles thus saved will show up as a PaintRectangle with flavor=blt, as a convenience to clients that keep caches of screen contents. It does not make sense to enable this feature without also setting the paintRectangles bit. Clients that scale an image to fit the viewer bounding box should not use this feature.

The paintRectangles bit in the class determines whether or not the window manager will pass a PaintRectangle (as the whatChanged parameter) to the viewer when the paintProc is called. These rectangles may be used by the client to optimize painting. If NIL, then the client must assume the entire viewer is invalid. If a PaintRectangle is seen by a paintProc, then it can safely assume that it need paint only those areas with flavor=invalid.

The simpleCreate bit in the class implies that a new instances of this class can be constructed just with ViewerOps.CreateViewer[$ClassFlavor, info: [name: instanceName]].

BltRule: TYPE = { none, top, center, bottom } ;

PaintRectangleFlavor: TYPE = { invalid, blt } ;

PaintRectangle: TYPE = REF PaintRectangleRec;

PaintRectangleRec: TYPE = RECORD [

flavor: PaintRectangleFlavor ← invalid,

x, y, w, h: INTEGER ← 0

];

If flavor=invalid, the area inside the rectangle needs to be repainted.

If flavor=blt, the area inside the rectangle has already been painted by a blt.

xmin: PROC[self: PaintRectangle] RETURNS[INTEGER] = INLINE { RETURN[self.x] };

ymin: PROC[self: PaintRectangle] RETURNS[INTEGER] = INLINE { RETURN[self.y] };

xmax: PROC[self: PaintRectangle] RETURNS[INTEGER] = INLINE { RETURN[self.x+self.w] };

ymax: PROC[self: PaintRectangle] RETURNS[INTEGER] = INLINE { RETURN[self.y+self.h] };

ViewerFlavor: TYPE = ATOM ;

ViewerFlavors predefined by the Viewer package include: $Label, $MessageWindow, $Button, $Container, $Rule. Tioga implements $Text and $Typescript.

Lock: TYPE = RECORD [ -- process-reentrant viewer lock

process: UNSAFE PROCESS ← NIL, -- current write process

] ;

Column: TYPE = {static, left, right, color} ;

Static documents, such as the message window, may not be open/closed

PaintProc: TYPE = PROC [self: Viewer, context: Imager.Context, whatChanged: REF ANY,

clear: BOOL] ;

Called by the window manager when the client should repaint the data on the screen. The context is clipped to the client screen area. whatChanged is just passed from the call to ViewerOps.PaintViewer, but will be NIL when the window manager requires a full repaint after moving a viewer on the screen (unless self.class.paintRectangles is set; see above). clear is a hint that the client background is white, so that the client can paint on the black bits if it so chooses.

NotifyProc: TYPE = PROC [self: Viewer, input: LIST OF REF ANY] ;

Input events from the class TIPTable. Mouse events get passed whenever the mouse is over the viewer, keyboard events get passed if the viewer owns the input focus (see the InputFocus interface). N.B. Called at Process.priorityForeground!

ModifyProc: TYPE = PROC [self: Viewer, change: ModifyAction] ;

ModifyAction: TYPE = {set, push, pop, kill};

Called when the input focus ownership is changing so that the client can modify things like selection feedback on the screen or private data structures and state.

DestroyProc: TYPE = PROC [self: Viewer] ;

Called when the viewer has been destroyed for some reason.

CopyProc: TYPE = PROC [self, new: Viewer] ;

Copy implementor private data structures.

The op atom for SetProc and GetProc is for private client agreements to get things like selection contents or content representations other than ropes.

SetProc: TYPE = PROC [self: Viewer, data: REF ANY, finalise: BOOL ← TRUE, op: ATOM ← NIL] ;

GetProc: TYPE = PROC [self: Viewer, op: ATOM ← NIL] RETURNS [data: REF ANY] ;

InitProc: TYPE = PROC [self: Viewer] ;

Called by the window manager shortly after a viewer is created so that the client can create and initialize private data structures. Also called on the "Reset" menu command.

SaveProc: TYPE = PROC [self: Viewer, force: BOOL ← FALSE] RETURNS[ok: BOOL];

Requests client to save data structures on the disk. force should only be true when called from the emergency backup code on error recovery and requests that the client consider overriding monitors or locks that might otherwise prevent saving the data. If the save failed, the client should return ok=FALSE (example: trying to save a No Name viewer).

ScrollProc: TYPE = PROC [self: Viewer, op: ScrollOp, amount: INTEGER,

shift, control: BOOL ← FALSE] RETURNS [top, bottom: INTEGER ← LAST [INTEGER]] ;

ScrollOp: TYPE = {query, up, down, thumb};

Client scrolling and scrolling feedback. If op is 'query' the client should return the percentage of the scrollable document at the top and bottom of the screen, or default if unknown. If op is 'up' or 'down' then amount is number of pixels to glitch. If op is 'thumb' then amount is percentage into document to scroll. The shift and control information reflects the state of the shift and control keys during the up, down, and thumb ops and may be interpreted by the client as desired.

HScrollProc: TYPE = PROC [self: Viewer, op: HScrollOp, amount: INTEGER,

shift, control: BOOL ← FALSE] RETURNS [left, right: INTEGER ← LAST [INTEGER]] ;

HScrollOp: TYPE = {query, left, right, thumb};

Client horizontal scrolling and scrolling feedback. If op is 'query' the client should return the percentage of the scrollable document at the left and right of the screen, or default if unknown. If op is 'left' or 'right' then amount is number of pixels to glitch. If op is 'thumb' then amount is percentage into document to scroll. The shift and control information reflects the state of the shift and control keys during the left, right, and thumb ops and may be interpreted by the client as desired.

CaptionProc: TYPE = PROC [self: Viewer, context: Imager.Context] ;

Experimental: allows client to draw caption legend.

END.