-- File: WQueue.mesa
-- extension to MBQueue.mesa, to allow Flush to take a proc to call

-- Interface: Provides Menu items and Buttons that are automatically serialized
-- Created by: Cattell and Haugeland on October 21, 1982 9:11 am
-- Last edited by:
-- Cattell on October 21, 1982 9:11 am
-- MBrown on October 21, 1982 6:22 pm
-- Last Edited by: Maxwell, December 17, 1982 10:06 am
-- Last Edited by: Willie-Sue, August 8, 1983 9:07 am

DIRECTORY
Buttons USING [Button, ButtonProc],
Menus USING [ClickProc, MenuEntry, MouseButton],
Rope USING [ROPE],
ViewerClasses USING [ViewerRec],
VFonts USING [Font, defaultFont];

WQueue: CEDAR DEFINITIONS
IMPORTS VFonts =

BEGIN

Queue: TYPE = REF QueueObj;
QueueObj: TYPE;

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.


CreateMenuEntry: PROC [
q: Queue, name: Rope.ROPE, proc: Menus.ClickProc, clientData: REF ANY ← NIL,
 documentation: REF ANY ← NIL, fork: BOOL ← TRUE, guarded: BOOL ← FALSE]
 RETURNS [Menus.MenuEntry];
 -- Identical to Menus.CreateEntry, except for the first argument q. Defines a menu item that
 -- is interpreted in the context of q.

CreateButton: PROC [
q: Queue, info: ViewerClasses.ViewerRec ← [],
proc: Buttons.ButtonProc, clientData: REF ANY ← NIL,
 fork: BOOL ← TRUE, font: VFonts.Font ← VFonts.defaultFont, documentation: REF ANY ← NIL,
 guarded: BOOL ← FALSE, paint: BOOL ← TRUE ] RETURNS [Buttons.Button];
 -- Identical to Buttons.Create, except for the first argument q. Defines a button that
 -- is interpreted in the context of q.
 
QueueClientAction: PROC [
q: Queue, proc: PROC [REF ANY], data: REF ANY];
-- Allows client to queue actions other than the menu item clicks and 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.

Action: TYPE = RECORD [
SELECT type: * FROM
client => [
proc: PROC [REF ANY],
data: REF ANY ],
user => [
proc: Menus.ClickProc,
parent: REF ANY, clientData: REF ANY,
mouseButton: Menus.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, proc: PROC[Action]← NIL];
-- 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.
-- proc will get called for each Action in the queue, to allow cleanup, NOTIFY's, etc


END.