A+ Reference: Screen Management Functions

# Screen Management Functions

Definitions of the Screen Management Functions

free
has
hide
is
of

Attributed Data

show

Dependencies and Displayed Objects

> "Introduction to Screen Management" shows all the basic primitive functions for visual representation in action, and in fact includes most forms of their definitions. This chapter gives complete details. The command $load s establishes these functions in both the root and the s contexts.

> In this chapter, an object is a symbol holding the name of a global variable or dependency. (It may also be a two-element vector of symbols naming context and variable separately, but it will be described in this chapter as a single symbol, for simplicity.) A class is a visual representation format, e.g., array or label. An attribute is a modifiable characteristic of a class such as title or bg. An object which is not bound to a display class is said to be free.

# Definitions of the Screen Management Functions

## free

Syntax

> free obj

Argument and Result

> The argument is a symbol scalar or one-element vector. The result is a one-element symbol vector or the Null.

Definition

> If the object (i.e., global variable or dependency) named in the right argument obj is bound to a class, it is unbound. In this case the result is 1Òobj. Otherwise, the function has no effect and the result is Null. If the class to which the object is bound is a container (see the function is), then all children of the object are also freed. If the object is a child of another object, it is freed but its parent is not.

## has

Syntax

> obj has rescs

Arguments and Result

> The left argument obj is a symbol scalar or one-element vector. The result is a symbol scalar.

Definition

> This function sets the attributes named in the right argument for the object (i.e., global variable or dependency) named in the left argument. The attributes can be specified in one of two general ways:

> - as a slotfiller array:
>   (`attribute1 `attribute2 ...; (value1;value2;...))

> - as an association list:
>   (`attribute1;value1; `attribute2;value2; ...).
> In addition, if all of the values to be set are symbols, then the following symbol array is also permitted:

>        `attribute1,value1,`attribute2,value2, ...

> There is an additional variation. If a dot is placed before the attribute name, as in `.attribute1, the symbol given for that attribute is not an attribute value itself, but a variable, function, or dependency whose value (at any time of use) will be used for that attribute value. A variable or function provides an "electrical connection", and a dependency does so if it is bound to the reference class (so that it is evaluated as necessary each time the interpreter traverses the mainloop); with such a connection, the display is changed to reflect the new attribute value whenever the variable or function is respecified or the dependency is invalidated. If a Null is given as a value for a dotted attribute, instead of a name, the previous attribute default variable (if any) is no longer connected to this attribute of this object; the value of the attribute does not change. (See "Attribute Default Variables".) See the examples.

> The result is ''Òobj. The expression `obj has (...;) sets the specified attribute to its default value.

> If the left argument holds a name that has no value and is not local to a function, then a free global variable with the value Null is assigned to that name - which might possibly cause a binding requested by the right argument, such as to radio, to fail.

> If the left argument (after the action just described if necessary) names a free variable or dependency and the right argument does not specify a class binding, then the variable or dependency is bound to its default display class. (In fact, because the attributes are applied sequentially, if the right argument specifies a class binding but first specifies a nonpersistent attribute, the free variable or dependency is bound first to its default display class and then to the specified class.)

Examples

