Attributes with Callbacks


An attribute associated with certain button presses or certain key presses or other events can be assigned an event callback function, which will be invoked whenever an associated button or key is pressed or event takes place. All these functions, except as noted, can have from zero to three arguments, the basic syntax being
     ecfn{s;c;v}
where The arguments always have these meanings, in this order, no matter how many (or few) are used in the definition of the function.

The value of an attribute with callback is given as either the function name, 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 equivalent to (f;()), indicating that the static data is Null. Note that the first element of the value of the attribute is a function, not the name of a function; if you use the name f in specifying an attribute, change the definition of f, and want the callback to use the new definition, you must specify the attribute again.

The actions of some of these attributes depend on the row or cell that is currently selected; for example, the effect of the delete attribute is to delete the selected row. Whenever a function associated with one of these attributes is called because a key or button was pressed, some row or cell or trace in a displayed object must have been selected. Usually it is important to determine within the function which row or cell it is; the attributes row and col hold the row index and, when it is meaningful, the column index of the selected row or cell. The values of two other attributes are relevant here: the value of selected is the pair (row attribute, col attribute), and the value of selected field, which applies only to tables, is the nested array pair (row attribute; symbol holding the name of the selected field).

Some of these attributes have default behavior. For example, the default behavior of the delete attribute is to delete the selected row. These attributes can be assigned functional values to change the default behavior, or simply be assigned 0 to turn the default behavior off. If off, the default behavior can be turned back on by setting the value to 1. The default behavior can also be turned off with `false or `off in place of 0, or turned back on with `true or `on in place of 1.

When an attribute attr has a default behavior for the class to which an object obj is bound, that behavior can be invoked by s.call{`obj;`attr}. Thus, a callback function can be assigned to an attribute of an object that will, when called, make a decision whether or not to invoke the default action, to do some other work, or to do both or neither. s.call should work for all attributes with default callback behaviors; it will work for all attributes listed in 0ěs.EVENT_CALLBACKS.

Attributes with Callbacks
(event callbacks - up to three arguments -, except as noted)
AttributeDescriptionDefault
addtexttrace
addtrace
copytexttrace
copytrace
refer
referpoint
textactivate
See the table "Attributes for Interactions with Graphs". See also "refer" in this table.  
clear If an object was the last one in its A+ process to set the primary selection buffer, and that buffer is subsequently set by another process, a clear event occurs for that object. See "Accessing the Primary Selection Buffer".  
deiconized
iconized
These event callbacks occur when the widget is deiconized or iconized.  
delete A delete event occurs when Meta-Delete or, on an IBM keyboard, Alt-Delete is pressed. The default action is to delete the selected row or cell. If the attribute is 1, the default action is taken; if 0, it is not. If the last row is deleted, changing the row attribute, a select event (below) is also triggered. 0
done A done callback function is called at the end of a screen entry and refresh cycle, which consists of some or all of the following actions, in the following order: in, preset callback, set variable, ordinary callback, out, done. Note: this is a variable callback function, taking up to six arguments, {s; data; index; path; c; v}.  
editbegincb
editendcb
These events occur when a user begins or stops editing the widget, i.e., when the widget editor is invoked or unmapped, respectively. For array, matrix, slot, and table, the cell involved is given by selected. Null (none)
exit An exit event occurs when the right button is pressed while the mouse pointer is in the shelltitle area of a window, and Quit, or Dismiss, or Close is selected from the menu. The default action is to remove a top-level object from the screen. If the attribute is 1, it is taken; if 0, it is not. 1
f1 through f12 There is no default action for function key presses. f1 controls the action when F1 is pressed, f2 when F2, and so on.  
increment
decrement
These events occur when, respectively, an up or down arrow button (shown when arrowbuttons is 1) is pressed. A slot may have several such buttons; the selected attribute gives the symbol for the entry whose button was pressed.  
incurrent workspace

outofcurrent workspace
In a CDE window, these callbacks occur when the window:
  • receives presence in the current workspace (i.e., when the presence of a window is changed to include the current workspace or when the current workspace is changed to a workspace which includes this window from a workspace which did not include it) or

  • loses presence in the current workspace (i.e., when the presence of a window is changed to exclude the current workspace or when the current workspace is changed to a workspace which does not include this window from a workspace which included it).
See the
caveats for deiconized. Ignored outside CDE.
 
insertabove An insertabove event occurs when Shift-Meta-Insert or, on an IBM keyboard, Shift-Alt-Insert is pressed. If 1, the default action is to insert a new row or cell above the currently selected one. If 0, the default is not taken. 0
insertbelow An insertbelow event occurs when Meta-Insert or, on an IBM keyboard, Alt-Insert is pressed. If 1, the default action is to insert a new row or cell below the currently selected one. If 0, the default is not taken. 0
is There is no default action associated with this attribute. The function is called when an object is bound to a display class.  
key There is no default action. The function is called when a key press occurs in the value area during editing.  
notify The request attribute is set in order to reference the last entry written to the primary buffer. A notify event occurs when that entry is available for referencing. See "Accessing the Primary Selection Buffer".  
pagechangecb When a user clicks on the tab of a notebook page which is not the current page, thereby making it the current page, this callback is fired. The new page name is, of course, available from the currentpage attribute. Null (none)
rband If the mouse pointer is on a page object and the left mouse button is pressed and held, a rubberband box is created. The box is anchored in the upper left corner of the character on which the pointer rested when the mouse button was pressed, and the diagonally opposite corner of the box moves with the pointer. The rubberband box as drawn disappears and an rband event occurs when the mouse button is released. If rband is 0, the box attribute is unchanged and the page object appears unchanged. If rband is 1, the location and extent of the box that triggered the event is appended to the box attribute and the box is shown in the page object in the color indicated in boxcolor. 0
refer In an array, matrix, table, or view object, a refer event occurs when the pointer is in a selected row or cell that has focus and the left mouse button or the Enter key is pressed. Hence it occurs as the result of a "double click" with the left mouse button in a row or cell. There is a default action for array, matrix, and table only, taken if refer is 1: highlight the referred row in the indexbg color and append the new value of the row attribute to the value of the index attribute. If refer is 0, the default action is not taken. Pressing the left mouse button on a referred row removes the reference.

