The callback reason, returned in the $reason variable, specifies why the action occurred. Its value is set for any kind of action, but you need to inspect it only when the action is associated with an edit_box, list_box, image_button, or slider tile. The following table shows the possible values:
|
Callback reason codes |
|
|---|---|
|
Code |
Description |
|
1 |
This is the value for most action tiles. The user has selected the tile (possibly by pressing ENTER, if the tile is the default and the platform recognizes accelerator keys). |
|
2 |
Edit boxes: The user has exited the edit box, but has not made a final selection. |
|
3 |
Sliders: The user has changed the value of the slider by dragging the indicator but has not made a final selection. |
|
4 |
List boxes and image buttons: This callback reason always follows a code 1. It usually means “commit to the previous selection.” It should never undo the previous selection; this confuses and annoys the user. |
Code 1 is described fully in the table. The following text describes the codes 2, 3, and 4 in greater detail.
The user has exited the edit box—by pressing the TAB key or by choosing a different tile—but has not made a final selection. If this is the reason for an edit box callback, your application should not update the value of the associated variable, but should check the validity of the value in the edit box.
The user has changed the value of the slider by dragging the indicator (or an equivalent action), but has not made a final selection. If this is the reason for a slider callback, your application should not update the value of the associated variable but should update the text that displays the slider's status. For more information, see Sliders. For code examples, see Handling Sliders.
The user has double-clicked on the list box. You can define the meaning of a double-click in your application. If the main purpose of the dialog box is to select a list item, a double-click should make a selection and then exit the dialog box. (In this case, the is_default attribute of the list_box tile should be true.) If the list box is not the primary tile in the dialog box, then a double-click should be treated as equivalent to making a selection (code 1).
List boxes that allow the user to select multiple items (multiple_select = true) cannot support double-clicking.
The user has double-clicked on the image button. You can define the meaning of a double-click in your application. In many cases it is appropriate for a single-click to select the button, but in others it is better for a single-click (or a keyboard action) to highlight the button, and then have the ENTER key or a double-click select it.