>          `header has (`title `bg;
>                       ("Visual Display"; `yellow))
>                            ã Specified as a slotfiller.
>     ã (The responses, `.header and so on, are omitted here.)
>          `header has (`title;"Visual Display"; `bg;`yellow)
>                            ã Given as an association list.
>          `a has `bg `red   ã Specify actual value, a symbol so simple form is okay.
>          `bg of `a
>      `red
>          varû`blue
>          `a has `.bg `var  ã Specify a variable whose value
>                            ã   will be used, by using `.bg
>          `bg of `a         ã Get the value of the attribute.
>      `blue
>          `.bg of `a        ã Get the name of the variable
>      `var                  ã   holding the attribute's value.

## hide

Syntax

> hide obj

Argument and Result

> The argument is a one-element symbol array. The result is Null.

Definition

> Every object displayed on the screen appears in a window under the control of the window manager of the underlying system, and every window created through A+ is the result of applying the function show to some object; that object is called the root object of the window. Windows are either top-level windows or popups, a distinction that is discussed in "Windows" and "Quit, and Open and Close". If the object named in the argument obj is the root object of a top-level window, the effect of this function is to replace the window with an icon. If the object is the root object of a popup window, and the pin is out, the effect is to remove the window from the screen; there is no effect if the pin is in. If the object is a child of a layout, the effect is to remove the object from the screen (but not from the layout definition) and reconfigure the layout if necessary. Otherwise, the function has no effect.

## is

Syntax

> obj is cls

Arguments and Result

> The left argument is an array and the right argument is a symbol scalar. The result is also a symbol scalar.

Definition

> This function binds the object represented by obj to the display class named in cls. There are three cases for the left argument, depending on whether it is a global name with a value, just a name, or just a value.

> > Case 1. The left argument is a one-element symbol array naming a global variable, which may be a dependency. This is the ordinary case, and this global variable is the one that will be bound to a display class cls.

> > Case 2. The left argument is a one-element symbol array holding a name, but that name has no value. If the name is not local to a function, it is automatically given a prototypical value for an object bound to class cls, and the resulting global variable is bound to that class. (In this case, obj has (`class;cls) would assign the value Null to the object, no matter what the class.)

> > Case 3. The left argument is an array other than a one-element symbol array. A global variable is created whose value is this array, and this variable is bound to the class named in cls. See the example for show for the rules governing the creation of the variable name.

> There are also three cases for the right argument; a container display class (graph, hpane, layout, table, vpane, window), simple classes (all the other display classes except graphTrace and tableField), and a default setting. The graphTrace and tableField classes are not in the domain of is.

> > Case 1. The right argument names a simple class. The object represented by the left argument is bound to that class and the name of the object is returned as the result.

> > Case 2. The right argument names a container class. The global variable named by the left argument must be an array of objects. The function behaves as in Case 1, and additionally binds to their default classes any free children of the object being bound. The geometry of the newly bound object is determined by the form of the object's value. "Example 1. Manipulating Layouts" shows how the value of the left argument can determine the geometry of the object.

> > Case 3. The right argument is the Null. The object named in obj (or created, for Case 3 of the left argument) is bound to its default class. See "Default Class Binding".

> If the object to be bound is already bound to a class, it is first freed.

> The result in the first two cases for the left argument is ''Òobj, and in the other case it is a symbol scalar holding the name of the created variable.

> See "Assignment of Objects Bound to Display Classes" for a discussion of assigning values to objects that are bound to display classes and the refusals and error messages that can occur.

## of

Syntax

> rscs of obj

Arguments and Result

> The right argument obj is a symbol scalar or one-element vector.

> In the usual case, the left argument rscs is a symbol array, and the result is a nested vector of the same shape. The left argument can also be a slotfiller or association list suitable as a right argument for has, and the result is a nested vector of shape Ò0Ørscs or (Òrscs)ß2, respectively.

> In the attributed data case, the left argument is either (`out;value) or (`in;string), where value is appropriate for an element of obj and string is appropriate for an entry in a cell of a display of obj, and the result is a nested scalar.

Definition

> Consider the usual case first, and since only the attribute names in a slotfiller or association list are used (the values being ignored), assume that the left argument is a symbol array. For every i of É#,rscs, if res is the result, iØres is the value of the resource i#,rscs for the object (i.e., global variable or dependency) named in the right argument obj. Place a dot before the attribute name to indicate that you want the variable holding the value, not the value itself. (See "Attribute Default Variables"). If there is no such variable, a Null is returned. See the examples for has.

Attributed Data

> For `out, the result is the enclosure of the formatted string, the string that would appear for an element of obj with value value in a display. For `in, the result is the enclosure of the converted value, the value that would be appropriately placed in obj as a result of the entry of string in a cell of a display of obj. It is not necessary for obj to be shown, although it must be bound.

Examples

>          `title `bg of `header ã Continued from has example. Usual case.
>     < Visual Display
>     <  `yellow
>          (`in;'142.376') of `a ã Attributed data, assuming appropriate a
>     <  142.376                 ã Converted value, a floating-point number.
>          (`out;142.376) of `a
>     < 142.376                  ã A character string.
>          `a has (`out;'f12.3') ã Now change output format.
>      `.a
>          (`out;142.376) of `a
>     <     142.376

## show

Syntax

> show x

Argument and Result

> The argument is any array. The result is Null.

Definition

> If x is a one-element symbol array representing a bound object, that object is displayed on the screen in the format to which it is bound. If x is a one-element symbol array representing a free object, that object is bound to its default class (see "Default Class Binding") and then displayed. Otherwise, an object is created whose value is that of the expression x, and the object is bound to its default class and displayed on the screen.

> If the displayed object is a table or a graph and its children were already bound, either explicitly by the user or as a result of being displayed on the screen, they are re-bound as appropriate for x.

Example

>          show É2 3
>     ã     gn: variable generated
>     ã     gn: S will bind variable to array
>     ã     gn: variable bound to array

> gn is a global variable name generated by show. The value of that variable is É2 3. The name is chosen to be the first available name in the root context from the list of names:

>     .a, .b, .c, ... , .y, .z, .a0, .a1, .a2, ... .

# Dependencies and Displayed Objects

> Dependencies marked for evaluation will ordinarily be reevaluated only when explicitly referenced. If, however, a dependency is displayed on the screen, it will be automatically referenced upon being marked for evaluation (see the discussion following the next example). The effect is that its value is always current relative to the objects on which it depends, which is the most generally useful behavior for dependencies displayed on a screen. They are, after all, being referenced at unknown times by the user. For example, if a dependency represents a view of a database and the database changes, one would expect to see the view change accordingly. The same automatic referencing can be obtained without actual display on the screen by binding a dependency to the reference display class, as in `d .is `reference.

> Immediately referenced dependencies, however, require extra consideration similar to cyclic dependencies. Consider the following simple example:

>          aû0 3 2 ¢1 5
>          bû9 2 5 4 3
>          c:a+b
>          show `c is `array
>          bûb,10
>           +: length
>     *

> This dependency set should be organized in a commit and cancel style. When a, b, and c are displayed and edited on the screen, the decision to commit or cancel can be put on the screen as well, in the form of a commit button and cancel button. There is then no need for a callback function to record update activity or for tests as to when commitments can be done.

> There is a general rule for when dependencies that are displayed (or bound to the reference display class) and marked for evaluation will be automatically evaluated. The A+ process is always executing in an event loop. Within this loop it processes, one at a time, messages from Emacs or an XTerm (keyboard entry, or stdin in Unix terminology), from other processes through adap, and from the screen (e.g., key and button presses). Some of these messages are processed by evaluating A+ expressions or invoking callback functions, during which dependencies might be marked for evaluation. During each pass through the event loop, a series of messages is processed and then the screen is refreshed, i.e., all dependencies that are displayed (or bound to the reference display class) and marked for evaluation are evaluated. Since the programmer can't be sure how many messages are processed on each pass, the prudent thing is to assume that it is only one. The assumption, therefore, must be that the screen is refreshed after each message is processed.

> For instance, in the above example the expression bûb,10 was evaluated, which constitutes a message and caused the displayed dependency c to be marked for evaluation. When execution was complete, c was automatically evaluated. Since this happened before a was adjusted, which would have required a separate message, an error occurred. If, however, the expression (a;b)û(a,5;b,10) had been entered, then both a and b would have been updated in the evaluation of this single message, and the subsequent automatic evaluation of c would not have failed because of a length error. Note that had the expression contained a defined function, that function would have been executed to completion before c was automatically evaluated. The respecifications of a and b could have occurred anywhere within that function execution, even in different functions that it called, without a length error.

> In sum, if, as in this example, a displayed dependency requires more than one thing to be done before it can be correctly evaluated, then either all those things must be done within a single message, or the evaluation must be deferred, say through a commit and cancel formulation.