Functional Attributes


Certain attributes are functional: the attribute can be assigned a function instead of a value, and the function will be called any time a value for that attribute is needed. Even though the values of nonfunctional attributes can be reset at any time, functional attributes are more dynamic, because the current state of the application can be tested and attributes set accordingly at the precise time the setting is needed. For example, whenever the value in a cell changes the foreground color of the cell can be set to red if the value is negative and black otherwise (the function producing the attribute value is called after the variable associated with the cell is modified).

An attribute function is one kind of callback function. Its syntax is the same as that of an ordinary variable callback function, and so are the meanings of the arguments (see "Set Callback"). That is, an attribute function can have from zero to six arguments, and the meanings of the arguments, no matter how many are present, are (from left to right in the function header): static data; data value; index; path; context name as symbol; variable name as symbol. These arguments will be denoted by s, d, i, p, c, and v, respectively. Just as ordinary variable callback functions are called when a variable changes, attribute functions are called when values of the variable's attribute are needed, and the function arguments indicate which part of which object needs the value. Unlike an ordinary variable callback function, which need not produce a value, but like a preset variable callback function, an attribute function must produce a value, which must be appropriate to the attribute.

The value of a functional attribute is either the function, say f, or a pair (f;), or a pair (f;s), where s is an array. The form (f;s) specifies the function and its static data s. Both f and (f;) are taken to be equivalent to (f;()), indicating that the static data is Null.

Some of the attribute function arguments differ in form for the various display classes and attributes. "Display Classes vs. Arguments to Attribute Functions" and "Display Attributes vs. Attribute Function Arguments and Rules" give descriptions of these arguments and some comments. The information in any attribute-class pair describes the particular characteristics of an attribute function for that class. The large table in the previous chapter, "Display Attributes", tells to which classes each attribute applies.

Display Classes vs. Arguments to Attribute Functions
Display ClassPath and Index Arguments, p and i
actionSee slot.
arrayThe path p is always Null and the index i is of the form
(row_index;column_index) for a matrix,
(index;) for a vector, and (;) for a scalar.
buttonBoth the path p and the index i are always Null.
check,
choice
See slot.
command,
graph
Both the path argument p and the index argument i are always Null.
graphTraceThe path p is always Null and the index i is always of the form (;column_index), where column_index indicates the visible trace within the trace set being affected. The function for an attribute specific to a graphTrace is called for every visible trace where the attribute has meaning. For example, the function for the fillcolor attribute will not be called for a scatter plot. Note that because of the form of the index i, these attributes can be specified separately for the visible traces within a trace set.
hgrid,
hmenu,
hpane,
label,
layout
Both the path p and the index i are always Null, except that when a label has a multiline value i is the line index for each call to the fg functional attribute. [Future use]
matrixThe path argument p is always Null.
If the index argument i refers to a matrix entry, it is always of the form (row_index;column_index);
if it refers to a row label, it is always of the form (row_index;);
if it refers to a column label, it is always of the form (;column_index);
if it refers to the corner label, it is always 0; and, finally,
if it refers to all entries it is Null.
notebook,
page
Both the path p and the index i are always Null. For page, the function must return an array of the same shape as the underlying variable.
passwordNo functional attribute is meaningful for password.
radioSee slot.
scalarBoth the path p and the index i are always Null.
slotThe path p is always a symbolic index of the slotfiller variable, or Null, whether the attribute refers to the label area or value area of the slot. The index i is always Null.
tableBoth the path p and the index i are always Null, except that i is the break number for report generation.
tableFieldThe path p is always Null. The index i is of the form (row_index;), or just a row index or pair of them, or a report break number. For formatting report break text, d is the unformatted string.
text,
tree,
vgrid
Both the path p and the index i are always Null.
viewThe path p is always Null and the index i is of the form (row_index;).
vmenu,
vpane,
window
Both the path p and the index i are always Null.


Each row of the following
table names one or more display attributes and gives arguments {s;d;i;p;c;v} and rules for them.

