ViewRec is a Cedar tool that provides a quick and easy way to make user interfaces. It includes a procedure which puts up a viewer, called a RecordViewer, on a given aggregate (a record, sequence, or array). ViewRec can access aggregates through refs to records, and through names of interfaces. All of the components of the aggregate that 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 may be continuously kept up to date by a background process.

The documentation on ViewRec comes in two pieces: an introduction (ViewRecIntroduction.Tioga), and this reference manual (ViewRecDoc.Tioga). The introduction gives a quick description of the essential features of ViewRec. This reference manual gives a detailed description of everything. Read the introduction first; it won't take long, and it provides an overview. This reference manual dives straight into all the gory details. They are divided into two groups. Those in the first describe the interfaces produced by ViewRec. Those in the second describe how to get ViewRec to produce such interfaces.

This document assumes a general familiarity with Cedar. The first section, on the interfaces produced by ViewRec, references concepts from the Cedar user environment (screen, keyboard, and mouse; Viewers). The second, on programming ViewRec, is intended for those familiar with the Cedar programming environment. The packages most relevant to ViewRec are Viewers and the Abstract Machine. Simple usage of ViewRec requires little knowledge of either. ViewRec does, however, have options, the use of which requires deeper knowledge of one or the other.

The client area of a viewer produced by ViewRec may be divided into three main parts; they are listed below:

ViewRec places some restrictions on the concurrency of user-initiated actions. Each RecordViewer may or may not allow more than one procedure activation at one time. No RecordViewers allow more than one concurrent activation of the same procedure. At most one component among all the aggregates 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. If there is an opened component when any of the screen buttons in any RecordViewer is clicked, ViewRec closes that component before doing whatever else the button would do. To close a component means to parse the string in its value viewer. If the parse is successful, the component is updated to the value from the parse. If the parse is not successful, the user is given a message that says so and describes the type of the component.

Clicking any screen button with either Control key, but no Shift key, causes ViewRec to give a short description of what the other mouse clicks will do.

ViewRec associates with each RecordViewer is a working directory. It is expected that each application will have some way of letting the user know and manipulate that working directory.

ViewRec is simple to use: create, in any way you wish, an aggregate of the procedures and variables you want in your user interface, invoke a ViewRec create proc (ViewRef, ViewInterface, or ViewTV) on it, and you have a ready-made user interface. A number of whistles and bells have evolved, but they are just secondary attachements.

For a small, if frivolous, example, see ViewRecExampleClient.Mesa, included in the DF file.

ViewRec really uses the "Abstract Machine" (TypedVariables, Types, and so on) inside. It is (or, at least, it is intended to be) not necessary to understand AMTypes (very much) in order to use ViewRec. An effort has been made to provide a convenient set of "sugar" routines that convert from the more familiar world into the world of AMTypes; if you find a piece of sugar coating missing, complain, and it should get fixed.

TypedVariables are like POINTERs and REFs (they "point to" Cedar/Mesa values), and Types are like TYPEs. The difference is that there are ways, at runtime, to explore the structure through TypedVariables and Types, and this is why ViewRec uses them.

ViewTV is the procedure that really does it. ViewRef and ViewInterface are sugared versions for dealing with common sources of aggregate TypedVariables: refs to records, and names of definitions modules.

ViewRef passes to ViewTV a TypedVariable for the referent of the first argument (agg: REF ANY). The rest of the arguments are passed on directly.

ViewInterface passes to ViewTV an Interface Instance Record, obtained from the current memory state, for the definitions module whose name is the first argument (name: ROPE). An Interface Instance Record looks like any other record to ViewRec, and it contains as fields the variables and procedures declared in the interface. Again, the rest of the arguments are passed on directly.

ViewTV Creates a RecordViewer for the given TypedVariable. Most of the arguments can be ignored for vanilla usage; their defaults produce ordinary behavior.

ViewRec thinks of RecordViewers as a sub-class of Viewers. There are procedures to:

ViewRec also thinks of RecordViewers as a sub-class of REF ANY. Analogs of the above three functions are also provided along this relation. There are Cedar/Mesa language features intended to do this, but they don't all work in all cases (because RecordViewerRep is an opaque type). NarrowToRV is provided to fix that deficiency.

Given an instance of an aggregate type, ViewRec will decide, for each component of that aggregate, whether or not to display it. That decision can roughly be characterized as: "if the Client has told me what to do, I will obey; otherwise, if the component is simple enough, I will display it". ViewRec knows how to display numbers and enumerations (and subranges thereof), strings, procedures with "simple" arguments, and aggregates of those things.

There are two ways the Client can tell ViewRec what to do. First, it can say: "don't display the component". This is done with the BindingList argument (specs) to ViewTV. If there is a Value Binding for the component, with visible=false, the component will not be displayed. Don't be confused by the other things that Value Bindings can do as well, such as providing initial values. The switches in Value Bindings are set up to default to the commonnest case, which is making data structure linkages that you don't want the user to see.

The other way the Client can tell ViewRec what to do is to say "this is how to display the component". A Handler describes how to display the component and handle its User interactions. There is a later section that explains how to make Handlers and associate them with components.

