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(1tcl), keylget(1tcl), keylkeys(1tcl), keylset(1tcl). 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(1tcl). 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)

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(?)

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