list-view

Class

The class of the list-view control.

Control

The list-view control displays a table of textual information. It may include a row of buttons along the top that serve as column headers and which may be clicked in order to sort the rows of the list-view by the values that appear in any column. The column headers may also be stretched to change the width of individual columns.

The range property of a list-view is a list of list-view-item instances, each of which represents one row of data. The columns property contains a list of list-view-column instances, each of which represents one column of data and its header. Each list-view-item has a value-plist property that contains a value for each column of that row --- this value-plist is of the form (column-name value column-name value ...).

The list-view control supports icons and alternate layout styles. (The alternate layout styles are supported on the Windows platform only.) Refer to the documentation for the following symbols for more information: image-list, large-image-list, small-image-list, state-image-list, icon-index, state-icon-index, layout-style, alignment, auto-arrange, arrange-icons, list-view-item-position, open-image-list, close-image-list, image-list-open-p, and share-image-lists. On Windows only, see draggable-headers, full-row-select, and show-grid-lines.

Check boxes

On Windows, check boxes are supported for list-views. See show-check-boxes, checked, and on-check.

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

Example

Here is an example that shows how to create and modify a list-view widget programmatically. It creates a list-view with some initial items and displays it on a parent dialog, then adds a few more items and modifies the value of one of them.

(let* ((list-view
        
        ;; Make a list-view widget.
        (make-instance 'list-view
          
          ;; Where to place the list-view in its parent dialog.
          :left 20 :top 20 :width 300 :height 200
          
          ;; The initial columns of the list-view.
          :columns (list
                    (make-instance 'list-view-column
                      :name :flower
                      :title "Flower"
                      :justification :left
                      :width 144
                      :on-sort-predicate 'string<)
                    (make-instance 'list-view-column
                      :name :value
                      :title "Value"
                      :justification :center
                      :width 60
                      :on-sort-predicate '<)
                    (make-instance 'list-view-column
                      :name :rating
                      :title "Rating"
                      :width 80))
          
          ;; The initial rows of the list-view.
          :range (list
                  (make-instance 'list-view-item
                    :name :azalea
                    
                    ;; The value to display in each column
                    ;; for this row.
                    :value-plist
                    `(:flower "Azalea" :value 3700 :rating :low))
                  
                  (make-instance 'list-view-item
                    :name :dieffenbachia
                    :value-plist
                    `(:flower "Dieffenbachia" :value 23 :rating :high))
                  (make-instance 'list-view-item
                    :name :philodendron
                    :icon-index 1
                    :value-plist
                    `(:flower "Philodendron" :value 870 :rating :low))
                  (make-instance 'list-view-item
                    :name :spider-plant
                    :icon-index 1
                    :value-plist
                    `(:flower "Spider Plant" :value 9 :rating :medium)))
          
          ;; This row that will initially be selected.
          :value (list :dieffenbachia)
          
          ;; The set of icons that can be displayed at the left
          ;; of the rows.  The icon-index of each list-view-item
          ;; is an index into this set of pixmaps.
          ;; The :pixmap-names argument refers to pixmaps
          ;; that can be found from their names because
          ;; cache-pixmap was called on the pixmaps.
          :small-image-list (make-instance 'image-list
                              :name :sample-small
                              :pixmap-names
                              (list :default-closed-with-mask
                                    :default-leaf-with-mask))
          
          ;; The list-view will initially be sorted by this column.
          :sort-column :flower))
       
       ;; Make a parent dialog and put the list-view widget on it.
       (dialog (make-window :list-view-example
                 :class 'dialog
                 :interior (make-box-relative 200 200 340 240)
                 :dialog-items (list list-view))))
  (select-window dialog)
  
  ;; After the dialog has appeared, add a few more rows
  ;; one at a time.
  (dotimes (j 3)
    (sleep 1)
    (let* ((title (format nil "~:(~r~)" (1+ j))))
      (add-item list-view
                (make-instance 'list-view-item
                  :name (intern title :keyword)
                  :icon-index 0
                  :value-plist `(:flower ,title
                                 :value ,(* 10 (1+ j))
                                 :rating :medium)))))
  
  ;; Increase the value of the spider plant, and then select it.
  (sleep 1)
  (let* ((item (find-item list-view :spider-plant))
         (plist (value-plist item)))
    (incf (getf plist :value) 300)
    (setf (value-plist item) plist))
  (sleep 1)
  (setf (value list-view)(list :spider-plant))

  ;; Sort by the flower column again after adding the new items.
  (sleep 1)
  (setf (sort-column list-view) :flower)
  
  ;; Return the dialog.
  dialog)

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.