s A+ Reference: The s Context

The s Context

For a listing, with links, of s-context functions and variables alphabetized by their A+ names, click here.


Although the external functions of the s context are present when A+ is started, a $load s must be performed to bring in the rest of the s context. This command retrieves a packfile. (The script corresponding to the packfile is in s.raw.+.)

Many of the functions in the s context have to do with creating and managing display classes and their attributes. For examples, see "Display Classes".

Specification of attribute values can usually be given in one of two ways: as a slotfiller or an association list. In the case of a slotfiller sf, each of its symbolic indices holds an attribute name, and the value of the attribute attr is accessible as attrsfal.  An association list al is a vector with an even number of elements. The elements at the even index positions, 0, 2, 4, etc., are symbols holding attribute names. The elements at the odd index positions are the attribute values. For example, if i is even then (i+1)al is the value of the attribute ial.

Definitions of s-Context Functions

Array to Character Vector s.box{a}

     Argument and Result
The argument is any A+ array. The result is a character vector.

     Dependency
Printing Precision, `pp.

     Definition
The result is a character vector that, with one exception, produces an A+ array identical to the argument a when executed. The exception is that the decimal parts of floating-point numbers may not be represented with sufficient precision to reproduce the original value.

This function is used to produce output representations for objects in the array and slot display classes.

Attribute Settings s.domainOf{c;a}

     Arguments and Result
The left argument c is a one-element symbol array, and the right argument a is a symbol scalar or vector. The result is a nested vector of depth 1 whose count equals the count of a.

     Definition
The symbol c names a display class, such as `graph. The right argument is a list of attribute names for that class. The i-th element of the result is an enclosed vector of the possible values of the i-th attribute in the right argument, for the display class specified in c. For attributes whose values are not simply chosen from a list, like `yx, the corresponding elements in the result are enclosed Nulls. Examples of attributes whose values are chosen from a list are `fg and `editspace.

Attribute Sources s.derivedFrom{c;a}

     Arguments and Result
The left argument is a one-element symbol array and the right argument, a, is a symbol scalar or vector. The result is a vector of symbols whose count equals the length of a.

     Definition
The left argument, c, names a display class and the right argument one or more attributes. The result is a vector of class names indicating from what real or virtual class c inherits its definition of each attribute.

Bind Several s.are{v;c}

     Arguments and Result
The arguments are lists of symbols, each argument a vector or scalar. The result is a vector of symbols whose length equals the count of v.

     Definition
The left argument, v, names variables and the right argument names display classes. The explicit result is a vector of the names in v. Bind Several binds the variables listed in v to the classes listed in c. It is like is but looks ahead in c to avoid the rebinding that a top down approach can involve. The variables in v should be listed in a top down order, to avoid the reparenting that a bottom up approach would entail. If c is not the same length as v, it is used cyclically or partially - i.e., (v)c is used as the list of classes.

Here is a comparison of four different ways of binding three objects:

     ab30 40; l`a`b;

     `a `b `l is `matrix `matrix `layout;
    .a: variable bound to matrix
    .b: variable bound to matrix
    .l: variable bound to layout     Because of the bottom up
    .a: variable reparented to .l    order, a and b must be
    .l: variable reparented to top level window
    .l: workspace will be created    reparented and, since
    .b: variable reparented to .l    a was top-level,
     free `l;                         l must also be reparented.

     `l `a `b is `layout `matrix `matrix;
    .l: variable bound to layout
    .a: S will bind variable to array
    .a: variable bound to array      Part of binding of l
    .b: S will bind variable to array
    .b: variable bound to array      Because of the use of is
    .a: variable bound to matrix     and top down order, both
    .b: variable bound to matrix     children must be re-bound.
     free `l;
                                       Now the s.are ways.
     `a `b `l s.are `matrix `matrix `layout;
    .a: variable bound to matrix
    .b: variable bound to matrix
    .l: variable bound to layout
    .a: variable reparented to .l  No lookahead for reparenting:
    .l: variable reparented to top level window  all three
    .l: workspace will be created    objects must be reparented,
    .b: variable reparented to .l    just as they were by is
     free `l;

     `l `a `b s.are `layout `matrix `matrix;
    .l: variable bound to layout    Arguments are in top down
    .a: S will bind variable to matrix order, so no reparenting
    .a: variable bound to matrix     is required, and s.are
    .b: S will bind variable to matrix  looks ahead to avoid
    .b: variable bound to matrix        rebinding.

Call Default Callback Function s.call{x;a}

     Arguments and Result
The left argument x is a one-element symbol array, and the right argument a is a symbol scalar. The result is null.

     Definition
The symbol x names a displayed object, and a is an attribute name for that object; a must have a default action for objects of the class to which x is bound. The effect is to invoke that default action.

