EBEditors.mesa
Copyright Ó 1988, 1989, 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Goodisman, August 2, 1989 9:39:50 pm PDT
Bier, October 23, 1991 12:37 pm PDT
Kenneth A. Pier, October 30, 1990 2:17 pm PST
Doug Wyatt, April 15, 1992 3:28 pm PDT
Contents: Editors' interface to EmbeddedButtons, a framework for adding standardized behaviors to any application that is willing to support a set of button objects and to implement the behavior access routines.
DIRECTORY
EBTypes, EmbeddedButtons, Rope, ScreenCoordsTypes, TIPTypes, ViewerClasses;
EBEditors:
CEDAR
DEFINITIONS =
BEGIN
ActiveButton: TYPE = EBTypes.ActiveButton;
ActiveDoc: TYPE = EBTypes.ActiveDoc;
Event: TYPE = EBTypes.Event;
ButtonInfo: TYPE = EBTypes.ButtonInfo;
EachButtonProc: TYPE = EmbeddedButtons.EachButtonProc;
ROPE: TYPE = Rope.ROPE;
Viewer: TYPE = ViewerClasses.Viewer;
A an editor that wishes to support active documents using this package must be willing to:
(1) associate a data structure, called the ButtonData property with each object that is to have button behavior, and store a textual representation of the ButtonData property when the document is stored on disk.
(2) pass input events to the HandleEvent routine, if the mouse is over a button object.
(3) implement the routines described in ActiveDocClass below, and allocate an ActiveDoc record for each document that is to be active, using the CreateActiveDoc routine.
The editor should call ButtonDataFromRope when filing in each button and ButtonDataToRope when filing out each button.
If the button's state is changed (e.g. buttons with values may go from FALSE to TRUE), then the ButtonData property is changed, and the document becomes edited.
Routines Implemented by Participating Editors
CreateActiveDoc:
PROC [theDoc:
REF, docClass: ActiveDocClass]
RETURNS [theActiveDoc: ActiveDoc];
Builds an ActiveDocObj for this doc and creates an empty name table.
FeedbackToEditor:
PROC [feedback:
REF, buttonInfo: ButtonInfo]
RETURNS [
REF];
Convenience routine. Calls the FeedbackProc of the editor to which "button" belongs.
ActionToEditor:
PROC [action:
LIST
OF
REF, buttonInfo: ButtonInfo, feedbackEvent:
LIST
OF
REF];
Action is a right-hand-side of a feedback clause, such as (BeginButton <GetValue> ApplyLook EndButton) or ((BeginButton) (<AsText <GetValue>> FillColorFromSelectedName) (EndButton)). Evaluate the <> expressions and repeatedly call EBEditors.FeedbackToEditor on each list of atoms. In our first example, FeedbackToEditor should be called once. In our second example, three times.
ActiveDocClass: TYPE = REF ActiveDocClassObj;
ActiveDocClassObj:
TYPE =
RECORD [
name: ATOM,
getRef: GetRefProc,
setRef: SetRefProc,
mapRef: MapRefProc,
feedback: FeedbackProc,
inButton: InButtonProc,
getText: GetTextProc,
getDocName: GetDocNameProc,
lookupActiveDoc: LookUpActiveDocProc
];
GetRefProc:
TYPE =
PROC [key:
ATOM, button: ActiveButton, doc: ActiveDoc]
RETURNS [ref:
REF];
Get the property, whose name is "key" that is stored with "button" in "doc". Return NIL if key not found.
SetRefProc:
TYPE =
PROC [key:
ATOM, button: ActiveButton, doc: ActiveDoc, ref:
REF, edited:
BOOL];
Set the property, whose name is "key" that is stored with "button" in "doc". If edited = FALSE the editor should not consider the document edited, even though this property has been set.
MapRefProc:
TYPE =
PROC [doc: ActiveDoc, mapProc: EachButtonProc]
RETURNS [aborted:
BOOL ¬
FALSE];
Applies mapProc to each button in doc. Aborted is TRUE if any of the mapProc's returned done=TRUE.
FeedbackProc:
TYPE =
PROC [button: ActiveButton, doc: ActiveDoc, feedback:
REF]
RETURNS [
REF];
The editor should perform the events described by "feedback". If passed a rope as feedback, the editor should return a parsed, runtime version of the feedback.
At present, feedback will be a LIST OF REF ANY or a LIST OF LIST OF REF ANY, where this structure results from running each feedback token in the Poppy language through IO.GetCedarToken, and building lists of the resulting ROPEs, REF INTs, ATOMS, and REF BOOLS, as suggested by the parentheses.
InButtonProc:
TYPE =
PROC [button: ActiveButton, doc: ActiveDoc, x, y:
INTEGER]
RETURNS [
BOOL];
Returns TRUE if the given [x, y] pair (in document client coordinates) is inside the button and false otherwise.
GetTextProc:
TYPE =
PROC [button: ActiveButton, doc: ActiveDoc]
RETURNS [text:
ROPE];
If the button is a textual document element, return the contents of the button as an ASCII string (throwing away any formatting). If the button is not a textual document element, return NIL.
GetDocNameProc:
TYPE =
PROC [doc: ActiveDoc]
RETURNS [name:
ROPE];
Returns the name of the doc. Often a filename or window name.
LookUpActiveDocProc:
TYPE =
PROC [viewer: Viewer]
RETURNS [doc: ActiveDoc];
Returns the active document that is associated with this viewer.
Routines Called by Participating Editors
GetEvent:
PROC [input:
LIST
OF
REF]
RETURNS [Event];
try to interpret input as a raw event from a transparent TIP table
ValidEvent:
PROC [Event]
RETURNS [
BOOL];
is this this a valid event?
MouseAction:
PROC [Event]
RETURNS [
BOOL];
is this a mouse action?
MouseAllUp:
PROC [Event]
RETURNS [
BOOL];
are all the mouse buttons up?
MousePosition:
TYPE ~ ScreenCoordsTypes.TIPScreenCoordsRec;
MouseCoords:
PROC [Event]
RETURNS [MousePosition];
what is the current mouse position?
HandleEvent:
PROC [event: Event, button: ActiveButton, doc: ActiveDoc];
The editor should call this whenever it receives an event that should go to a button.
EmbeddedButtons will cause button feedback according to the type of event.
Passes the event to a button-class specific handling routine.
ParseEvent:
PROC [TIPTypes.TIPTable, Event]
RETURNS [
LIST
OF
REF];
When the editor decides that an event does not go to a button, it should call this to process the event itself with its own TIP table.
ButtonDataFromRope:
PROC [rope:
ROPE, instantiateNow:
BOOL ¬
FALSE, button: ActiveButton ¬
NIL, doc: ActiveDoc ¬
NIL]
RETURNS [val:
REF];
The ButtonData property is converted from ROPEs to internal structures. Useful at file-in time or when a button is created.
RopeFromButtonData:
PROC [val:
REF]
RETURNS [rope:
ROPE];
The ButtonData property is converted back to a ROPE. Useful at file-out time or when a button's current state is to be inspected.
END.