cell-widget

Arguments: grid-row grid-column row-number column-number

Returns a number of values that indicate which of the several built-in cell widgets should appear in particular grid-widget cells, and what attributes those widgets should have. The default method does nothing, so an application must add its own cell-widget methods in order to use the built-in cell widgets with this approach.

An alternative approach is to use the various widget-column-mixin subclasses along with the widget-row-mixin class. That approach is more object-oriented, but also limits the built-in cell widgets to particular columns for each type of widget.

The IDE's Navigator Dialog contains a complete example of the cell-widget approach, called Grid-widget: using built-in cell widgets in ARBITRARY cells.

The first value returned from a cell-widget method should be a keyword that indicates which type of widget to use in the cell that is indicated by the arguments to cell-widget. The possible values are :button, :static-text, :editable-text, :check-box, :combo-box, :lamp, and :pixmap. For more information on how each of these widgets works, please refer to the associated widget-column-mixin class shown below (even though these classes are not used at all when writing cell-widget methods):

• :button -- static-text-and-button-column-mixin
• :check-box -- check-box-column-mixin
• :combo-box -- combo-box-column-mixin
• :editable-text -- editable-text-column-mixin
• :static-text -- static-text-column-mixin
• :lamp -- lamp-column-mixin
• :pixmap -- pixmap-column-mixin

The rest of the multiple values that a cell-widget method should return supply various attributes of the cell's widget. These values depend on which type of widget is being used. Most of these values correspond to properties of the various widget-column-mixin subclasses, though the cell-widget approach does not use those mixin classes. Since the cell-widget approach has no grid-column object on which to hang these property values, we must return them as multiple values from cell-widget methods instead.

Here are the multiple values that a cell-widget method should return for each type of widget. This list includes links to the corresponding widget-column-mixin properties that they emulate, where applicable, for more information.

• For a static-text widget, return these values:
  1. the symbol :static-text
  2. the string to display in the cell, or else nil to defer to the read-cell-value method for the cell.
• For a button widget, return these values:
  1. the symbol :button
  2. the name of the function to run when the user presses the button (see button-function)
  3. a boolean value indicating whether the button should fill the cell (see button-fills-cell)
  4. a string or pixmap to draw in the cell, or else nil to defer to the read-cell-value method for the cell
  5. a background color for the button (see make-rgb) or else (more typically) nil to default to the cell-background-color method for the cell
  6. a boolean value indicating whether the pixmap (if the fourth returned value is a pixmap) should stretch to fill the button, rather than being drawn at its canonical size
• For a check-box widget, return these values:
  1. the symbol :check-box
  2. a string to display beside the check-box gadget (this value must be a string and not nil); the null string will center the gadget horizontally
  3. a boolean value indicating whether the user must click on the check-box gadget itself, rather than anywhere in the cell, to toggle the value (see click-must-be-on-gadget).
• For an editable-text widget, return these values:
  1. the symbol :editable-text
  2. a keyword indicating how type-in is initiated (see edit-start-trigger)
  3. a keyword indicating how type-in is terminated (see edit-end-trigger).
• For a combo-box widget, return these values:
  1. the symbol :combo-box
  2. a list of choices to display in the drop-down list (this is like the list that a range-reader function would return, but it must be a non-null list of choices)
  3. a boolean value indicating whether the user may type in a new value, rather than selecting from the list of choices
  4. a boolean value indicating whether to use a "real" combo-box for the list of choices rather than a pop-up-menu (see use-real-combo-box, though that option has been deprecated and so nil should always be returned here)
  5. a boolean value indicating whether the user must click on the drop-down arrow gadget itself, rather than anywhere in the cell, to show the list of choices (see click-must-be-on-gadget)
  6. a keyword indicating how type-in (if allowed) is initiated (see edit-start-trigger)
  7. a keyword indicating how type-in (if allowed) is terminated (see edit-end-trigger).
• For a lamp widget, return these values:
  1. the symbol :lamp
  2. a real lamp widget, created as usual with make-instance. Typically this widget will not also be used as a standalone lamp widget on a dialog, though it could be, and it may also be displayed by multiple grid cells, even in multiple grid-widgets.
• For a pixmap, return these values:
  1. the symbol :pixmap
  2. an association list that maps application values to pixmap names, as with the pixmap-alist property of a grid-column
  3. a boolean value indicating whether the pixmap should be stretched to fill the grid cell; see the stretching property
  4. a boolean value indicating whether the user is allowed to interactively cycle through the cell's set of pixmaps; see user-modifiable
  5. the name of a function to use for testing whether two application values are equivalent, as with the pixmap-value-test property; this value may be omitted to default it to widget-value-equal

These returned values cover only the properties that are unique to the built-in cell widgets. Other attributes of the cell will still be determined by general grid-widget generic functions such as read-cell-value, write-cell-value, cell-font, cell-background-color, cell-horizontal-justification, and so on. See the grid-widget class for a complete overview.

cell-widget methods may be called frequently, so to avoid generating a lot of garbage it is advisable to return static values rather than values that are newly consed on each call.

There is an example using cell-widget on the Examples tab of the Navigator Dialog.

See the grid-widget class for an overview of writing grid-widget code.

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.