This function would typically be used within a user's callback function for the attribute a; it enables selective invocation of default behavior, as well as providing a way to add other function to the default behavior

The attributes currently supported are:

addtexttrace
addtrace
copytexttrace
copytrace
cornerselect
delete
exit
insertabove
insertbelow
rband
refer
save
selectcol
selectrow
textactivate

Capture the Screen Configuration s.script{}

     Result
The result is a character vector.

     Definition
The result contains A+ expressions to recreate the binding of objects currently bound when this function is executed, to set their attributes, and to set the global variables of these objects to their current values. In effect, the current screen management state of an application can be captured for future reproduction. Which objects actually appear in the script is controlled globally by the switch s.AUTOSCRIPT, and locally by the save and script attributes.

CDE Window Manager s.CDE

     Result
Scalar 1 or 0.

     Definition
s.CDE is a dependency. Its value is 1 if the window manager is a CDE one and 0 otherwise. It is evaluated the first time it is referenced; thereafter, the stored value is used. The value does not change within a process.

Character Vector to Array s.execute{c}

     Argument and Result
The argument c is a character vector. The result is an A+ array.

     Definition
The argument c represents an A+ array, in the same sense that results of the function s.box represent A+ arrays. The result is the A+ array represented by the argument c.

Class Can Have Attributes s.canHave{c;a}

     Arguments and Result
The left argument is a symbol naming a class and the right argument is a symbol vector listing attributes. The result is a boolean scalar.

     Definition
The result is 1 if all the attributes named in a can be set for an object of class c, and 0 otherwise.

Classes with Attributes s.classesHaving{a}

     Argument and Result
The argument a is a symbol scalar or vector. The result is a symbol vector.

     Definition
The result is a list of classes having the attributes listed in the argument a.

     Example
     s.classesHaving{`at`geometry}

Closest Named Color s.closest{r}

     Argument and Result
The argument is a three-element integer vector. The result is a symbol.

     Definition
The result holds the name of the color whose rgb value is closest to that represented by the argument.

Color Name to Pixel Conversion s.color{x}

     Argument and Result
If the argument is a character vector or symbol, the result is an integer scalar; if the argument is an integer, the result is a symbol.

     Definition
This function converts from color names to pixel representations of colors, and from pixel representations to names. The pixel representation is the most efficient way to specify colors in s. Consequently, for applications that set colors often, it may be best to compute their pixel values once and for all during application initialization, and use those values in color specifications. Do not store the pixel values in your A+ scripts, however, because they change from one session to another.

Color Shades s.shade{b;c}

     Arguments and Result
The left argument is an integer between 2 and 19, and the right argument is a two-element vector of symbols. The result is a character matrix with b rows and seven columns.

     Definition
The result r is such that r is a vector of hex representations of colors that vary from the color named in 0c to that in 1c.

Color to Hex s.ch{c}

     Argument and Result
The argument is a character vector. The result is a symbol of the form `#rrggbb.

     Definition
This function is the inverse of hc.

Color to RGB s.cc3{p}

     Argument and Result
The argument is a symbol scalar. The result is a three-element integer vector.

     Definition
The argument is a color name, the result its rgb representation. See s.hc3 for a discussions of the rgb color representation.

Copy Attributes s.copy{x;v}

     Arguments and Result
x is a symbol scalar and v is a list of symbols. The result is a vector of symbols.
     Definition
Copy Attributes attempts to bind the variables named (in symbol form) in the vector or scalar v to the same class as that of the variable named in x. The other attributes of each one successfully bound are then given values copied from x. The result lists the variables which were successfully bound.  Warning:  x should have only one item; if you give a list for x, the first item is used for all the variables in v and the other items are ignored, without any message or error report.

If x names a table (or graph) and a variable named in v could be a tableField (or graphTrace) but not a table (or graph), then a parent variable is generated for it and bound to table (or graph), but the attribute values of x are nevertheless copied, where appropriate, to the variable named in v, not to the generated variable.

Attribute values are copied except as dictated by the variables, as in the following example, where a blank space appears in t1 at the right because of the cols limitation:

     abcdef10
     t`a`b`c`d
     t1`e`f
     `t has (`class;`table; `cols;4; `show;1)
     `t s.copy `t1
 `.t1
     >>`space of `a`b`c`d`e`f
 5 5 5 5 5 5
     (<`yxs`cols) of `t`t1
< <  191 279
  <  4
< <  191 279      Same size as the four-column t
  <  2            Only two columns because t1 is 2.

Define Attributes s.classHas{c;a}

     Arguments and Result
The left argument c is a symbol. The right argument is a two-element nested vector, in which the first element holds a symbol and the second either holds a two-element function array or is the Null. The value is a symbol.

     Definition
The effect of this function is to define a new attribute for the class named in c, or delete a defined attribute. If the right argument is of the form (s;(g_f;s_f)), then the attribute named in the symbol s will be defined. If the right argument is of the form (s;), then the defined attribute named in s is deleted.