Here is a precise statement of how ViewRec decides whether or not to display a component:

The criteria for "simple enough" are similar to those for being displayed, except that there are ways something can be simple, but not displayed. An aggregate is simple enough if and only if, for every component:

Since ViewTV can only be called on already existing aggregates, this is almost not a problem.

The problem comes in with procedure arguments. ViewRec must cons up an argument record for any procedure it is going to invoke. From the TypedVariable for the procedure it can do this. This is also where it gets initial values for that record.

In addition to that, ViewRec offers an additional complication: Value Bindings. These are effectively assignments performed in ViewTV.

ViewRec may be thought of as providing a generalization of Menus, where the procedures can take arguments. What, then, is the meaning of components that are not procedures?

One thing such components may be used for is to give some information to the user. You could think of them as showing a state variable of the user's model of your application. As such, you may not want the user to be able to directly edit that variable. This can be done with a Value Binding. Setting "editable" to FALSE makes ViewRec disallow user edits of that component.

Another use for such components could be to parameterize your application in some way. This could be accomplished with a state variable and procedure-to-set-it pair. Alternatively, ViewRec allows the Client to specify a procedure to be called whenever the user edits a component. This is done with a Notify Binding.

ViewRec will periodically review some components and update their displays if they have changed. This is done by a special process whose sole purpose in life this is. Exactly what gets reviewed, and how often the whole loop is performed, are adjustable.

There is a protocol by which a user can request, with varying degrees of urgency, that the executing procedure be aborted (see section 2.2.1.2). The procedure is responsible for occasionally checking the urgency of the user's abortion request, and taking abortive action. There is a procedure, TestAndMaybeResetUserAbort, that, given a threshold, will check whether the urgency has reached or passed that threshold. If it has, that urgency is what's returned, and the urgency is reset to 0. If it hasn't, 0 is returned, and the urgency is unchanged.

It is possible for the Client to enrich ViewRec's repertoire. A Handler determines how a given component will be displayed, and how it will interact. A Recognizer is a procedure, which, given a Type, can decide what Handler to use (it can also decide to pass, and let someone else decide). All Handlers are "guarded" by Recognizers. ViewRec has an elaborate mechanism for locating the Recognizers to apply in the right order to get a useful variety of effects. ViewRec starts out with a standard set of Recognizers, and clients may add more.

The search for the Handler for a given component is conducted by applying Recognizers in a particular order, until one of them succeeds. The order is as follows:

The last seven lists are each added to by one of three procedures:

Each of the last seven lists is maintained in a particular order, and each of the above three procedures offers (via the AddPlace argument) the option of adding to the beginning or the end of the designated list.

It can be easiest to just write one recognizer per Handler. Note that by carefully choosing which list to put it in, the task of actually deciding whether or not the Handler is appropriate can be obviated.

Handlers come in two flavors: Simple, and Complex. Simple Handlers are restricted to do the Name-Value pair style of display and interaction. Complex Handlers are less restricted.

To implement a Simple Handler, you need (almost) only provide procedures to parse and print. Here, exactly, is what you need to provide:

Complex Handlers are even simpler to describe. You need to provide only two procedures:

A RecordViewer lays itself out as follows. First, it identifies a target width. Then, for each viewer it will contain, it creates that viewer, measures its size, and places it so as not to exceed the target width (if possible). Consecutive contained viewers are placed left to right, top to bottom (as words are in English). The height of the main body is constrained by the maxEltsHeight field in the CreateOptions; if the contained viewers stretch over more vertical distance, the main body is made scrollable. Next the containers for procedure arguments and returns are dealt with. For each prepared procedure, the vertical space allotted to its arguments and returns is again limited, by createOptions.maxArgsHeight; the container will be scrollable if necessary. Next, the FeedBack viewer is added on (unless the CreateOptions say its height is to be 0, in which case it is elided). Finally, the height of the whole Viewer is set accordingly (unless it is a top-level Viewer and the height is excessive: greater than about 80% of the screen).

The target width is identified as follows. If the RecordViewer is a top level Viewer, and the viewerInit.ww given is not zero, that is taken as the target width. Otherwise, if either (1: the RecordViewer is a top level Viewer that is not iconic) or (2: the viewerInit.ww given is not zero, and the Record Viewer is embedded), the inner width of the main body of the RecordViewer (cw in its ViewerRec) just after its creation according to viewerInit is used. Otherwise, the createOptions.defaultTargetWidth is used.

Some RecordViewers (according to CreateOptions) will change their layout when the width of their containing viewer changes.

When creating a RecordViewer, the client may consider the RecordViewer to be for "forms fillout" preperatory to doing some task. For example, such is the case when ViewRec uses itself to prepare the arguments to a procedure. Here are two "reserved for future expansion" slots that can be used to signal completion of the form and readiness to do the task.

Some small examples can be found in ViewRecExampleClient.Mesa, and in the implementation of ViewRec.ViewSelf in ViewRecOther.Mesa. Also, try invoking ViewSelf and using the resulting viewer to view the Rope interface. For more information, see the implementor.