--FILE: ViewRec.Doc
Last Edited by: Spreitzer, February 15, 1983 11:58 am
ViewRec Documentation
Introduction
ViewRec provides a quick and dirty way to make user interfaces. It mainly consists of a procedure which puts up a Record Viewer on a given TypedVariable (which must be a record). Using some RTTypes wizardry, ViewRec provides procedures which acquire the necessary TypedVariable from either a Defs Module name, or a REF to a record. All of the components of the record which are "simple enough" are displayed, and may be invoked (if they are PROCEDURES) or edited (if they are not). Arguments are retained from one invocation to the next, and results are displayed. The displayed values are continuously kept up to date by a background process.
The User Interfaced Provided by ViewRec
Format of a Record Viewer
A Viewer produced by ViewRec has the following parts (any of which may, almost independently, be empty):
Label: A descriptive string.
OtherStuff: A place for random things. Used by ViewRec in the embedded Record Viewer on an argument record of a procedure (see below). Also available to the Client.
Body: A set of Components, where each Component is either a Name-Value Pair, or a Procedure.
Name-Value Pair:
A Name-Value Pair has a Buttons.Button containing the Name and a colon, and some kind of Viewer containing the Value. Some Components may not be edited by the user. In this case, the Name Buttons.Button displays Black On Grey, instead of the normal Black On White.
Procedure:
A Buttons.Button with the name of the PROCEDURE.
Procedure Arguments And Results: This is where the arguments to a PROCEDURE may be prepared, and where the results are viewed. The arguments and results of only one procedure at a time appear here. The PROCEDURE whose Arguments and Results are displayed here, if any, has it's Button's display style set to Black on Grey, instead of the normal Black on White. This region may contain a Record Viewer on an instance of the argument type of the PROCEDURE, above a Record Viewer on an instance of the result type of the PROCEDURE. If either the argument type or the result type is empty, the corresponding Record Viewer will not be present. In the OtherStuff region of the argument Record Viewer, there is a Buttons.Button for invoking the PROCEDURE. Also, there is a field that tells whether the PROCEDURE is currently executing, and whether or not it was last called with the arguments as they currently appear. The encoding is as follows:
"working":
The PROCEDURE has been called, but has not yet RETURNed. The arguments have not been edited since it was called.
"workin on old":
The PROCEDURE has been called, and has not yet RETURNed. The arguments have been edited since it was called.
"done":
The PROCEDURE has been called, and has RETURNed. The arguments have not been edited since it was called.
"aborted":
The PROCEDURE has been called, and raised the SIGNAL ABORTED, which ViewRec caught (using BugBane to ABORT from an uncaught SIGNAL is one way to get this behavior). The arguments have not been edited since it was called.
"":
All other cases.
FeedBack Window: This is a Tioga Viewer, used to say things to the User.
How a Record Viewer interacts
Each Record Viewer has at most two things happening at one time. Each Record Viewer has at most one PROCEDURE in it's record executing. At most one component among all the records being subjected to ViewRec is being edited.
The component which is being edited is said to be opened, and it's Name is displayed White On Black, instead of the normal Black on White. When any of the Buttons.Buttons in any Record Viewer is clicked, if there is an opened component, ViewRec first closes it, before doing whatever else the Buttons.Button would do. To close it means to parse the string in the Value Viewer. If the parse is successful, that component is updated to the value from the parse. If the parse is not successful, the user is given a short description of the TYPE of that component.
Clicking any Buttons.Button with the Control key, but no Shift key, held down will cause to be said a short description of what the kinds other mouse clicks will do. If the Record Viewer in which something is said has a FeedBack Window, that is where the message is displayed. If the Record Viewer does not have a FeedBack Window, but is embedded in another Record Viewer, it recursively looks there. The Viewers Message Window is used if no FeedBack Window is found.
Clicking a Procedure Component will have one of two different effects, depending on whether the Procedure has any arguments. If it doesn't, then it is invoked, and it's Results, if any, are displayed. If it does, that Procedure's Arguments and Results are displayed. In the OtherStuff region of the Arguments Record Viewer there is a Buttons.Button that is used for invoking the PROCEDURE. While the PROCEDURE is executing, the Procedure Buttons.Button will be displayed White on Black, instead of the usual Black On White.
Clicking a Name with both the Control and a Shift key down will cause to be said a description of the TYPE of it's Value.
Clicking a Name without the Control key down initiates editing of it's Value. There are three different ways of editing, selected according to which mouse button was clicked:
Red (the leftmost, or top, mouse button):
This opens the Value Viewer for user edits (Value Viewers normally do not allow user editing of the text therein). The contents of the Value Viewer will not be parsed until the next ViewRec Buttons.Button is clicked, or until certain keystrokes are made in the Value Viewer (which is a Tioga text editing viewer). The keystrokes are:
Control Shift Next: Give Up
No attempt to parse the characters in the Value Viewer is made, and the component is not updated. A character representation of the value of the component is put in the Value Viewer. The message "OK, I give up!" is said.
Control NotShifted Next: Close
This component is closed.
NotControl NotShifted Next: Go To Next
This component is closed, and then the next component is opened. This is equivalent to NotControl Red clicking the next component's Name. The next component is the next editable one in a left-to-right top-to-bottom traversal of the outermost RecordViewer containing this component. If there is no next component (i.e. this component is the last one in the traversal), instead of opening it, the message "Ran off end!" is said.
NotControl Shift Next: Go To Previous
This is like Go To Next, except it traverses in the opposite direction.
NotControl NotShifted Return: Close
Just like Control NotShifted Next.
Control NotShifted Return: Doit
This component is closed, and the doit procedure of the enclosing RecordViewer is invoked. Every RecordViewer has at most one doit procedure associated with it. This association is made by the client at create time. An important example is the Arguments RecordViewer used for a procedure; its doit procedure invokes that procedure.
Yellow (middle):
This causes the current Tioga Selection to be used as the candidate string. It will be parsed, and if successful, the component value will be updated. If unsuccessful, the User will be told something about the desired TYPE.
Blue (rightmost, or bottom):
This is available only for values of Enumerated TYPEs. The next, or previous, value in the enumeration will be used, depending on whether or not a Shift key is held down.
The Client Interface to ViewRec
This is incomplete. Informative examples can be found in ViewRecExampleClient.Mesa, and in the implementation of ViewRec.ViewSelf in ViewRecOther.Mesa. For more information, see the implementor.
Simple Enough:
A component of a record is Simple Enough relative to a BindingList if it either:
Is bound in the BindingList, or
Is of any one of the built-in Numeric TYPES, or
Is of any Enumerated TYPE, or
Is a Rope.ROPE, or
Is a record (but not a variant record), all of whose components are Simple Enough relative to the record's sublist in the BindingList, or
Is a PROCEDURE, whose argument record is Simple Enough relative to its sublist in the BindingList.