| Allegro CL version 6.2 Unrevised from 6.1 | |||||||||
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 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 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 eql). 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 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-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.
| Allegro CL version 6.2 Unrevised from 6.1 | |||||||||