The syntax of the function g_f is g_f{o}; if the symbol o is an object of class c, then the result of g_f{o} is the value of the attribute s for that object. The value of the attribute should be obtained in the same way as for primitive attributes, namely as the result of o has s. The function has uses g_f to get the value.

The syntax of the function s_f is s_f{o;a}; if the symbol o is an object of class c, then the effect of s_f{o;a} is to set the value of the attribute s to a for that object.

     Example
See "Display Classes".

Desktop Geometry s.desktop{}

     Result
The result is a two-element vector.

     Definition
The result is the number of rows and number of columns in the virtual desktop.

Electrified Attributes s.used{x}

     Argument and Result
The argument is a singleton symbol and the result is a vector of symbols.

     Definition
The result is a list of the attributes of the object named by x that are explicitly electrified. In addition to attributes connected to variables and functions, however, the result includes attributes connected to dependencies.

See the example for the next function, s.usedBy, especially concerning "explicitly".

Electrifying Objects s.usedBy{y;x}

     Arguments and Result
The argument y is a scalar or vector of symbols; x is a singleton symbol; the result is a vector of enclosed symbols or Nulls.

     Definition
The argument y lists attributes and x names an object. For each attribute, the result names the variable, function, or dependency which explicitly (see the example) supplies its value for the object. For an attribute using none of these, a Null appears in the result instead.

     Example
     show `a  a8 10
     s.BLACK`blue          The fg color in the display of a
     s.used `a              immediately turns blue, but s.BLACK
     `fg s.usedBy `a        is a default, not explicitly set,
<                           so neither s.used nor s.usedBy
                            shows the electrification.
     `a has (`fg;`s.BLACK)  Explicitly connect the fg color to
     s.used `a              s.BLACK.  Now both s.used and
`fg                         s.usedBy show the connection of
     `fg s.usedBy `a        `fg for `a with s.BLACK
<  `s.BLACK

Establish Screen Management Functions s.functions{}

     Result
Null.

     Definition
Establish the six root-context screen-management functions - free, has, hide, is, of, show - in the current context.

Font Name to Internal Form Conversion s.font{x}

     Argument and Result
If the argument is a character vector or symbol, the result is the internal form, an integer scalar. If the argument is an integer, the result is a symbol.

     Definition
Just as the pixel representation of colors is an efficient, internal form, there is an internal representation for fonts (see s.color). This function converts font names to the internal form, and also the internal form to font names. For applications that set fonts often, it may be best to compute their internal values once and for all during application initialization, and use those values in font specifications. Do not store the internal values in your A+ scripts, however, because they change from one session to another.

Free All Objects s.reset{}

     Definition
The effect is to free all objects that would be named by s.windows{}. The result is a vector of symbols naming all the objects that were freed.

Get Attribute Defaults for a Class s.defaultOf{a;c}

     Arguments and Result
The left argument a is a symbol scalar or vector. The right argument c is a one-element symbol array. The result is a boxed array of the same shape as the left argument a.

     Definition
The i-th element of the result is the enclosed default value of the i-th attribute in a for the class c.

     Example
     s.defaultOf{`bg`fg;`array}

Get Attribute Default Variables or Values s.Of{a;c}

     Arguments and Result
The left argument is a scalar symbol or vector of symbols. The right argument is a symbol. The result is a nested vector with the same number of elements as the left argument.

     Definition
The i-th element of the result is an enclosed name or value corresponding to the i-th attribute listed in a for the class c: the name of the attribute default variable if a dot was placed at the beginning of the attribute name in a, else the default value of the attribute. (See "Attribute Default Variables"). Cf. s.Has.

     Examples
     `bg s.Of `array
<  `grey
     `.bg s.Of `array
<  `s.GREY

Get Attribute Values for Parent s.ofParent{a;o}

     Arguments and Result
The left argument is a scalar symbol or vector of symbols. The right argument is a symbol. The result is a nested vector with the same number of elements as the left argument.

     Definition
The i-th element of the result is the enclosed value of the i-th attribute listed in a for the parent of the object o.

Hex to Color s.hc{h}

     Argument and Result
The argument is a symbol of the form `#rrggbb. The result is a character vector.

     Definition
The argument is a hex representation of a color, and the result is the color name. See s.color for a discussion of the pixel color representation.

Hex to RGB s.hc3{h}

     Argument and Result
The argument is a symbol of the form `#rrggbb. The result is a three-element integer vector.

     Definition
Each pair of characters rr, gg, bb in the argument represents a two-digit hex, or base 16, integer. The base 10 representations of the pairs of hex integers are integers between 0 and 255. The result is of the form (n1, n2, n3), where n1 is the base 10 representation of rr, n2 is the base 10 representation of gg, and n3 is the base 10 representation of bb. The result is an rgb color representation. Both the argument and result are interpreted as the relative intensity of red, green, and blue for a screen color.

List of All Bound Objects s.objects{}

     Result
The result is a nested array of symbols.

     Definition
The result is a list of all objects currently bound to some display class.

List of All Objects Bound to a Class s.boundTo{c}

     Argument and Result
The argument is a symbol scalar. The result is a vector of symbols.

     Definition
The result is a list of the objects bound to the class c.

List of Attributes s.attributes{c}

     Argument and Result
The argument c is a symbol. The result is a vector of symbols.

     Definition
The result is a list of the attributes for the class named in the argument c. In addition, if c is `variable, then the result is a list of the persistent attributes.

List of CDE Workspaces s.wslist{}

     Result
A nested vector of character vectors.

     Definition
The result is a list of the workspace names or, if the window manager is not a CDE one, null.

List of Classes s.classes{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of symbols holding the names of all current classes.

List of metaClasses s.metaClasses{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of symbols holding the names of the display classes that are not virtual and cannot be directly instantiated. In effect, these classes have no visual representations.

     Example
See "Display Classes".

List of Popups s.popups{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of all displayed objects that are popups - not contained in another object and not top level.

List of Real Classes s.realClasses{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of symbols holding the names of the display classes that can be directly instantiated, such as array and table.

     Example
See "Display Classes".

List of Shells s.shells{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of all displayed objects that have window manager decorations, both top-level windows and popups.

List of Subclasses of a Class s.subClasses{c}

     Argument and Result
The argument is a symbol scalar. The result is a nested array of symbols.

     Definition
The result is a nested array of symbols whose values are the names of the subclasses of the class specified in the argument c. A class b is a subclass of the class c if the attribute set of b contains the attribute set of c. The structure of the result indicates the hierarchical structure of the subclasses, based on set membership of their attribute sets.

List of Superclasses of a Class s.superClasses{c}

     Argument and Result
The argument is a symbol scalar. The result is a nested array of symbols.

     Definition
The result is a nested array of symbols whose values are the names of the superclasses of the class specified in the argument c. A class b is a superclass of the class c if the attribute set of b is contained in the attribute set of c. The structure of the result indicates the hierarchical structure of the superclasses, based on set membership of their attribute sets.

     Example
See "Display Classes".

List of Top-level Windows s.toplevels{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of all top-level windows - those not contained in another object, with `iconic equal to 1.

List of Virtual Classes s.virtualClasses{}

     Result
The result is a vector of symbols.

     Definition
The result is a list of symbols holding the names of the display classes that cannot be directly instantiated, but nonetheless have visual representations, namely tableField and graphTrace.

     Example
See "Display Classes".

Move Mouse Pointer s.warpPointer{w}

  Releases 2.44 and 4.09 on.

     Argument

The argument is a scalar symbol naming a workspace.

     Definition
This function moves the mouse pointer to the window associated with the symbol w. This is useful after a window has been given focus and you want keyboard input to go immediately to that window.  Example:
     (a;b)  (10; 3 3)
     s.show `a `b
     `b s.has (`focus;1)
     s.warpPointer `b

Nested Association List s.ral{x}

     Argument and Result
The argument is a nested, i.e. recursive, slotfiller and the result is a nested association list.

     Definition
This function converts a nested slotfiller to the equivalent nested association list.

No Longer Use Variables s.doesNotUse{o;a}

     Arguments
Each argument is a one-element symbol array or a vector of symbols.

     Definition
If ,o and ,a have the same number of elements, then for every valid index i, the attribute i#,a of the object i#,o will no longer use any variable it may have been using (see s.uses). Otherwise, one of them has only one element, and it is paired with every element of the other argument.

Objects with Specific Attribute Values s.which{a}

     Argument and Result
The argument is either a slotfiller or an association list. The result is a symbol vector.

     Definition
The argument represents a list of attributes and their values (see above). The result is a list of the objects which currently have those settings for those attributes.

Object with Keyboard Focus s.this{}

     Result
The result is a symbol scalar, or the Null.

     Definition
The result is the object on the screen that currently has keyboard focus, or the Null if there is none.

Primitive Attributes s.primitiveTo{c}

     Argument and Result
The argument is a one-element symbol array and the result is a vector of symbols.

     Definition
The result is a list of the attributes for the given class whose definitions it does not inherit, i.e., whose definitions are primitive to the class.

Recursive Association List to Nested Slotfiller s.rsf{a}

     Argument and Result
The argument a is a recursive association list, i.e., an association list in which some of the values may themselves be association lists.

     Definition
The result is a nested slotfiller equivalent to the argument a. That is, any value in a can be reached by a sequence of associations `x, `y, `z, ... ; that same value can be reached in the result by the primitive function Pick with a left argument of `x`y`z ... . The individual changes are made using _alsf.

Refresh All Objects s.refresh{}

     Definition
The effect of this function is to refresh the visual appearance of all objects to reflect recent settings of display-related attributes such as fg and out.

Restore the Captured Screen Configuration s.load{f}

     Argument and Result
The argument is a character vector. The result is a two-element nested array, with each element a simple vector of symbols.

     Definition
The effect is the same as _load{f}, except for the explicit result. The result is of the form (b;f), where b is a vector of symbols listing the objects that are bound to a display class as a result of loading this file, and f is a vector of symbols listing the objects freed. Cf. Save the Captured Screen Configuration, s.save, below.

RGB to Color s.c3c{r}

     Argument and Result
The argument is a three-element integer vector. The result is a symbol scalar.

     Definition
This function is the inverse of Color to RGB, s.cc3.

RGB to Hex s.c3h{r}

     Argument and Result
The argument is a three-element integer vector. The result is a symbol of the form `#rrggbb.

     Definition
