write-cell-value

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

This generic function may be called to write a value that the user has interactively entered into the grid cell defined by the row and column arguments back into an application's master data. The row-number and column-number arguments define which replication of replicated rows or columns is being addressed (see section-count).

Typically write-cell-value is called by a cell-click method or a cell-key-down method that has interpreted a new cell value from the end user's mouse or keyboard gesture. If the grid column uses one of the built-in grid-column classes such as editable-text-column-mixin, then the cell-click or cell-key-down method that is supplied with the built-in column class will call write-cell-value internally. Otherwise an application may supply custom cell-click or cell-key-down methods that call write-cell-value. The default write-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).

;; default write-cell-value method
(defmethod write-cell-value ((row grid-row)(column grid-column)
                             row-num column-num value)
  (declare (ignore row-num column-num))
  (let* ((data-object (data-object row)))
    (and data-object
         (let* ((data-writer (data-writer column)))
           (funcall (if (functionp data-writer)
                        data-writer
                      ;; This is needed for (setf foo) cases.
                      (fdefinition data-writer))
                    value 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-writer functions for the grid columns. For grids that do not fit the object-rows-and-attribute-columns paradigm, the application could either supply a write-cell-value method that writes grid data to the application in a custom way, or else not use write-cell-value at all in its cell-click and cell-key-down methods.

Verifying user-entered values in a write-cell-value method

Even if you can use the default write-cell-value method, you may still want to add your own method in order to validate the value that the user has entered, for example. Here is an example write-cell-value method that could be used with an editable-text-column-mixin column to allow the user to enter only integers.

(defmethod write-cell-value ((row my-grid-row)(column my-grid-column)
                             row-number column-number value)

  ;; Read a lisp object from the text that the user typed.
  ;; Alternately you could use a data-write-converter function
  ;; to convert the string.
  (let* ((object (ignore-errors (read-from-string value))))

    ;; Make sure that the object is an integer.
    (if* (integerp object)

            ;; Don't bother to write the integer to the master data
            ;; if it's equal to the current value.
       then (unless (= object
                       (read-cell-value row column
                                        row-number column-number))

              ;; Call the default write-cell-value method, which
              ;; will call this column's data-writer function on
              ;; this row's data-object.
              (call-next-method row column row-number column-number

                                ;; Pass the converted value explicitly
                                ;; if you didn't use a
                                ;; data-write-converter function.
                                object))

       else (pop-up-message-dialog
             nil "Invalid Value" "The value must be an integer."
             warning-icon "~OK"))))

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 write-cell-value method that uses these handy new arguments.

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

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.