defcomponent

Arguments: class-name superclass-names slot-specifiers &rest class-options

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

Defines a class that has properties, so as to effectively combine a defclass expression with an associated defproperties expression. defcomponent is similar to defclass, except that a :properties option may be specified as follows:

(defcomponent thing
  ((color ...)
   (size ...))
  (:default-initargs
   :color red
   :size 4)
  (:documentation "A silly class")
  (:properties
   (color
    :help-string "Color of the thing."
    :type rgb-or-nil
    :editor-type :color)
   (size
    :help-string "How big the thing is."
    :type positive-integer)
   ))

More examples are on the defproperties page.

The format of the properties option is similar to defproperties except that the symbol define-property is not needed at the beginning of the list for each property.

A property may define any of the following property facets, listed here with the initarg that is used to specify each:

• :reader: the name of a function for reading the property value. Defaults to the property name. (Always naming the property the same as the reader function is recommended.)
• :writer: the name of a function for writing the property value. Defaults to the setf of the property name. (Using the setf of the reader function for the writer is recommended.) If a separate writer function is provided, it should be written to perform any side effects that are needed to keep the object and its environment in a consistent state.

  Note on :reader and :writer: The name of the reader and writer functions for a property default to the name of the property and the setf of the name of the property respectively. But defining a property does not actually create the reader and writer functions for the property (regardless of whether the reader and writer names are specified explicitly), so the application must define these functions separately. Typically, a property is defined for a class and has the same name as a slot of the class, and the accessor methods that are created for the slot serve as the reader and writer of the property as well. Otherwise the reader and writer functions must be defined explicitly. See below for examples.

• :type: a lisp type that the property value must satisfy. The inspector will prevent invalid values from being used. Defaults to t, to allow any value.
• :dependent-properties: a list of the names of other properties of the object whose values might be changed by the writer function as side effects. The Inspector uses this to redisplay related properties whenever the user changes a property value in the inspector. (In general, the Inspector does not know automatically to redisplay values that have changed once it has inspected an object, and the Refresh Values command on the Inspector's right-button shortcut menu may be used to ensure that the displayed values are current.)
• :initarg: a keyword used by recreation-code to generate a lisp expression for recreating an object that has this property. Defaults to the keyword that has the same name as the property name symbol.
• :help-string: a short documentation string for the property, or nil. Defaults to nil.
• :editor-type: a value specifying which kind of extended editing will be used by the inspector for the property when the user clicks on the small button to the right of the value. (In releases prior to 7.0, this option was called :editor-mode.) Options are:
  • :long-expression: pops up a multi-line text editor. This is the default.
  • :multiple-choice: drops a list of choices.
  • :toggle: toggles between the choices when clicked. The default choices for :toggle are t and nil.
  • :color: pops up the color-selection dialog.
  • :font: pops up the font selection dialog.
  • :path: pops up the file selection dialog.
  • :menu: pops up the menu editor dialog.
  • :function: finds source code or generates skeleton code.
• :choices: a list of possible values for use by the inspector when the editor-type is :multiple-choice or :toggle. Defaults to nil, unless the editor-type is :toggle, in which case the default is a list of t and nil.
• :read-only: a flag to prevent modification of the property in the inspector. Defaults to nil.
• :remake: a flag to indicate that the object that has this property should be recreated when this property is modified in order to completely effect the change. Defaults to nil.
• :hidden: a flag to indicate that the inspector should not show this property. Useful when a property is inherited but is not useful on a particular subclass. Defaults to nil.
• :repositioning (for controls): a flag to indicate that the control may be moved or resized when this property value is modified. Used internally to update handles on forms when needed. Defaults to nil.

Properties of CLOS classes inherit similarly to slots. Only those facets that differ from the inherited property need be specified for a given class, and properties that have no differing facets need not be specified at all.

Properties are shown on a separate tab of the inspector, and thus can serve as a relatively high-level interface to the object by providing a selected subset of the object's internal attributes, where each property knows to either disallow modification or to cause appropriate side effects upon modification in order to maintain a consistent environment.

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.