on-change

Arguments: dialog-item

Returns the value of the on-change event property of dialog-item. The value of the on-change property should be a function (function object or function name, such as a symbol) to be called when the dialog-item's value is changed. The application supplies this function to implement any side effects that should be done when the value changes. The on-change function will be called regardless of whether the value was changed interactively (by the user clicking on or typing into the component) or programmatically (via a call to (setf value)). The on-change function will not be called if the value is changed by calling initialize-value.

The value of on-change may be nil if no function needs to be called.

The function should take three arguments, which are (1) the control (i.e. dialog-item), (2) the new value of the control, and (3) the old (previous) value of the control.

The function should return true if the application accepts the new value. If it returns nil, then the previous value will automatically be restored to the control.

The function may also return a true second value to indicate that if the parent window is currently being invoked as a modal dialog, then the dialog should now exit, returning this dialog-item from the call to pop-up-modal-dialog that invoked the dialog.

The on-change function will only be called if the new value is different from the old value. The value of the on-change-test event property is a function which takes the old and new values as arguments and returns nil if they are different (and the on-change function should be called) and true if they are the same (and on-change should not be called).

on-change is distinct from on-click. For example, if the user clicks an item-list control on the value that is already selected, then the on-click function will be called but not the on-change function (assuming that the on-change-test function returns true, which it will if it has the default value widget-value-equal). On the other hand, if the value of a control is changed programmatically by application code, then the on-change function will be called but not the on-click function. For a button widget in particular, the value is arbitrarily toggled between t and nil when the button widget is successfully pressed, to cause the on-change function to be called.

If you would like to supply code that runs whenever the value changes in any instance of some widget class, you could add a widget-set-value  :after method.

Warning

For editable-text and multi-line-editable-text controls with the delayed property turned on (as it is by default for those controls), you should not move the keyboard focus from the parent dialog in an on-change handler, such as by calling select-window or pop-up-modal-dialog. The reason is that the on-change handler may be getting called due to the user clicking down on another widget, where the operating system may be waiting on the mouse button to be released, but the parent dialog will not receive the message for the mouse button release if the keyboard focus has been moved elsewhere.

See cg-events.htm for information about event handling in Common Graphics.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.