In a password or scalar object, a refer event occurs when the mouse pointer is in either the title or value area, and the left mouse button is pressed. In a slot, the pointer can be in any label or value area. In a graph, the pointer can be anywhere on the graph; if the pointer is on a line trace, the event occurs for that trace. In all these cases, a refer event occurs only if the area has focus; there is no default action.

0 for array, matrix, table, and view;
Null otherwise.
save A save event occurs when Ctrl-s is pressed while an object bound to the text display class has focus. If save is 1, the edited text on the screen is saved in the workspace variable. If it is 0, this default action is not taken. 1
select There is no default action for mouse button presses or arrow key presses. This attribute can be set for an object of class array, matrix, table, or view, and the function to which it is set will be called whenever the mouse pointer is on a row or cell of the object, that row or cell is not currently selected, and the left mouse button is pressed. The selected cell appears raised and in the color specified by the selectbg attribute, while the rest of the selected row appears in the color specified by the rowbg attribute. Once a row or cell is selected the user can move from row to row or cell to cell with the arrow keys. With each press of an arrow key the row or cell in the indicated direction becomes selected, and the function is called. Orogrammatically setting a row or column to -1 causes a select callback.  
selectcol If 1, the default action is to highlight the selected column labels in the rowindexbg color and update the value of the colindex attribute with the row index of each selected column label. If 0, the default action is not taken. This attribute can be set for a matrix, and the function to which it is set will be called whenever the mouse pointer is on the label area of a column and any mouse button is pressed. If there is a selected row at the time a column label is selected, it remains unchanged, but the selected cell becomes the one at the intersection of the selected row and the column beneath the newly selected column label. In particular, if a new cell is selected, a selected event occurs. Press any mouse button on a referred column to remove the reference. 0
selectcorner If 1, the default action is to highlight the selected corner label in the cornerindexbg color and change the value of the cornerindex attribute to 1. If 0, the default action is not taken. This attribute can be set for a matrix, and the function to which it is set will be called whenever the mouse pointer is on the label area of the upper left corner and any mouse button is pressed. Press any mouse button on the referred corner to remove the reference. 0
selectfield This attribute can be set for a table, and the function to which it is set will be called whenever the mouse pointer is on the title area of a field and any mouse button is pressed. If there is a selected row at the time a field title is selected, it remains unchanged, but the selected cell becomes the one at the intersection of the selected row and the field beneath the newly selected field title. In particular, if a new cell is selected, a selected event occurs.  
selectrow If 1, the default action is to highlight the selected row labels in the rowindexbg color and update the value of the rowindex attribute with the column index of each selected row label. If 0, the default action is not taken. This attribute can be set for a matrix, and the function to which it is set will be called whenever the mouse pointer is on the label area of a row and any mouse button is pressed. The row with the selected label becomes the selected row. If no row was selected at the time the row label is selected, the selected cell is the one in the first column of the selected row. If there was a selected cell at the time the row label was selected, the newly selected cell is the one in the same column, but in the newly selected row. In particular, if a new cell is selected, a selected event occurs. Press any mouse button on a referred row to remove the reference. 0
3down Pressing the right mouse button causes a 3down event.  
3up A 3up event occurs when the right mouse button is released.  
2down Pressing the middle mouse button causes a 2down event.  
2up A 2up event occurs when the middle mouse button is released.  
validate There is no default action associated with this attribute. The function is called when the keyboard entry for a password object is completed (by an Enter).  

Accessing the Primary Selection Buffer

When text is clipped in an Emacs or XTerm window, say by dragging the pointer over the area while the left button is depressed, the text is written in the primary selection buffer, and when text is pasted into an Emacs or XTerm window, it is retrieved from the primary selection buffer. A+ provides four attributes for using this buffer: primary, request, notify, and clear.

To write in the primary selection buffer, give the primary attribute a character value. (Attempted settings with other types of data are quietly ignored; the value of primary remains unchanged.) Since there is only the one buffer, the value of the attribute changes for all objects.

To read the buffer, specify the request attribute for a bound object. If and when primary has been given a proper value, a notify event occurs and the buffer can be read by referencing the primary attribute.

If the buffer is overwritten by another process (not by an object in this A+ process), the A+ object, if any, whose specification of the primary attribute was overwritten will undergo a clear event. Dragging the pointer over text in an Emacs, Xterm, or FrameMaker window, for example, will cause a clear event. The text that is highlighted can then be retrieved through primary, but text that Emacs demarcated by bouncing the cursor back and forth cannot - but can, however, after you press the "0 to PRIMARY" button in an xcutsel window.

See the tutorial scripts, which are available under the "Tutorials" item on the "On-Line Documents" section of the home page. The entry "s.tutorials/data" gives an example, for the view class. It is an ASCII text file; use Emacs to access it.


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