public interface InplaceEditor
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:
connect()
is
called to configure the editorgetComponent()
is displayed on screen and given focusACTION_SUCCESS
or ACTION_FAILURE
clear()
to dispose of any state or references held by the inplace editorIf 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:
PropertyEnv.registerInplaceEditorFactory(InplaceEditor.Factory)
in its attachEnv()
method.
When the user invokes an editor operation, the returned inplace editor
will be used.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")
Modifier and Type | Interface and Description |
---|---|
static interface |
InplaceEditor.Factory
A factory for inplace editor instances.
|
Modifier and Type | Field and Description |
---|---|
static String |
COMMAND_FAILURE
Action command that tells the property sheet that editing
is completed, but the value should not be updated, the
editor should simply be removed.
|
static String |
COMMAND_SUCCESS
Action command that tells the property sheet to update
the property's value with the value from this inplace editor and close
the inplace editor.
|
Modifier and Type | Method and Description |
---|---|
void |
addActionListener(ActionListener al)
Add an action listener to the InplaceEditor.
|
void |
clear()
Dispose of any state and references to the property or value being
edited, to avoid memory leaks due to held references.
|
void |
connect(PropertyEditor pe,
PropertyEnv env)
Connect this editor with a property editor.
|
JComponent |
getComponent()
Returns the physical inplace editor component that should be displayed
on-screen.
|
KeyStroke[] |
getKeyStrokes()
Keystrokes that should be ignored by the containing component when
this inplace editor is open, even if they are in the
InputMap
of the container. |
PropertyEditor |
getPropertyEditor()
Get the
java.beans.PropertyEditor
instance associated with this
inplace editor. |
PropertyModel |
getPropertyModel()
Inplace editors cache the property model used to update a
property value at the conclusion of editing.
|
Object |
getValue()
Returns the value currently displayed or selected in the editor.
|
boolean |
isKnownComponent(Component c)
Returns true if a component is one the inplace editor instantiated.
|
void |
removeActionListener(ActionListener al)
Remove an action listener from an InplaceEditor.
|
void |
reset()
Restore the inplace editor to the value returned by the property editor's
getValue() method, discarding any edits. |
void |
setPropertyModel(PropertyModel pm)
Set the property model that should be updated in the event of a
change.
|
void |
setValue(Object o)
Set the value to be displayed in the inplace editor.
|
boolean |
supportsTextEntry()
Indicates whether an inplace editor supports the direct entry of text or not.
|
static final String COMMAND_SUCCESS
static final String COMMAND_FAILURE
void connect(PropertyEditor pe, PropertyEnv env)
PropertyEditor
instance will already be
initialized with the initial value, and if it is an
instance of ExPropertyEditor, ExPropertyEditor.attachEnv(env)
will already have been called. The PropertyEnv
instance is passed to allow rendering hints to be passed to
the InplaceEditor
instance. Implementations
which may be connected to PropertyEditor
instances
that do not implement ExPropertyEditor
must handle
the case that the env
property may be null.
pe
- The property editorenv
- An instance of PropertyEnv, if the editor is an instance of ExPropertyEditor,
or null if it is notJComponent getComponent()
JComponent
subclasses which implement this interface
and simply return this
from this method. If you
implement this interface separately from the inplace editor
component, it is expected that the same component instance
will be returned from this instance from the first time
connect()
is called, until such a time as clear()
is called.void clear()
Object getValue()
This method may return
a String
, in which case the property editor will be updated
using its setAsText()
method, and the value taken from the
property editor. Implementations are free to also return either null when
appropriate, a String appropriate for use with the property editor's
setAsText()
method, or an object instance compatible with the property in question's
setValue()
method.
getComponent()
void setValue(Object o)
This method is optional, and primarily useful for editors that support text entry. Editors which do not support text entry may supply an empty implementation of this method.
It is required that setValue()
for
a given InplaceEditor
be able to handle any possible
type that it can return from getValue()
, since it is
used to temporarily cache and then restore the value mid-edit.
o
- The value that should be displayed in the editor component. This
should be an object the component is capable of displaying. It may be
a String or any other object type, provided the component is capable
of displaying it. This method will only ever be called with a value
object supplied from getValue()
, so this method should
be compatible with anything that getValue()
on a given
InplaceEditor
implementation may returnboolean supportsTextEntry()
getComponent()
supports
direct text entry by the user.void reset()
getValue()
method, discarding any edits.NullPointerException
- If called before a call to connect()
or after a call to
clear()
, since in that case the property editor is null.void addActionListener(ActionListener al)
COMMAND_SUCCESS
and COMMAND_FAILURE
.
Other action events
(such as may be generated by a component subclass implementing
this interface) may be fired, but will be ignored by the
property sheet infrastructure.al
- The action listener to addvoid removeActionListener(ActionListener al)
al
- The action listener to removeKeyStroke[] getKeyStrokes()
InputMap
of the container.JTable (and potentially other components) will respond to keystrokes sent to an embedded component. In particular, this is a problem in JDK 1.4 with embedded JComboBoxes - the down arrow key, used for combo box navigation, also changes the selection and closes the editor. Since it is not always possible to determine reliably the keystrokes an inplace editor will consume at instantiation time, this allows them to be specified explicitly, so the table knows what to ignore.
PropertyEditor getPropertyEditor()
java.beans.PropertyEditor
instance associated with this
inplace editor. For efficiency, client code uses
this method to cache the property editor being
used, rather than perform gratuitous lookups of the
property editor on the property it represents.
Inplace editor implementations are expected to cache
the property editor they are initialized with until clear()
is called.PropertyModel getPropertyModel()
setPropertyModel()
this method should return the
property model that should be updated with the value from this
inplace editor. After a subsequent call to clear()
this method should return null. Under no circumstances should an InplaceEditor implementation attempt to modify the property model - this is the job of the infrastructure that instantiated the InplaceEditor.
void setPropertyModel(PropertyModel pm)
pm
- The property model this inplace editor will representboolean isKnownComponent(Component c)
c
- A component which has received focusgetComponent()
in the component
hierarchy, but which is effectively part of the editor).