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
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 editor
getComponent()is displayed on screen and given focus
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
fired by instances of
In no cases should an instance of
attempt to directly update the value of the represented property
or property editor. If the property should be updated, ensure
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:
attachEnv()method. When the user invokes an editor operation, the returned inplace editor will be used.
Node.Propertymay provide a custom inplace editor via hinting. To do this, the
Node.Propertyinstance should return an instance of
|Modifier and Type||Interface and Description|
A factory for inplace editor instances.
|Modifier and Type||Field and Description|
Action command that tells the property sheet that editing is completed, but the value should not be updated, the editor should simply be removed.
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|
Add an action listener to the InplaceEditor.
Dispose of any state and references to the property or value being edited, to avoid memory leaks due to held references.
Connect this editor with a property editor.
Returns the physical inplace editor component that should be displayed on-screen.
Keystrokes that should be ignored by the containing component when this inplace editor is open, even if they are in the
Inplace editors cache the property model used to update a property value at the conclusion of editing.
Returns the value currently displayed or selected in the editor.
Returns true if a component is one the inplace editor instantiated.
Remove an action listener from an InplaceEditor.
Restore the inplace editor to the value returned by the property editor's
Set the property model that should be updated in the event of a change.
Set the value to be displayed in the inplace editor.
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)
PropertyEditorinstance 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
PropertyEnvinstance is passed to allow rendering hints to be passed to the
which may be connected to
that do not implement
ExPropertyEditor must handle
the case that the
env property may be null.
pe- The property editor
env- An instance of PropertyEnv, if the editor is an instance of ExPropertyEditor, or null if it is not
JComponentsubclasses which implement this interface and simply return
thisfrom 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
This method may return
String, in which case the property editor will be updated
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
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
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
InplaceEditorimplementation may return
getComponent()supports direct text entry by the user.
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_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 add
void removeActionListener(ActionListener al)
al- The action listener to remove
InputMapof 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.
java.beans.PropertyEditorinstance 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
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 represent
boolean isKnownComponent(Component c)
c- A component which has received focus
getComponent()in the component hierarchy, but which is effectively part of the editor).