on-change-test

Arguments: dialog-item

Returns the value of the on-change-test event property of dialog-item. The value of the on-change-test property should be a function object or a function name (a symbol naming a function), or nil. This function is called to determine whether an apparent change in the value of dialog-item should trigger a call to the on-change function. If no function is supplied (that is, on-change-test is nil), then no values are ever considered equivalent. (That can be useful for ensuring that the on-change function is always called, even when the value is set to its current value.)

The function (if any) should take two arguments, the old value and the new value.

The function should return nil if the values are different (returning nil is the definition of the values being different) and return true if the values are the same.

The initial value (for all widgets) is the function name widget-value-equal. When the two values being compared are both strings, then this function returns the result of calling string= on the two values; otherwise the result of calling eql on the values is returned. This special function is provided in order to match string values properly (so strings with identical characters will be considered the same), but without inefficiently recursing into deep trees or other complex widget values needlessly, as equal (which does consider strings with identical characters the same) might do.

The on-change-test is also used internally to find values in some kinds of controls. For example, when the value of an item-list control is set, the range of values is searched for the new value, using the on-change-test to test which range value is equivalent to the new value so that it may be selected.

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

Copyright (c) 1998-2006, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 7.0. has had minimal revisions compared to the 6.2 page.
Created 2005.9.20.