| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: class-grid-or-object-editor
Returns the edited-slots property value of an object-editor
dialog or class-grid
widget. The value may be set when
creating either of those interface objects by passing the
edited-slots initarg, or anytime later by calling
(setf
edited-slots).
An edited-slots value is a high-level specification that tells an
object-editor
or class-grid
which slots of its
edited-class it should edit, and how it should edit each of those
slots. When the edited-slots
property is set, an object-editor
will create or update its widgets
as needed for editing those slots as specified, or a class-grid
will create or update
its grid columns.
When creating an object-editor
dialog as a form window in an IDE
project, or when creating a class-grid
on a form, the edited-slots value can
be specified interactively using the IDE's Class Interface Editor
dialog. Otherwise the expression must be specified programmatically
using the options documented here. For an extended example of
specifying an edited-slots
expression programmatically,
see Creating an
Object-Editor Dialog or Class-Grid Programmatically.
Here is small sample edited-slots value:
((last-name :edited-type (:variable-char) :width 120) (date-of-birth :edited-type (:date :yyyy/mm/dd)) (favorite-color :edited-type (:single-choice (:red :green :blue :yellow)) :on-print capitalize-object :label "Fave Color") (best-friend :edited-type (:class-instance patient) :width 140) ((best-friend date-of-birth) :label "Best Friend's Birth Date" :edited-type (:date :yyyy/mm/dd)))
An edited-slots value is a list where each element of the list describes how to edit a particular slot. We'll call these elements slot entries here. A slot entry is a list where the first element is a slot reference, and the rest of the list is an options plist.
A slot reference is either a slot name or a list of slot names. When
it is a slot name, it should be the name of a slot of the edited-class
of the object-editor
or
class-grid
. In that case,
the widget or grid column that is created will directly access that
slot of the displayed instances. When it is a list of slot names,
then the widget or grid column will indirectly access a slot of some
other object; see Editing Slots Indirectly below.
An options plist consists of alternating option keywords and option
values that determine how the generated user interface will edit a
particular slot. A special option is the
:edited-type
option that determines the type of
widget that will be used and such things as what choices it might
offer. Other options are generally geared toward the look and feel.
An :edited-type
value is a list where the first
element is a keyword that indicates which basic type of editing to
use, such as :variable-char
or
:class-instance
. The rest of the list contains
zero, one, or two parameters, depending on the basic type. Here is a
list of all of the basic editing types, their meanings, and what else
should be in the list for each type.
:static-text
- The value is displayed as a single
line of text of any length, and the user cannot modify the value.
There are no parameters. An object-editor
will use a static-text
widget, and a class-grid
will use a class-grid-static-text-column
with its single-line property set to true. If
the slot value is not a string, then princ-to-string is used to produce a string.
:static-text-multi-line
- the value is displayed as
multiple lines of text of any length, and the user cannot modify the
value. There are no parameters. An object-editor
will use a scrolling-static-text
widget, and a class-grid
will use a class-grid-static-text-column
with
its single-line property set
to nil
. If the slot value is not a string,
then princ-to-string is used
to produce a string.
:variable-char
- the value is displayed as a single
line of text of any length, and the user can modify the value. There
are no parameters. An object-editor
will use an editable-text
widget, and a class-grid
will use a class-grid-editable-text-column
.
:variable-char-multi-line
- the value is displayed
as multiple lines of text of any length, and the user can modify the
value. There are no parameters. An object-editor
will use a multi-line-editable-text
widget, and a class-grid
will use a class-grid-editable-text-column
.
:fixed-char
- the value is displayed as a single
line of text of a specific length, and the user can modify the value.
There is one parameter, which is the length of the string. An object-editor
will use an editable-text
widget with a template-string, and a class-grid
will use a class-grid-editable-text-column
with a template-string. The
:horizontal-justification
option defaults to
:left
.
:fixed-numeric
- the value is displayed as a single
line of text of a specific length, and the user can modify the value.
The user can enter only numerals, or a plus or minus character if the
:template-allows-sign
option is true and there are
no non-space characters to the left of the current position. There
are two parameters, the first being the number of digits before the
decimal point, and the second being the number of digits after the
decimal point. An object-editor
will use an editable-text
widget with a template-string, and a class-grid
will use a class-grid-numeric-editable-text-column
with a
template-string. The
:horizontal-justification
option defaults to
:right
.
:date
- the value is displayed as a single line of
text of a specific length, and the user can modify the value. There
is one parameter, which is a keyword indicating the format of the date
string; possible values currently are :yyyy/mm/dd
,
:mm/dd/yyyy
, :mm/dd/yy
,
:dd/mm/yyyy
, and :dd/mm/yy
. The
user can enter only numerals. An object-editor
will use an editable-text
widget with a template-string, and a class-grid
will use a class-grid-editable-text-column
with a template-string. The
:horizontal-justification
option defaults to
:left
.
:boolean
- the value is displayed as nil
or true (which is anything other than nil
), and the user can toggle the value between
nil
and t
. There
are no parameters. An object-editor
will use a check-box
widget, and a class-grid
will use a class-grid-check-box-column
.
:single-choice
- the value is displayed as a single
line of text, with a dropping list of choices from which the user can
select a single choice. There is a single parameter, which is the
list of choices. An object-editor
will use a combo-box
widget, and a class-grid
will use a class-grid-combo-box-column
.
:multiple-choice
- the value is displayed as
selected items in a list of all choices. There is a single parameter,
which is the list of choices. An object-editor
will use a multi-item-list
with the simple-click-toggle property set to true. This
option is not implemented in a class-grid
.
:pixmap
- the value is displayed as a pixmap that
represents an associated slot value. The user can modify the value by
clicking the widget or grid cell, or by pressing the spacebar when the
widget or grid cell has the keyboard focus. This action changes the
pixmap to the next choice (cycling through all choices repeatedly as
needed) and sets up the associated user value to be written to the
slot (if confirmed, as usual). There may be either one or two
parameters. The first parameter is an association list that maps
arbitrary slot values to pixmaps. The first element of each alist
entry is an arbitrary slot value, and the second is the name of a
pixmap that has been cached by calling cache-pixmap. If the current slot value is not
in the alist, then no pixmap is drawn (the widget or grid cell will be
blank). A pixmap value may be nil
to not
draw a pixmap but still allow the user to set the slot to the
associated value by cycling to it as usual with the mouse or spacebar.
The (optional) second parameter may be nil
or
true, indicating whether the pixmap should stretch to fill the
available space in the widget or grid cell; it defaults to nil
to draw the pixmap at its normal size.
:static-pixmap
- like :pixmap
,
except that the user cannot modify the value interactively. Clicking
the pixmap or pressing the spacebar will have no effect.
:class-instance
- the value is expected to
be a class instance, and is displayed as a single line of text, with a
dropping list of choices from which the user can select a single
choice. There is one parameter, which is the name of the class of
which the slot holds an instance. A separate
:edited-instances
option may be a list of instances
to offer as choices. The primary-name-slot and/or secondary-name-slot of the class (if any) will
be used to find the string to display for each instance; otherwise the
class's print-object method
will be used. An object-editor
will use a combo-box
widget, and a class-grid
will use a class-grid-combo-box-column
.
:static-class-instance
- the value is
expected to be a class instance, and is displayed as a single line of
text, and the user cannot modify the value. There is one parameter,
which is the name of the class of which the slot holds an instance.
The primary-name-slot and/or
secondary-name-slot of the
class (if any) will be used to find the string to display for each
instance; otherwise the class's print-object method will be used. An object-editor
will use a static-text
widget, and a class-grid
will use a class-grid-static-text-column
.
:table-of-class-instances
- the value is expected
to be a list of class instances of a single class, and is displayed as
a table. There is one parameter, which is the name of the class of
the instances. A nested :edited-slots
option
should be passed to specify the columns of the table. An object-editor
will use a slot-editing-class-grid
. This
option is not implemented in a class-grid
. The user can edit the instances in
the class-grid
as with any
class-grid
, so static types
should be used for the columns if you don't want the end user to be
able to edit the instances indirectly in this table.
:lisp-type
- the value is displayed as a single
line of text that is printed via princ-to-string. The user can modify the text,
which is then read with the lisp reader to return a lisp object to
return to the slot. There is one parameter, which is the lisp type of
the values; it may be any lisp type, though only some types of lisp
values may be saved in an AllegroCache database. An object-editor
uses a lisp-text
widget, and a class-grid
uses a class-grid-lisp-text-column
.
Here are the options other than the special
:edited-type
option documented just above.
:label
- a string to display beside a widget in an
object-editor
or in a
column header of a class-grid
. If nil
or
unspecified, defaults to the name of the edited slot with dashes
converted to spaces and then each word capitalized.
:width
- the width of the widget or grid-column,
measured in pixels. If nil
or unspecified, a
default value will be used. For the fixed-length types, a default
width is computed that fits the number of characters in the
template-string. For the pixmap types, the default is 32. For the
:table-of-class-instances
type, the default is the
entire interior width of the object-editor
, minus the outer margins and any
room taken up by the table's helper buttons. For all other types, the
default is the layout-widget-width of the layout-spacing of an object-editor
, or the default-column-width of a class-grid
.
:height
- the height of the widget, measured in
pixels. Not applicable to class-grid
, where the body-row-height of the class-grid is always
used. If nil
or unspecified, a default value
will be used. For a multi-line widget, the default is the layout-multi-line-widget-height of the
layout-spacing of the object-editor
. For a single-line
widget, the default is the layout-single-line-widget-height of the layout-spacing of the object-editor
if that is
non-nil
, and otherwise a height that fits the
widget's font. For a type that is implemented as a combo-box
, the standard combo-box
height will be used (with a dropping list that's 200 pixels tall).
For the pixmap types, the default is 32. For the
:table-of-class-instances-type
, the default is the
layout-table-height of the
layout-spacing of the object-editor
.
:width-in-chars
- the width of the widget or
grid-column, measured in "m" characters. When true, this option takes
precedence over the :width
option.
:font
- the font to use in the widget or
grid-column. If nil
or unspecified, then a
default font is used according to the
:fixed-width-font
option.
:fixed-width-font
- used only when the
:font
option is nil
or
unspecified. A boolean value indicating whether the default font that
is used has fixed-width characters. If this option is specified as
true, then the global Common Graphics fixed-font is used. If this option is specified
as nil
, then the global Common
Graphics proportional-font is
used. If this option is not specified, then fixed-font is used for
the
:fixed-char
, :fixed-numeric
, and
:date
types and otherwise proportional-font is
used.
:help-string
- a string to display when the mouse
cursor is over the widget. This string will be displayed in the
status-bar of the nearest ancestor window that has a status-bar, if
any. If nil
or unspecified, then no string
is displayed.
:on-print
- a function that converts a user value
into a string to display. Its single argument should be the user
value, and it should return the string to display. If nil
or unspecified, this effectively defaults to
princ-to-string for values
that are not strings already.
:horizontal-justification
- one of the values
:left
, :center
, or
:right
. If unspecified, defaults to
:right
for the :fixed-numeric
type and otherwise to :left
. Applicable to the
types :static-text
,
:scrolling-static-text
,
:variable-char
,
:variable-char-multi-line
,
:fixed-char
, :fixed-numeric
,
:date
, :static-class-instance
,
and :lisp-type
.
:vertical-justification
- one of the values
:top
, :center
, or
:bottom
. If unspecified, defaults to
:center
. Applicable to all types in a class-grid
, for positioning within
a grid cell. Not applicable to object-editor
.
:sortable
- a boolean value indicating whether the
user can sort a class-grid
by the grid column for this slot. Not applicable to object-editor
. If unspecified, the
default is nil
.
:edited-instances
- a list of instances that are
offered as choices for the :class-instance
type.
When unspecified, all class instances will be displayed if the class is
persistent, and otherwise it is an error (because all instances cannot
be found). This option is not allowed on a form window in a project,
because the instances cannot be saved in the generated code to create
the running window.
:edited-slots
- applicable only to the
:table-of-class-instances
type, which is allowed
only on an object-editor
.
Specifies a nested edited-slots specification for the columns of a
class-grid widget that's on an object-editor
dialog.
:template-allows-sign
- applicable only to the
:fixed-numeric
type. A boolean value indicating
whether the user is allowed to type a plus or minus character to the
left of all non-whitespace characters. If unspecified, the default is
nil
.
:edit-start-trigger
- one of the values
:click
, :get-focus
, or
:begin-typing
, determining the user action that will
begin text editing in a grid cell. See edit-start-trigger. Applicable only to class-grid
, and only for the types
:fixed-numeric
, :fixed-char
,
:date
, :variable-char
, and
:variable-char-multi-line
. If unspecified, the
default is :click
. See edit-start-trigger.
:edit-end-trigger
- one of the values
:enter
or :enter-or-arrow-keys
,
determining the user action that will end text editing in a grid cell.
See edit-end-trigger.
Applicable only to class-grid
, and only for the types
:fixed-numeric
, :fixed-char
,
:date
, :variable-char
, and
:variable-char-multi-line
. If unspecified, the
default is :enter
. See edit-end-trigger.
When a slot reference is a list of slot names, the associated widget
or grid column will indirectly edit a slot of some object other than
the one being displayed by the object-editor
or class-grid
. It does this by taking the first
slot-name in the list and reading the value of that slot of the
displayed instance. If there are further slot names in the list, then
the value that was read is expected to be a first-class object (a
class instance), and the next slot in the list is read from that
object. That continues until the last slot is read.
For example, if an object-editor
is editing a patient, and the slot
reference for one of its widgets is (hospital ceo
phone-number)
, then the widget will read what should be a
hospital object from the hospital slot of the patient that the object-editor
is currently
displaying, then read a CEO object from the ceo slot of that hospital
object, and then read a value from the phone-number slot of that CEO
object. This will hopefully be the phone number of the CEO of the
hospital of the patient. If the user edits the value of the widget
and saves it, then this would change the CEO's phone number even
though the dialog is editing a patient. For that reason, it's
probably usually appropriate to use static (non-editable) widgets for
indirect slot references.
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.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |