org.openide.explorer.propertysheet

Interface InplaceEditor

public interface InplaceEditor

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:

1. The user clicks a property in the property sheet.
2. 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).
3. connect() is called to configure the editor
4. The component returned from getComponent() is displayed on screen and given focus
5. The user enters text or otherwise manipulates the component to change the value
6. 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
7. The property sheet detects this action event and removes the editor component
8. The property sheet updates the property
9. 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 ActionEvents 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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	InplaceEditor.Factory A factory for inplace editor instances.

Field Summary

Fields

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.

Method Summary

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.

Field Detail

COMMAND_SUCCESS

static final 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.

See Also:

Constant Field Values

COMMAND_FAILURE

static final 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.

See Also:

Constant Field Values

Method Detail

connect

void connect(PropertyEditor pe,
             PropertyEnv env)

Connect this editor with a property editor. The 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.

Parameters:

pe - The property editor

env - An instance of PropertyEnv, if the editor is an instance of ExPropertyEditor, or null if it is not

getComponent

JComponent getComponent()

Returns the physical inplace editor component that should be displayed on-screen. Typical implementations of this interface are 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.

Returns:

The component that should be displayed to the user to edit the property

clear

void clear()

Dispose of any state and references to the property or value being edited, to avoid memory leaks due to held references. The property display code will call this once an inplace editor component has been closed. A call to this method should return the inplace editor to the state it is in after its constructor is called.

getValue

Object getValue()

Returns the value currently displayed or selected in the editor. This may or may not correspond to the current value of the Property being represented, and may not represent a valid final value for the property, but rather represents the edit in progress.

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.

Returns:

The value currently shown in the editor component provided by getComponent()

setValue

void setValue(Object o)

Set the value to be displayed in the inplace editor. Implementations should take care to avoid triggering a property change event in the property editor connected to this inplace editor. This method is used to restore the partial value of an editor in the case that some external event causes it to be temporarily removed.

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.

Parameters:

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 return

supportsTextEntry

boolean supportsTextEntry()

Indicates whether an inplace editor supports the direct entry of text or not. In particular, this method is used to support managing the background color of the editor component. The default selection color is used by the property sheet to indicate selection in the property sheet. Editors supporting text entry should not have their background color set to the default selection color, so that the user may distinguish selected text (which would otherwise have the same background color whether it were selected or not).

Returns:

True if the editor component supplied by getComponent() supports direct text entry by the user.

reset

void reset()

Restore the inplace editor to the value returned by the property editor's getValue() method, discarding any edits.

Throws:

NullPointerException - If called before a call to connect() or after a call to clear(), since in that case the property editor is null.

addActionListener

void addActionListener(ActionListener al)

Add an action listener to the InplaceEditor. Note that the source property for ActionEvents fired by an InplaceEditor must be an instance of InplaceEditor. The property sheet infrastructure will recognize two action commands: 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.

Parameters:

al - The action listener to add

removeActionListener

void removeActionListener(ActionListener al)

Remove an action listener from an InplaceEditor.

Parameters:

al - The action listener to remove

getKeyStrokes

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.

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.

Returns:

The keystrokes a container of the editor component should ignore even if they are mapped to actions in it.

getPropertyEditor

PropertyEditor getPropertyEditor()

Get the 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.

Returns:

The property editor this InplaceEditor represents

getPropertyModel

PropertyModel getPropertyModel()

Inplace editors cache the property model used to update a property value at the conclusion of editing. After a call to 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.

Returns:

The property model representing the property being edited

setPropertyModel

void setPropertyModel(PropertyModel pm)

Set the property model that should be updated in the event of a change.

Parameters:

pm - The property model this inplace editor will represent

isKnownComponent

boolean isKnownComponent(Component c)

Returns true if a component is one the inplace editor instantiated. The property sheet tracks focus and will close an inplace editor if focus is lost to an unknown component. Since inplace editors may instantiate popup components that can receive focus, if focus is lost while an inplace editor is open, the property sheet will query the current inplace editor to ensure that the recipient of focus is truly not a child of the inplace editor. For most InplaceEditor implementations, it is safe simply to return false from this method.

Parameters:

c - A component which has received focus

Returns:

True if the passed component was instantiated by the inplace editor as part of its normal operation (for example, a popup which is not a child of whatever is returned from getComponent()in the component hierarchy, but which is effectively part of the editor).