define-property
Arguments:
name &rest args
&key reader writer accessor type dependent-properties initarg help-string remake editor-type read-only choices hidden repositioning
7.0 release note: the keyword argument called
:editor-mode
in earlier releases is now called
:editor-type
.
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.)
-
:type: a type-specifier indicating the type of values that are
allowed for this property. Any type-specifier may be used, such as the
symbol
integer
or the list (and integer
(satisfies evenp))
, just as with the type-specifier argument
to typep. This
type is used only by the IDE inspector, which will reject a value that
a user interactively enters for a property if the value is not of that
type.
-
:dependent-properties: a list of the names of other properties
whose values may change as a direct result of changing the value of
this property. This list is used only by the IDE inspector, which
will immediately update its display of any of these dependent
properties that exist for an inspected object whenever the user
interactively changes the value of this property.
-
: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: 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. (This argument was called
:editor-mode in releases prior to 7.0.) The 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 consistant
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.