The preset and set attributes, although functional, are not included in this table because their arguments are dependent on the changes to the variables for which they are set, rather than the characteristics of display classes.

Display Attributes vs. Attribute Function Arguments and Rules
AttributeArguments {s;d;i;p;c;v} and Rules
beBoth the path p and the index argument i are Null. The data argument d is the name of the child to be bound, in symbol form.
bg These attributes are functional for data cells in the array, matrix, tableField, and view classes; see the descriptions of the arguments for these classes in the previous table.
blink
bold
color
underline
These attributes are for the page display class only, so the arguments are as described in the previous table. The function must return an array of the same shape as the underlying variable.
bggrayscale
breakcriteriafunc
fggrayscale
scalefontcb
The index argument i specifies a row.
breakbggrayscale
breakfggrayscale
breakfont
breakleading
breakoffset
breakstyle
pagebreakcb
The index argument i specifies a break number.
breakprocessfunc Argument i is the beginning and ending row indices for the calculation.
colors The function is called once for each element in an indexed specification (perhaps caused by screen editing), so the arguments specify a cell. The form they take is described in the previous table; see the appropriate one of the nine classes for which this attribute is meaningful.
colspace Both the path p and the index argument i are Null. The function is called whenever the colspace attribute value is established for an object and whenever show is invoked to display that object or an object containing it.
fillcolor
gradient
legend
linecolor
linestyle
linewidth,
movelimit
selectable
style
symbol
symbolsize
These attributes are for the graphTrace display class only, so the arguments are as described in the previous table.

For performance reasons, fillcolor, gradient, legend, linecolor, linewidth, style, symbols, and symbolsize are not fully functional. They are invoked once during assignment and when traces are dynamically added, except that linecolor and fillcolor are fully functional when gradient is true and the style is bar.

fg In the case of an array, matrix, tableField or view, the attribute function is called once for every visible cell, row, or slot value area in the various display classes, whenever the attribute is specified or whenever the object is bound, displayed, or redisplayed. It is also called for any visible cell, row, or value area of a bound object that changes value. When a label has a multiline value, it is called once per line and i is the line number. Otherwise, it is called once for the initial display or any redisplay of the object. The function should return a single color. [Future use]
font The rules for calling this attribute function are the same as for the fg attribute. The function should return a single font.
formatbreakfunc The data argument d is the unformatted string.
geometry The path p and index i are both equal to Null. The function should return the complete geometry specification for the object.
in Attribute functions for the in attribute parse data taken from the screen, which is always in character vector form. The argument d holds a formatted character vector, and the function must produce a value suitable for the object in the workspace. The arguments i and p are of the standard form for each class, except that they are Nulls for attributed data. If the character vector d represents an invalid value, return the Null from this function in order to keep the input area active for another try.
label The function for this attribute is called once for every slot area or matrix label area when the attribute is specified or the object is bound. It is not called when the object is redisplayed or changes occur to the slot value areas or matrix value. The function should return one character vector.
labelfg The function for this attribute is called once for every label area, whenever the attribute is specified or whenever the object is bound, displayed, or redisplayed. The function should return one color.
labelfontSee label.
out A function for this attribute formats data as character vectors to be written on the screen. The data is in the argument d, and the function must produce a character vector of the correct length for the display. The arguments i and p are of the standard form for each class (see previous table), except that they are Nulls for attributed data.
protect The function for this attribute is called whenever a cell, row, slot value area, or visible trace is about to be modified on the screen, to determine whether or not it is protected. To determine the protection on a table cell the attribute function for the table is called first, and if its value is 0, the value or function of the protect attribute for the field holding that cell is used or called.
xaxis
x/Xlabel
x/Xlabelout
x/Xsublabel
x/Xsublabelout
yaxis
y/Ylabel
y/Ylabelout
These attributes are for the graph display class only, so the arguments are as described in the previous table.

For performance reasons, xaxis and yaxis are not fully functional. They are invoked once during assignment and when traces are dynamically added.


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