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 whether each range value is equivalent to the new value so that it may be selected. If the item-list uses string values, for example, then the default on-change-test of eql will typically not find a new value in the range, since two strings are typically eql to each other (we say typically because there are cases when both as a constant string and thus are eq and thus eql). In this case, the on-change-test should be a function like string-equal that will return true for equivalent strings. (A more efficient approach may be to use symbols or other objects for which eql suffices, and use an on-print function to convert that object to the string to be displayed.)

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. This change may be backwardly incompatible in certain cases, but this is expected to be rare, such as 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.