Callback data structure

SCO Visual Tcl Reference Guide
Chapter 3, SCO Visual Tcl - graphical scripting language

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 (see the ``Keyed lists (TCLX)'' for further details). TclX provides commands to access and manipulate keyed lists. This keyed list contains information about the widget that invoked the callback and will minimally contain these keys:

widget: The name of the widget in which the event occurred.
dialog: The name of the form dialog in which the widget resides.

In addition, the callbacks specified with -callback option will have these 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

Contains a value indicating what caused the callback to activate. The value for this key is one of these (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 tabbing 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(VTCL) and VtDrawnList(VTCL). 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 button that is already selected.)

Additional information depending on the type of widget and callback may be put in the callback data. For example, the callback data for VtList(VTCL) contains the key selectedItemList, that contains a list of items selected.

Some additional widget-specific callback keys are provided for backward compatibility with earlier versions of SCO Visual Tcl. They are surrounded by brackets where they appear in the text. Use of these keys is deprecated; they may be withdrawn from a future release of SCO Visual Tcl.

To get access to the data corresponding to a key, use the command keylget. For example, to get access to the button which caused a pushbutton callback and the value passed to the callback, this code might be used:

   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 stimuli.

Value of ``mode'' keyedList field 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

 drawnList   N/A(?)                  MB1         N/A      N/A                 Up/Dwn Arrow
                                     SPACE                ( while in dlist)

∗: since <Enter> does not activate these from OSF/Motif 1.2
(1): uses -defaultCallback for this case
(?): missing finality (in drawnList)
Chg+LF: Change and LostFocus
MB1: single MouseBtn 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. You may also get this mode field in the cbs structure on the other callbacks ( other than -callback ).