Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.explorer 6.5.22 1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `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.

Nested Class Summary
`static interface` | `InplaceEditor.Factory` A factory for inplace editor instances.

Field Summary
`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
`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).

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.explorer 6.5.22 1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.