Interface defining the contract of reusable inline cell editors for
properties. Generally, this interface will be implemented
on a component subclass. Note
that such components do not have to be concerned about providing
a custom editor button for properties with custom property
editors. If needed, the rendering infrastructure will provide
one.
Inplace editors are designed to be reusable - that is, a single
instance may be reconfigured and reused to edit multiple properties
over its lifespan. The connect()
and clear()
methods provide a means of configuring an instance to represent a
property, and then de-configure it when it is no longer needed. The
typical lifecycle of an inplace editor is as follows:
- The
user clicks a property in the property sheet.
- The property
sheet identifies the property clicked, and locates the correct
inplace editor (either a default one or a custom implementation supplied
by the property or property editor).
connect()
is
called to configure the editor- The component returned from
getComponent()
is displayed on screen and given focus
- The user enters text or otherwise manipulates the component to change
the value
- When the component determines that the user has
either concluded editing (usually pressing Enter) or cancelled editing
(pressing Escape), the inplace editor fires
ACTION_SUCCESS
or ACTION_FAILURE
- The property sheet detects this
action event and removes the editor component
- The property sheet
updates the property
- The property sheet calls
clear()
to dispose of any state or references held by the inplace editor
If you implement this interface to provide a custom inplace
editor for a particular property, it is wise to also write a
custom PropertyEditor whose paint()
method will
paint an image identical to what your editor looks like when
it is instantiated. The simplest way to do this is to create
a renderer instance of your inplace editor, and use it in the
paint()
method of your property editor.
The methods of this interface should never
be called from any thread except the AWT event thread. The backing
implementation is not thread-safe. This includes ActionEvent
s
fired by instances of InplaceEditor
.
In no cases should an instance of InplaceEditor
attempt to directly update the value of the represented property
or property editor. If the property should be updated, ensure
that getValue()
will return the correct value, and
fire the action command COMMAND_SUCCESS. Implementations
should also not assume that because one of these events has been
fired, that therefore the property editor has been updated with
the new value. Components that display inplace editors
are responsible for the timing of and policy for updates to the represented
properties. Inplace editors merely display the contents of a property
editor, provide a way for the user to edit that value, and notify
the infrastructure when the user has made a change.
Standard implementations of this interface for text entry, combo
boxes and checkboxes are provided by the property sheet infrastructure.
There are several ways to provide a custom inplace editor for use in
the property sheet:
- Globally - a module supplying a
property editor implementing ExPropertyEditor for a given class may call
PropertyEnv.registerInplaceEditorFactory(InplaceEditor.Factory)
in its attachEnv()
method.
When the user invokes an editor operation, the returned inplace editor
will be used. - On a per-property basis - A
Node.Property
may provide a custom inplace editor via hinting.
To do this, the Node.Property
instance should return an
instance of InplaceEditor
from getValue
("inplaceEditor")
If both methods are used on the same property, the inplace editor provided
by the per-property hint takes precedence.