Action Expressions and Callbacks

To define the action taken when a certain tile in a dialog box is selected, you associate an AutoLISP expression with that tile by calling the action_tile function. This is known as an action expression. Within the action expression, you often need access to attributes in the DCL file. The get_tile and get_attr functions provide this capability. The get_attr function retrieves the user-defined attributes within the DCL file. The get_tile function gets the current runtime value of a tile based on user input to that tile. Action expressions must be defined following the new_dialog call and before the start_dialog call.

Information relating to how the user has selected a tile or modified a tile's contents is returned to the action expression as a callback. In most cases, every active tile within a dialog box can generate a callback. As with reactors, the action expression that responds to the callback is often referred to as a callback function. This function should perform validity checking on the associated tile and should update information in the dialog box that pertains to the value of the tile. Updating the dialog box can include issuing an error message, disabling other tiles, and displaying the appropriate text in an edit box or list box.

Only the OK button (or its equivalent) should query the tile values to permanently save the settings that the user has finally selected. In other words, you should update the variables associated with tile values within the callback for the OK button, not the callback for an individual tile. If permanent variables are updated within the individual tile callbacks, there is no way to reset the values if the user selects the Cancel button. If the OK button's callback detects an error, it should display an error message and return focus to the tile in error; it should not exit the dialog box.

When a dialog box includes several tiles whose handling is similar, it can be convenient to associate those tiles with a single callback function. The principle of not committing to the user's changes until the user chooses OK still applies.

There are two ways to define actions other than calling action_tile. You can define a default action for the entire dialog box when you call new_dialog, and you can define an action by using a tile's action attribute. These alternative means of defining actions, and the order in which they occur, are described in Default and DCL Actions.