TBQueue.mesa
Copyright Ó 1985, 1987, 1992 by Xerox Corporation. All rights reserved.
Willie-sue, April 23, 1992 2:23 pm PDT
Interface: Provides TiogaButtons that are automatically serialized
Modeled after MBQueue
DIRECTORY
Buttons USING [Button, ButtonProc],
EditSpan USING [Place],
Imager USING [Font],
Menus USING [MenuEntry, MenuProc],
Rope USING [ROPE],
TiogaButtons USING [TiogaButtonProc, TiogaButton],
TiogaOps USING [Ref],
ViewerClasses USING [ClickProc, MouseButton, Viewer, ViewerRec];
Create:
PROC [pushModel:
BOOL ¬
TRUE]
RETURNS [Queue];
Creates a queue, a context in which mouse buttons are serialized. All menu item and
mouse button procs defined in the context of this queue will be strictly serialized, i.e.
the procs will be called in the order that the user clicked, and each proc will completely
finish execution before the next one starts.
If pushModel = FALSE, then actions are to be removed from the queue by a client process,
using DequeueAction (below), rather than by this package.
The client process should be prepared to handle ABORTED.
CreateTiogaButton:
PROC [
q: Queue,
viewer: ViewerClasses.Viewer,
rope:
ROPE ¬
NIL,
format:
ROPE ¬
NIL,
looks:
ROPE ¬
NIL,
proc: TiogaButtons.TiogaButtonProc,
clientData:
REF
ANY ¬
NIL,
fork:
BOOL ¬
TRUE,
paint:
BOOL ¬
TRUE,
immediate:
BOOL ¬
FALSE
]
RETURNS [TiogaButtons.TiogaButton];
Identical to TiogaButtons.CreateButton, except for the first argument q. Defines a button that
is interpreted in the context of q.
CreateTiogaButtonFromNode:
PROC [
q: Queue,
node: TiogaOps.Ref,
start:
INT ¬ 0,
end:
INT ¬
INT.
LAST,
proc: TiogaButtons.TiogaButtonProc ¬
NIL,
clientData:
REF
ANY ¬
NIL,
fork:
BOOL ¬
TRUE,
immediate:
BOOL ¬
FALSE
]
RETURNS [TiogaButtons.TiogaButton];
... creates a button from the node and the offsets provided. If the start and end offsets are defaulted then the button refers to the node itself.
If proc is NIL then the a button record returned, but no button property will be applied to the node. Why bother?
AppendToTiogaButton:
PROC [
q: Queue,
button: TiogaButtons.TiogaButton,
rope:
ROPE ¬
NIL,
looks:
ROPE ¬
NIL,
proc: TiogaButtons.TiogaButtonProc ¬
NIL,
clientData:
REF
ANY ¬
NIL,
fork:
BOOL ¬
TRUE,
immediate:
BOOL ¬
FALSE
]
RETURNS [TiogaButtons.TiogaButton];
... appends the formatted rope to an existing button and creates a new button for the appended text.
If proc is NIL then the rope is appended and a button record returned, but no button property will be applied to the node. This is useful for providing labels, spacing between buttons, or special formatting. Note that the format is set only when you create a node.
A curious feature of appending to a button created with proc nonNIL: that button will be for the entire node and will subsume any appended buttons. This might be useful for providing a target that will refer to the entire node contents. The feedback looks neat!
CreateTiogaButtonAtNode:
PROC [
q: TBQueue.Queue,
viewer: ViewerClasses.Viewer,
oldButton: TiogaButtons.TiogaButton ¬
NIL,
where: EditSpan.Place ¬ before,
rope: Rope.
ROPE ¬
NIL,
format: Rope.
ROPE ¬
NIL,
looks: Rope.
ROPE ¬
NIL,
proc: TiogaButtons.TiogaButtonProc,
clientData:
REF
ANY ¬
NIL,
fork:
BOOL ¬
TRUE,
paint:
BOOL ¬
TRUE,
immediate:
BOOL ¬
FALSE
]
RETURNS [TiogaButtons.TiogaButton];
Identical to TiogaButtons.CreateButton, except for the first argument q. Defines a button that
is interpreted in the context of q.
CreateMenuEntry:
PROC [
q: Queue,
name: Rope.
ROPE,
proc: Menus.MenuProc,
clientData:
REF ¬
NIL,
documentation:
REF ¬
NIL,
guarded:
BOOL ¬
FALSE,
immediate:
BOOL ¬
FALSE
]
RETURNS [Menus.MenuEntry];
Similar to Menus.CreateEntry, except for the q and immediate arguments. Defines a menu item that is interpreted in the context of q. If immediate, then the queue entry is placed on the front of the queue, rather than the tail.
CreateButton:
PROC [
q: Queue,
info: ViewerClasses.ViewerRec ¬ [],
proc: Buttons.ButtonProc,
clientData:
REF ¬
NIL,
font: Imager.Font ¬
NIL,
documentation:
REF ¬
NIL,
guarded:
BOOL ¬
FALSE,
paint:
BOOL ¬
TRUE,
immediate:
BOOL ¬
FALSE
]
RETURNS [Buttons.Button];
Similar to Buttons.Create, except for the q and immediate arguments. Defines a button that is interpreted in the context of q. If immediate, then the queue entry is placed on the front of the queue, rather than the tail.
QueueClientAction:
PROC [q: Queue, proc:
PROC [
REF], data:
REF, immediate:
BOOL ¬
FALSE];
Allows client to queue actions other than the tiogaButton button clicks, which are user-initiated. The client's proc will be called after any user clicks before the call, and before any user clicks after the call. If immediate, then the event is placed on the front of the queue, rather than the tail.
Action:
TYPE =
RECORD [
SELECT type: *
FROM
client => [
proc: PROC [REF],
data: REF
],
tbUser => [
proc: TiogaButtons.TiogaButtonProc,
button: TiogaButtons.TiogaButton, clientData: REF,
mouseButton: ViewerClasses.MouseButton, shift, control: BOOL
],
mbUser => [
proc: ViewerClasses.ClickProc,
parent: ViewerClasses.Viewer, clientData: REF,
mouseButton: ViewerClasses.MouseButton, shift, control: BOOL
]
ENDCASE
];
DequeueAction:
PROC [q: Queue]
RETURNS [Action];
Waits for an action to appear, then returns it.
Called only for "pull model" queues.
Flush:
PROC [q: Queue, abort:
BOOL ¬
FALSE];
Flushes all pending button presses and menu selections in the context of q. This procedure can be called, e.g., when some illegal actions suggests the user is confused an further mouse-ahead should be ignored. If abort and the Queue was created with pushModel = TRUE, then the notifier will be aborted.
FlushWithCallback:
PROC [q: Queue, proc:
PROC [Action] ¬
NIL, abort:
BOOL ¬
FALSE];
Like Flush, but applies proc to each action being flushed.