on-print

Arguments: dialog-item

Returns the value of the on-print event property of dialog-item. The value of the on-print property should be a function object or a function name (a symbol naming a function), or nil. nil means use princ-to-string.

The function which is the value of this property is called whenever the dialog-item's value is being formatted for display in the dialog-item. It is also called for each member of the dialog-item's range when the range is a list of possible values that are shown in the control. The function should accept one argument, which is the value itself, and should return a string to display in the dialog-item for that value. The default differs for various dialog-item classes, but is usually a standard print function such as princ-to-string.

Using an on-print function allows the value of a dialog-item to be a meaningful Lisp object while the visible control itself displays an arbitrary nicely-formatted string to represent it. This is particularly useful in controls that display a set of choices: when the user selects a value, there is no need to map from the selected string to a meaningful lisp object, since that lisp object will be the control's value.

Most dialog-items that can display strings implement on-print. In addition, a list-view-column object may be given an on-print function to format the values in a single column of a list-view control differently than other columns of the same control. And a combo-box-column-mixin grid-column may be a given an on-print function to format the values in its drop-down list of choices (though the value displayed in the actual cell is formatted by the column's data-read-converter).

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

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.