object-editor

An object-editor is a specialized dialog subclass that makes it easier to create dialogs that edit instances of classes. Rather than creating individual widgets and giving them on-change functions and adding them to a dialog, you instead specify a single expression that parametrically describes the slots to be edited, and then the object-editor will automatically create widgets for those slots and arrange them on the dialog. An object-editor also offers a set of standard command buttons for viewing other instances, reverting the current changes, and so on.

Creating an object-editor dialog interactively is described in the document for the IDE's Class Interface Editor dialog. An extended programmatic example can be found in the essay Creating an Object-Editor Dialog or Class-Grid Programmatically.

Using an Object-Editor

To use an object-editor, there are three main properties that you need to set:

• The edited-class property: set it to the name of the class whose instances the dialog will display and/or edit.
• The edited-slots property: set it to an association list of slot names with editing parameters. The parameters for each slot specify what sort of value is in the slot and what kind of widget should edit them. This is the biggest step in creating an object-editor. See edited-slots for a full description of the format and options for this value. If the object-editor is being created as a form window in an IDE Project, then you can specify this large value interactively by using the IDE's Class Interface Editor dialog.
• The edited-instances property: set this only if you want the user to edit only a subset of the instances of the edited-class. In that case, set it to be a list of the instances that should be available to the user. Otherwise all instances will be available. If the edited-class is not a persistent (AllegroCache) class, then this list must be provided because all instances of a non-persistent class cannot be found automatically.

An object-editor will sort its edited-instances by the primary-name-slot and secondary-name-slot of the edited-class, if any, or else by the usual print names of the instances. It will display the first instance in the sorted listed automatically. The user may then use the command-buttons on the dialog to display and edit various instances, or the application can call display-instance in some other way.

How Slot Values Are Read and Written

When reading and writing slot values, an object-editor will call reader and writer functions of any direct slots that have reader and writer functions, and otherwise will call slot-value and (setf slot-value). Using reader and writer functions allows applications to perform their usual side effects as an object-editor accesses the slots. This is not done for non-direct slots, though, because it is not straightforward to find the reader and writer functions.)

Automatic Saving of User Edits

An object-editor will save changes to the currently displayed instance whenever a different instance is displayed or when object-editor-save is called. It will also do a save when a different window is selected if the save-on-clear-focus property is true, and do a save whenever an individual widget's value is changed if the save-on-new-widget-value property is true.

Finding the Object-Editor that a Widget Is On

If you add custom widgets to an object-editor form window in an IDE project, and an on-change function of a custom widget needs to find the object-editor itself, then note that this will be the parent of the parent of the widget. The widget's parent will be an object-editor-pane, and it is the parent of that pane that would be the proper argument for functions that take an object-editor argument.

Other Object-Editor Functionality

To reject invalid slot values as soon as the user enters them, write one or more validate-edited-slot-value methods.

To customize the spacing of widgets on the dialog, create an instance of the layout-spacing class, specifying some of its spacing properties, and pass it as the value of the layout-spacing initarg when creating the object-editor.

See command-buttons for the list of standard command buttons that are available on an object-editor, and the exported functions that they call.

The function current-instance returns the instance that is currently being displayed.

A special table of all instances is included on the dialog if the include-table-of-all-instances property is true.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.