read-cell-value

Arguments: row column row-number column-number

This generic function may be called to retrieve a value from an application's master data to display in the grid cell defined by the row and column arguments. The row-number and column-number arguments define which replication of replicated rows or columns is being addressed (see section-count).

Typically read-cell-value is called by a draw-cell method to find the value to draw in a particular cell. If the grid column uses one of the built-in grid-column classes such as editable-text-column-mixin, then the draw-cell method that is supplied with the built-in column class will call read-cell-value internally. Otherwise an application may supply custom draw-cell methods that call read-cell-value. The default read-cell-value method (shown below) assumes that the common grid paradigm is being used where each grid row represents a data object (such as an employee) and each grid column represents an attribute of those objects (such as an employee's department).

;; The default read-cell-value method
(defmethod read-cell-value ((row grid-row)(column grid-column)
                            row-number column-number)
  (declare (ignore row-number column-number))
  (let ((data-object (data-object row)))
    (and data-object
         (funcall (data-reader column)
                  data-object))))

The default method may be used for cells that fit this paradigm if the application has therefore supplied data-object values for the grid rows and data-reader functions for the grid columns. For grids that do not fit the object-rows-and-attribute-columns paradigm, the application could either supply a read-cell-value method that reads grid data from the application in a custom way, or else not use read-cell-value at all in its draw-cell methods.

For example, a draw-cell method to display a pixmap representing each employee's department could be written as follows (where the application has supplied a department-pixmap function):

(defmethod draw-cell ((row employee-row) (col department-column)
                      subrow-num subcolumn-num cell-box stream)
  (let* ((department (read-cell-value row column subrow-num subcolumn-num)))
    (copy-to-stream (department-pixmap department)
      stream cell-box)))

The above call to the default read-cell-value method depends on the grid row having a data-object (which would typically be an instance of the "employee" class), and on the grid column having a data-reader that is the name of a function, such as employee-department, that will return the department of that data-object. Alternately, since the above method already knows that the column is a department-column, instead of calling read-cell-value it could instead call (employee-department (data-object row)).

Compatibility note:

The row-number and column-number arguments are new to version 6.2. Applications that define methods on this generic function must add the new parameters to the method definitions. And any application calls to this generic function must pass the new arguments (just pass zeros to retain the old behavior). See the new example on the Examples tab of the Navigator dialog called Grid-widget: a basic replicated editable-text column to see how to write a read-cell-value method that uses these handy new arguments.

See also write-cell-value and the description of the grid-widget.

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