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. See the note about eq value below.)

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.

A note about eq value: why you might want the on-change-test function to always return nil

Suppose the value of a widget has contents subject to modification, such as a list. If you modify the elements of the list but do not create a new list, the old and new value will be eq and the default on-change-test function will see the old and new value as the same, behavior which you presumably do not want. In that case, nil is the appropriate value for the on-change-test: some efficiency is lost because the widget is always updated but no intended change is missed.

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.