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). 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.

The function 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.

Compatibility note: Through version 6.1, the default value for most widgets was eql, though for multi-item-list and list-view the default was equal. The change making the new default widget-value-equal for all controls may be backwardly incompatible in certain cases, but this is expected to be rare. Possible cases are a multi-item-list whose on-change-test had defaulted to equal, and which counted on equal to match two values that were each lists of lists, and some of the sublists were equal but not eq.

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.