SimpleFeedback.mesa
Copyright Ó 1986, 1990, 1991, 1992 by Xerox Corporation. All rights reserved.
Bier, May 1, 1990 4:42 pm PDT
Pier, October 23, 1987 3:20:56 pm PDT
Last tweaked by Mike Spreitzer on May 3, 1990 6:23:50 am PDT
Michael Plass, September 27, 1991 11:00 am PDT
Contents: This package is intended to be used widely within the Cedar environment to send messages to the user, in the form of ROPEs. Because it depends only IO and Rope, it can be called by low-level Cedar packages. See also Feedback.mesa for more advanced versions of these routines.
DIRECTORY IO, Rope;
SimpleFeedback: CEDAR DEFINITIONS = BEGIN
Introduction
SimpleFeedback can be used to send a text message to a named place, called a router. By default, each router sends its messages to an appropriate output area. For instance, in Cedar with Viewers, messages go by default to the MessageWindow and to a system typescript. To redirect the output of a given named router, applications can use other interfaces, such as Feedback.mesa. However, many applications will only need to call this interface, making use of the default output areas.
Here is an example of how this SimpleFeedback might be used. The Tioga text editor might name its router $Tioga. It might inform the user of errors by calling
Append[$Tioga, oneLiner, $Error, "Something has gone wrong"]
or it might give the user feedback during a copy operation by calling
Append[$Tioga, oneLiner, $Prompt, "Select for copy to caret"].
A given router can be programmed to send different classes of message (such as $Error and $Prompt in this example) to different places. For instance, $Error messages might go to a Typescript and to the MessageWindow, causing it to blink, while $Prompt messages might go only to the MessageWindow and not cause it to blink. Feedback.mesa explains how to customize routers in this way.
A message may need to be written in several pieces. For instance,
Storing file ... almost done ... done.
This can be done using the begin, middle, and end MsgTypes. For instance:
Append[$MyApplication, begin, $FileFeedback, "Storing file ... "];
Append[$MyApplication, middle, $FileFeedback, "almost done ... "];
Append[$MyApplication, end, $FileFeedback, "done."];
Advanced Topices
An application with multiple windows may have one output region per window (such as the Feedback line in each Gargoyle window). Such applications need a router per window rather than a router for the whole application. See Feedback.CreateRouter, Feedback.Append and other routines in Feedback.mesa for such applications.
Also see Feedback.mesa for ways to customize router output, to examine the current state of a router, and to enumerate the currently active routers.
Types and Routines
MsgType:
TYPE = {oneLiner, begin, middle, end};
A router automatically separates a "oneLiner" or "begin" message from the previous message. A router automatically separates a "oneLiner" or "end" message from the following message.
MsgClass:
TYPE ~
ATOM;
Clients may direct output for each (router, msgClass) pair independently.
Output to (router, msgClass) goes:
1. to the place the client has explicitly indicated output to that pair should go, or, in the absence of such explicit direction,
2. to the default place for that router, if the client has indicated one, otherwise
3. to the global default, which is always reasonable.
Clients can specify the pair destination and router default using the Feedback interface. The MsgClasses $Default and $Every are reserved for those control functions; clients do not normally output to those MsgClasses, and there is no guarantee about what happens if a client should try to.
Append:
PROC [routerName:
ATOM, msgType: MsgType, msgClass: MsgClass, msg: Rope.
ROPE];
Send "msg" to the named router. If no such router existed previously, one will be created automatically. "msgType" helps Append to format the message on a variety of devices by telling it when a message begins and ends (see MsgType above). "msgClass" and "routerName" together determine where and how this message will be displayed (see MsgClass above).
PutFL:
PROC [routerName:
ATOM, msgType: MsgType, msgClass: MsgClass, format: Rope.
ROPE ¬
NIL, list:
LIST
OF
IO.Value ¬
NIL ];
Like Append, but uses IO.PutFLR to format the message. Some routers may support the %l conversion specification and other ways of sneaking Tioga formatting through.
PutF:
PROC [routerName:
ATOM, msgType: MsgType, msgClass: MsgClass, format: Rope.
ROPE ¬
NIL, v1:
IO.Value ]
Common case of PutFL
~ INLINE { PutFL[routerName, msgType, msgClass, format, LIST[v1]] };
Blink:
PROC [routerName:
ATOM, msgClass: MsgClass];
Call attention to the named router, hopefully in an emphatic, non-textual way.
ClearHerald:
PROC [routerName:
ATOM, msgClass: MsgClass];
For output devices (such as Labels.Label in Cedar Viewers) that display only one "line" of text, clear that line. This makes the most sense between the end of one message and the beginning of the next; no guarantees about what happens if called under other circumstances.
SetRouterOn:
PROC [routerName:
ATOM, on:
BOOL];
Allows all output to be temporarily disabled or enabled without forgetting which handlers the router is currently attached to. Operations on disabled routers are no-ops.
GetRouterOn:
PROC [routerName:
ATOM]
RETURNS [on:
BOOL];
Returns the current value of the "on" parameter.
END.