This function is the inverse of Hex to RGB, s.hc3.

Save the Captured Screen Configuration s.save{f}

     Argument
The argument is a character vector.

     Definition
The effect of this function is to save the same result as that of the function s.script{} in the Unix file named in f. Cf. Restore the Captured Screen Configuration, s.load, above.

Screen Management Documentation s.doc{f}

     Argument and Result
The argument is a character vector naming a Unix file.

     Definition
The effect of this function is to write summary documentation for the screen management system to the file named by the argument f.

Scroll Together Horizontally s.hScroll, Vertically s.vScroll

     Definition
Scroll Together Vertically and Scroll Together Horizontally are callback functions that manage scroll groups. When they are used, a group is represented by a symbol vector and the appropriate one of these functions is established as a preset callback function for this vector. They can add and delete members, setting appropriate values for new and deleted members' vscrollwith, setcol, setfirstcol, and hscrollwith, setrow, setfirstrow attributes. Note: For example:
     `a`b`c`d`e`f is `array  abcdef20 20
     XY()
     _spcb{`X;(s.hScroll;)}; _spcb{`Y;(s.vScroll;)};
     X`a`b`c
Now these three objects will scroll horizontally together.

     show `a`b`c`d`e`f
     Y`a`b`e`f
Now these objects will scroll vertically together, a and b both ways.

Make d scroll horizontally with the others (Append Assignment okay).
     X[,]`d

Make c scroll with a, b, and e, and make f not scroll with any object.
     Y[3]`c

Sector of Desktop s.beHere{o}

     Argument
The argument is a symbol scalar.
     Definition
The top-level object o is displayed in the currently active sector of the virtual desktop. This is a cover function for `a has `atsector `here.

Set Attribute Default Variables or Values s.Has{c;s}

     Arguments and Result
The left argument is a symbol, the right argument a slotfiller or association list, and the result a symbol.

     Definition
This function sets the default values or attribute default variables for those attributes for the class named by c. See Set Attribute Values for Parent regarding slotfillers and association lists. The right argument represents a list of associations between attributes and either default values or, for any attribute names that have been preceded by a dot, attribute default variables (see "Attribute Default Variables"). Cf. s.Of.

     Example
     `array s.Has `bg `grey
<  `array
     `array s.Has `.bg s.GREY
<  `array

Set Attribute Defaults for a Class s.hasDefault{c;s}

     Arguments and Result
The argument c is a symbol scalar. The argument s is a slotfiller or association list. The result is identical to c.

     Definition
Either form of argument, slotfiller or association list, associates a list of attributes with a set of values in the manner described above. The effect of this function is make these values the default values of their attributes. After s.hasDefaults{c;s} is executed, all objects subsequently bound to the class specified by c will have default values as specified in s.

Note the following relation between this function and persistent attributes: suppose this function is used to set the default value of a persistent attribute for a class c, and that an object bound to another class has had the value of this attribute set explicitly. If that object is then rebound to the class c, the value of the persistent attribute will be the one that had been explicitly set, not the default that was set with this function.

     Examples
After the following is executed:
     `array s.hasDefault (`bg`fg;(`blue;`red))
all objects bound to class `array will have as defaults a blue background and red foreground color. For examples using derived classes, see "Display Classes".

Set Attribute Values for Parent s.parentHas{o;s}

     Arguments and Result
The left argument is a symbol, and the right argument is either a slotfiller or an association list. The result is a symbol.

     Definition
If s is a slotfiller, then each of its symbolic indices holds an attribute name attr and each `attrs is a value. If s is an association list, each element at an even index i is a symbol holding an attribute name, and the corresponding element at index i+1 is a value. In either case, the right argument represents a list of associations between attributes and values. This function sets those attributes to those values for the parent of the object named by o. An object p is the parent of an object o if `o explicitly appears in the value of the global variable p.

Set Current CDE Workspace s.setcurrentws{n}

     Argument and Result
The argument is a character string and the result is null.

     Definition
The workspace named n is made the current workspace (i.e., displayed) if the window manager is a CDE one. Otherwise, no action is taken. [Future use]

Tree Dependency s.wstree{s}

     Argument
The argument s is a scalar symbol naming a global variable.

     Definition
The value of the global variable named in the argument becomes a nested array representing the workspace-tree dependency. (The first top-level object created in an A+ session becomes the so-called screen workspace for that session; if that object is subsequently put in a container, that container becomes the screen workspace. Any other top-level objects do not appear in the result.)

Use Variables s.uses{o;s}

     Arguments
The argument o is a one-element symbol array or a vector of symbols. The argument s is either a slotfiller or an association list.

     Definition
In the simplest case o has one element naming an object, and s contains a pair of symbols a,v where a is an attribute and v names a global variable. The effect of this function is to identify the value of the attribute for the object named by o with the value of the global variable, so that whenever the value of the variable changes, the attribute (for the object named by o) automatically changes to the same new value.

In general, if s is a slotfiller, each of its symbolic indices names an attribute attr and each value `attrs is a symbol naming a global variable. If s is an association list, each element at an even index i is a symbol naming an attribute and the corresponding element at index i+1 is a symbol naming a global variable. In either case, the right argument represents a list of associations between attributes and global variables.

There are three possible relations between the number of such pairs, or associations, and the number of objects named in o. If o has one element, then every attribute of the object named by o is identified with its global-variable partner in the manner described above. If o is a list with the same number of object names as there are attribute, global-variable pairs on the right, then the ith attribute of the ith object is identified with the ith variable for every valid i. Finally, if there is only one attribute, global-variable pair on the right, then that attribute is identified with that variable for every object named in o.

Subsumed by s.has.

Users of a Variable s.using{v}

     Argument and Result
The argument is a symbol naming a global variable. The result is a nested pair of symbol vectors.

     Definition
The result is of the form (o;a), where o and a are vectors of symbols, and for every valid index i, the attribute a[i] of the object o[i] currently uses the variable named in v (see s.uses, above).

Values of Attributes for a Class s.ofClass{a;c}

     Arguments and Result
The left argument is a scalar symbol or vector of symbols. The right argument is a symbol. The result is a nested vector with the same number of elements as the left argument.

     Definition
The i-th element of the result is the enclosed value of the i-th attribute listed in a for the class c.

     Example
See "Display Classes".

Variable Can Be of Class s.canBe{v;c}

     Arguments and Result
The left argument is a symbol naming a variable and the right argument a symbol naming a display class. The result is a boolean scalar.

     Definition
If v can be bound to c, the result is 1; otherwise the result is 0.

s-Context Global Variables

The s_context global variables are classified as switches, parameters, system attribute default variables, and data variables. See the tables "s-Context Switches (Global Variables)", "s-Context Parameters (Global Variables)", "s-Context System Attribute Default Variables", and "s-Context Data Variables". When the value of an attribute is Null and there is a corresponding s.AUTO... variable, the value of that variable is used for the attribute.

s-Context Switches (Global Variables)
s-Context VariableDescriptionDefault
s.AUTOBUILD If 1, layouts defined by simple vectors of symbols invoke the autobuilder when the objects for the layout are on the screen. Then the objects appear in the layout in the same relative positions they occupied on the screen before the layout was built. 0
s.AUTOCOPY If 1, when a row is inserted values are copied from the row above or below which the new row is inserted.0
s.AUTOEDITSPACE If 1, the size of the edit buffer is the value of s.EDITSPACE. 1
s.AUTOEVALUATE If 0, variables are not to be evaluated in order to determine appropriate attributes for display; they will be set by the programmer. Use with great caution. The evaluate attribute gives finer discrimination.1
s.AUTOEXECUTE If 1, input expressions are executed to obtain a value; if 0, they are not.1
s.AUTOHAS If 1, whenever an attribute value is changed, report the new setting in the A+ session log, as a comment.0
s.AUTONEWSHOW For an existing container: if 1, a reparented child (see s.AUTOREPARENT) is reshown and an unbound variable is shown; if 0, a reparented child is reshown only if mapped and an unbound variable is not shown.0
s.AUTOPOSITION In layouts defined by simple vectors of symbols:  if s.AUTOBUILD is 1, layout objects already on the screen keep their relative positions and all others have at values of 0 0 1 1;  otherwise, all objects are stacked vertically if s.AUTOPOSITION is 1, and all have at of 0 0 1 1 if it is 0. 1
s.AUTOPRINTABLE Default value for printable attribute. See /common/s/opt.doc. 1
s.AUTOREPARENT If 1, an orphaned child (such as an object removed from a layout) is reparented to be a top-level object. If 0, an orphaned child is freed.1
s.AUTORESHOW If 1, a reparented child (see s.AUTOREPARENT) is reshown if it was shown in its former parent; if 0, it is not shown. 0
s.AUTORESPACE If 1, the space attribute is increased when exceeded by the result of the default out function.0
s.AUTOSCRIPT If 0, no object definitions appear in the result of s.script{}; if 1, the definitions appear for all objects that have their script attributes set to 1.1
s.AUTOWS When s.WS is null and an object is (initially) shown whose ws attribute is null, s.AUTOWS controls whether the object becomes the screen workspace (and hence top-level; cf. s.SHELL): if 1, yes, if 0, no.1
s.MENUDEFAULT MNEMONIC If 1, when a menu is bound, the default accelerator for each button is the first letter of its symbolic index. If 0, the default is no accelerators. Cf. the mnemonics attribute.0

s-Context Parameters (Global Variables)
VariableDescriptionDefault
s.ABORT Controls whether severe errors (and perhaps also moderate ones - see s.ERROR) cause s functions to abort execution (when s.ABORT is 1) or to suspend it (when 0). Cf. s.QUIET. 1 (abort)
s.AUTOBLANK The default value used for the display of a NA - e.g., where a row or cell has been inserted - in an object for which the blank attribute has not been set. Cf. s.NA. Null
s.AUTODOC Default for doc attribute, for documentation. ''
s.BACKING STORE Set to 0, turns off the use of backing store for any windows created thereafter, which radically reduces XServer memory consumption but impairs refreshing.
If 1, backing store is used (as normal) for any windows created thereafter. Thus some windows can use backing store while others do not.
1
s.BEEP Specify (any value) to cause the display to beep. 0
s.BUSY Whenever s.BUSY is set to 1, an internal "busy count" is incremented.
Whenever s.BUSY is set to 0, this count is decremented by 1 (but not below 0).
When the count is greater than 0, the pointer is busy: it appears as a little clock or stopwatch whenever it is in an s window. This behavior is independent of the setting of s.CLOCK.
0
s.CLOCK If 1, the pointer is busy - it appears as a little clock or stopwatch whenever it is in an s window - during callbacks for displayed objects and during assignments to variables being displayed on the screen, independent of s.BUSY.
If 0, it is not, except as required by s.BUSY.
s.CLOCK is set to 0 in applications requiring fast update rates, e.g., certain real-time updates.
1
s.CONNECTED A slotfiller. The symbolic indices identify displays. An item of the second element is set to zero if the server for the display identified by its symbolic index fails. If the user has not set a callback on s.CONNECTED, then s calls _exit{1} in the event of a failure. Items of the second element are all nonzero.
s.DATASPACE The default for the space attribute. 9
s.DISCONNECT When server disconnects, do _exit{s.DISCONNECT}. 0
s.DOUBLE CLICK INTERVAL The maximum interval, in milliseconds, between two consecutive clicks for them to be considered a double click. 250
s.EDITSPACE Default size of the edit buffer; see the editspace and space attributes. 256
s.ERROR If 0, s functions proceed upon encountering a moderate error (but see s.QUIET); if 1, they act as dictated by s.ABORT. 0 (proceed)
s.EXIT If s.EXIT is a scalar integer, then when the exit attribute is set to 1 the A+ session ends with _exit{s.EXIT}. Null
s.FILLCOLORS This symbol vector provides the default values for the fillcolor attribute of the graph display class. See "fillcolor". The vector `red `green `deepskyblue `violetred `yellow `cyan `pink `white
s.LINECOLORS This symbol vector provides the default values for the linecolor attribute of the graph display class. See "linecolor". The vector `red `green `deepskyblue `violetred `yellow `cyan `pink `white
s.LINESTYLES This vector provides the default values for the linestyle attribute of the graph display class. See "linestyle". The vector `solid `dash `dotdash `dot
s.MSG If s.MSG is `x or `c.x or `c`x, s messages are put in `x or `c.x, and if it is a suitable displayed object, they appear in the display. If s.MSG is null, the messages are displayed in the session log. Null
s.NA The default values used in the workspace for NA - e.g., in rows or cells created by insertabove and insertbelow -, arranged in a slotfiller.
The value used is based on the type of the variable being expanded and is used if the
na attribute is Null (e.g., has not been set). Cf. s.AUTOBLANK.
(`int `float `char `sym `box `func `null; (999999999; 999999999.0; ' '; `; <(); ; ()))
s.QUIET Controls the display of messages in the A+ session:
if -1, none;
if 2, only for severe errors (indicated by  !!! in the message);
if 1, also for moderate errors (indicated by  !!);
if 0, also for warnings (indicated by  !) and information (indicated by  ). See
s.ABORT and s.ERROR.
0 (all)
s.SCREEN A dependency giving the height and width in pixels of the current screen.  
s.SHELL Determines the default window type. All windows that are created when it is 0 are top-level by default. All windows created when it is -1 are popups by default, with one possible exception: if s.WS is the Null, then the next window that is created for a variable whose ws attribute is 1 or, if s.AUTOWS is 1, null is top-level and becomes the screen workspace. But see "Reversing the Effect of the s.SHELL Setting". Also see s.WS in this table and s.AUTOWS. 1
s.TRACE SYMBOLS This vector provides the default values for the symbol attribute of the graph display class. See "symbol". The vector `cross `circle `circlefilled `triangle `trianglefilled `square `squarefilled `diamond `diamondfilled `xsym `star
s.VERIFY Most display classes require a variable to satisfy certain rank and type restrictions. If 0, verification takes place in the A+ interpreter, and when a variable bound to a display class is assigned a value inappropriate to that class, an
: invalid
message is issued and execution is suspended. If 1, verification takes place within the s-context functions and a more meaningful message is issued.
0
s.WP When an object with default formatting is bound, s.WP is used in calculating a tentative value for the object's space attribute:
   if s.WP is 0, the result is the value of s.DATASPACE;
   if it is -1, the result is the minimum width required for any cell in the entire object;
   otherwise, the result is the minimum width required for any cell in just the first s.WP rows or (for a vector) cells, to save computation of widths.
The space attribute is then set to the greatest of its existing value, the value just calculated, and, if the object is a vector, the width of its title.
100
s.WS The screen workspace: the first object bound in a session, and thereafter any container that becomes the parent of the current workspace.
If s.WS is set to the Null, the next object bound becomes the screen workspace; see s.SHELL.
When s.WS is given a valid nonnull setting, then, no matter what form is given in the setting, its value is a two-element symbol vector `contextname `unqualifiedvarname.
Null (when no object has been bound)
s.WSNAME The default value of the shelltitle attribute for the object named in s.WS. 01_argv, or 'A+' if _argv is the Null.

Reversing the Effect of the s.SHELL Setting

The effect of the setting of s.SHELL can be reversed in individual cases by prefixing an underscore (_) to the name of the class to which a top-level object is to be bound.

For example, if the object's name is table1 and it is bound as follows:

     `table1 is `_table
and if table1 is not the screen workspace (see the description of
s.WS), then:

Attribute Default Variables

An attribute default variable for an attribute and a class is a variable that contains the default value for that attribute for that class. Several attributes may share such a variable, and so may several classes. A system attribute default variable for an attribute and a class is a variable that by default contains the default value for that attribute for that class. For example, s.GREY is the system attribute default variable for bg for all classes, editfg for all classes, and so on. Each system attribute default variable has a default value; for s.GREY, as its name might imply, that value is grey.

With three exceptions, when the value of an attribute default variable is changed, the value of each attribute for each class member for which that variable supplies the default is immediately changed: the attribute is "electrically connected" to the variable. For example, if the value of s.GREY is changed to rosybrown, then the backgrounds of all objects being displayed will change to rosybrown and objects subsequently shown will have rosybrown backgrounds.

There are, as said, three exceptions to this electrical connection. When the value of a system attribute default variable is changed, the value for a given attribute for a given object will not be changed under any of these circumstances:

There are several ways to find the attribute default variable, if any, for an attribute for a class, such as:
     `.bg s.Of `array
`s.GREY
An attribute default variable can be removed for an attribute and class, as in:
     `array s.Has (`bg;)
The attribute default variable can be reset to the system attribute default variable in the same way it would be set to any other variable, e.g.:
     `array s.Has `.bg `s.GREY
There are ten system attribute default variables, as shown in the following
table.
s-Context System Attribute Default Variables
VariableDefault ValueApplication
s.BLACKblack editbg, fg, labelfg, titlefg
s.BLUElightsteelblue3 rowbg
s.GREENmediumaquamarine colindexbg, cornerindexbg, rowindexbg
s.GREYgrey bg, editfg, selectbg
s.REDlightsteelblue3 indexbg
s.YELLOWgold hl
s.FONTkaplgallant font, labelfont, titlefont (all classes except graph)

s-Context Data Variables
s-Context VariableDescription
s.COLOR_NAMES1A symbol vector holding color names. See "Colors" in the chapter on attributes.
s.COLOR_NUMBERS1A three-column integer matrix holding rgb values for colors.
s.FONT_NAMESFont names, returned as a character matrix.
 1. For every index i, s.COLOR_NAMES[i] and s.COLOR_NUMBERS[i] refer to the same color.

Load s into your A+ session to see the values of these variables. A simple way to view s.COLOR_NAMES is

     show s.COLOR_NAMES
You can also view s.COLOR_NUMBERS in this way, but it is better to show colors with s.COLOR_NAMES.

doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.