DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Using callbacks and procedures

Callback data structure (cbs) and keyed lists

Every callback procedure gets passed a Tcl keyed list of callback data as its last argument. A keyed list is a list in which each element contains a key and value pair. SCO Visual Tcl provides commands to delete, get, list, and set keys: keyldel(TCL), keylget(TCL), keylkeys(TCL), keylset(TCL). This keyed list contains information about the widget that invoked the callback and minimally contains the following keys:


widget
name of the widget in which the event occurred

dialog
name of the form dialog in which the widget resides
In addition, the callbacks specified with -callback option will have the following keys:

value
A value corresponding to the contents or the state of the widget. The exact content and meaning of the data for this key depends on the widget and usually corresponds to the data in the ``widget specific'' field for the widget.

VtPushButton
pushbutton label string

VtOptionMenu
name of the widget that activated this callback

VtCheckBox
list of selected toggle buttons

VtRadioBox
name of the widget that activated this callback

VtToggleButton
name of the selected toggle button

VtList
list of items selected

VtDrawnList
selected item position

mode
A value indicating what caused the callback to activate. The value for this key is one of the following (see the tables below for individual ``mode'' keyedList field values):

changed
The user interacted with the widget and moved focus away from it. This implicitly indicates that they have finished interaction with the widget. (This usually corresponds to a value change and loss of focus, for example by using <Tab> or selecting another widget.)

done
The user interacted with the widget and explicitly indicated that they have finished interaction. (This usually corresponds to an <Enter> keypress.)

internalTraverse
This applies only to VtList and VtDrawnList. It occurs when traversing the list using up or down arrows.

select
The user selected something from the widget. (This usually corresponds to a <Space> keypress or mouse button click.)

selectSame
The user selected a value that is already selected. (This usually corresponds to the user selecting a toggle that is already selected inside a CheckBox or RadioBox.)
Additional information, depending on the type of widget and callback, can be put in the callback data. For example, the callback data for VtList contains the key selectedItemList, that contains a list of items selected.

To access the data corresponding to a key, use keylget(TCL). For example, to access the button which caused a pushButton callback and the value passed to the callback, use code like the following:

   proc buttonCB {cbs} {
   	set button [keylget cbs widget]
   	set value [keylget cbs value]
   }
If a callback has additional arguments other than those passed in automatically by the callback structure, declare the arguments first and then declare the callback structure (which is typically referred to as cbs):
   proc buttonCB {arg1 arg2 arg3 cbs} {
   	set button [keylget cbs widget]
   }
   .
   .
   .
   VtPushButton $parent.btn  -callback "buttonCB $par1 $par2 $par3"
The following tables show the value for the ``mode'' key for various widgets in response to various actions.

Value of ``mode'' keyedList value in graphical mode

widget done select change selectSame internalTraverse

         
Text RETURN N/A Chg+LF N/A N/A
  (single line)        
Combo RETURN N/A Chg+LF N/A N/A
  (in combotext widget)        
OptMenu RETURN SPACE/MB1 N/A N/A N/A
  (in droplist)        
CheckBox N/A(*) SPACE/MB1 N/A N/A N/A
RadioBox N/A(*) SPACE/MB1 N/A N/A N/A
PushBtn N/A(*) SPACE/MB1 N/A N/A N/A
Scale N/A MB1 Arrows N/A N/A
ToggleBtn N/A(*) SPACE/MB1 N/A SPACE/MB1 N/A
        (and selected value)  
list N/A(1) SPACE/MB1 N/A N/A Up/Dwn Arrow
          (while in list)
drawnList N/A(1) MB1 N/A N/A Up/Dwn Arrow
    SPACE     (while in dlist)


*
<Enter> does not activate these from Motif 1.2

(1)
uses -defaultCallback for this case

Chg+LF
Change and LostFocus

MB1
single MouseButton click

Value of ``mode'' keyedList value with CHARM Server

widget done select change selectSame internalTraverse
Text RETURN N/A Chg+LF N/A N/A
  (single line)        
Combo RETURN N/A Chg+LF N/A N/A
  (in combotext widget)        
OptMenu RETURN SPACE N/A N/A N/A
(in droplist)          
CheckBox RETURN SPACE N/A N/A N/A
RadioBox RETURN SPACE N/A N/A N/A
PushBtn RETURN SPACE N/A N/A N/A
Scale N/A N/A Arrows N/A N/A
ToggleBtn RETURN SPACE N/A SPACE N/A
        (and selected value)  
list RETURN SPACE N/A N/A N/A(?)
drawnList RETURN SPACE N/A N/A N/A(?)


(?)
indicates possible inconsistent behavior in character list widgets. Note that you will probably also get this mode field in the cbs structure on the other callbacks (other than -callback).

Next topic: Other defined callbacks
Previous topic: Using callbacks and procedures

© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003