defproperties

Arguments: class-name &rest properties

7.0 release note: the option called :editor-mode in earlier releases is now called :editor-type.

Defines a set of properties for a class. A property is an attribute of an object that defines a high-level means of accessing the attribute value. Properties are largely used by the inspector for editing objects that have properties, though they are useful programmatically as well mostly because a property defines how to cause any appropriate side effects when the property value is modified. A property for a CLOS object is typically based on a slot of the object, but properties are generally independent of any internal representation and can be defined for any lisp type. Properties are defined with define-property. The various property initargs are described on that page.

As an example, below is a part of the defproperties expression for the existing control class header-control. Here the properties are defined with define-property. (To make a defproperties form less verbose, each occurrence of the symbol define-property within the form may be excluded if desired, as shown is the second form.)

(defproperties header-control
 (define-property available
   :type boolean
   :editor-type :toggle)
 (define-property header-width
   :type positive-integer
   :reader default-header-width
   :writer (setf default-header-width)
   :editor-type :short-expression)
 (define-property header-justification
   :type justification
   :editor-type :multiple-choice
   :reader default-header-justification
   :writer (setf default-header-justification)
   :choices cg::justification-values)
 (define-property button-style
   :type boolean
   :editor-type :toggle
   :remake t)
 (define-property on-range-change
   :type event-handler
   :editor-type :function)
 (define-property on-set-focus
   :type event-handler
   :editor-type :function)
 )

;;  Here is the shorter form with define-property left out:

(defproperties header-control
 (available
   :type boolean
   :editor-type :toggle)
 (header-width
   :type positive-integer
   :reader default-header-width
   :writer (setf default-header-width)
   :editor-type :short-expression)
 (header-justification
   :type justification
   :editor-type :multiple-choice
   :reader default-header-justification
   :writer (setf default-header-justification)
   :choices cg::justification-values)
 (button-style
   :type boolean
   :editor-type :toggle
   :remake t)
 (on-range-change
   :type event-handler
   :editor-type :function)
 (on-set-focus
   :type event-handler
   :editor-type :function)
 )

Reader and writer examples. This includes examples of calls to defcomponent.

;; This example shows the typical case of defining properties 
;; for a standard-class, where the accessor methods that 
;; are automatically created for the size slot are also 
;; used by default as the reader and writer of the associated 
;; size property.  This technique of sharing
;; the name is recommended wherever it is feasible.

(defcomponent foo ()
  ((size :initarg :size
     :initform nil
     :accessor size))
  (:default-initargs
   :size :big)
  (:properties
   (size
    :help-string "How big it is."
    :type (member :big :medium :little nil)
    :editor-type :multiple-choice
    :choices '(:big :medium :little))))
(setq f (make-instance 'foo :size :little))
(inspect f)

;; ------------------------------------------------------
;; This example defines a property that computes its 
;; value each time it is read rather than reading a 
;; cached value from a slot.

(defcomponent yellow-item-list (single-item-list)
  ()
  (:default-initargs
   :background-color yellow)
  (:properties
   (how-many
    :read-only t)))
(defmethod how-many ((control yellow-item-list))
   (length (range control)))
(setq c (make-instance 'yellow-item-list
          :range '(a b c d)))
(inspect c)

;; -----------------------------------------------------------
;; This example does the same thing for an existing class, using
;; defproperties instead of defcomponent

(defproperties single-item-list
 (define-property how-many
   :read-only t))
(defmethod how-many ((control single-item-list))
   (length (range control)))
(setq d (make-instance 'single-item-list
          :range '(a b c d e)))
(inspect d)

;; -----------------------------------------------------------
;; This example demonstrates defining a property 
;; on a non-standard class, using an arbitrary place 
;; to hold the property values (since there is
;; no slot for the property).

(defproperties integer
    (define-property roundness))
(defparameter *integer-roundness* (make-hash-table))
(defmethod roundness ((integer integer))
   (gethash integer *integer-roundness* :unknown))
(defmethod (setf roundness)(value (integer integer))
   (setf (gethash integer *integer-roundness*) value))
(setf (roundness 6) :quite)
(inspect 5)
(inspect 6)

Properties in the Inspector

If the inspector should treat some instances of a class differently than other instances, that can be achieved by adding methods to one or more of the following generic functions: property-reader, property-writer, property-type, property-editor-type, property-choices, property-help-string, property-remake, property-read-only, and property-hidden.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.