define-property

Macro

Package: common-graphics

Arguments: name &rest args&key reader writer accessor type dependent-properties initarg help-string remake editor-mode read-only choices hidden repositioning

Defines an individual property within a defproperties form. On the defproperties page, there is an example which contains examples of calls to define-property.

This macro defines a property but does not associate it with any class or object. 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.

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 the examples at the end of the defproperties entry.
:accessor: use instead of :read and :writer. Provides a reader and a setf method for the reader which works as a writer. Using the same name as the property is recommended. :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-mode: specifies 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. 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-mode is :multiple-choice or :toggle. Defaults to nil, unless the editor-mode 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 consistant environment.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.