| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
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.
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |