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
Class PropertyEnv

    java.lang.Object
      org.openide.explorer.propertysheet.PropertyEnv

    public class PropertyEnv

extends Object

PropertyEnv is a class which allows an object (such as a Node.Property instance) to communicate hints to property editor instances that affect the behavior or visual rendering of the property in a `PropertySheet` or `PropertyPanel` component. An instance of PropertyEnv is passed to the `attachEnv()` method of property editors implementing ExPropertyEditor. Such property editors may then call `env.getFeatureDescriptor().get("someHintString")` to retrieve hints that affect their behavior from the Node.Property object whose properties they are displaying.

The other purpose of the of this interface is to enable communication between the `PropertyEditor` and the `PropertySheet` or `PropertyPanel`. The custom property editor can get into a state when the visual state does not represent valid value and in such case needs to disable OK button. To handle that the property editor has to keep reference to its associated `PropertyEnv` and switch it into invalid state by calling `setState(`STATE_INVALID`)` as soon as the content of the custom property editor is invalid and then back by `setState(`STATE_VALID`)` when the custom property editor becomes valid once again. As a reaction to these calls the displayer of the custom property editor (for example dialog with OK button) is supposed to disable and re-enable the button.

Also it can happen that the property editor is complex and cannot decide whether the value is valid quickly. Just knows that it needs to be validated. For that purpose it wants to be informed when user presses the OK button and do the complex validation then. For that purpose there is the `STATE_NEEDS_VALIDATION` state. The property editor needs to use it and attach a listener to be notified when the user presses the OK button:

     class Validate implements VetoableChangeListener {
       public void vetoableChange(VetoableChangeEvent ev) throws PropertyVetoException {
         if (PROP_STATE.equals(ev.getPropertyName())) {
           if (!doTheComplexValidationOk()) {
             throw new PropertyVetoException(...);
           }
         }
         // otherwise allow the switch to ok state
       }
     }
     Validate v = new Validate();
     env.setState(STATE_NEEDS_VALIDATION);
     env.addVetoableChangeListener(v);

When the state is `STATE_NEEDS_VALIDATION` the OK button of the surrounding dialog shall be enabled and when pressed the vetoable listener notified about the expected change from `STATE_NEEDS_VALIDATION` to `STATE_VALID` which can either be accepted or vetoed.

Field Summary
`static String` | `PROP_STATE` Name of the state property.
`static Object` | `STATE_INVALID` One possible value for the setState/getState methods.
`static Object` | `STATE_NEEDS_VALIDATION` One possible value for the setState/getState methods.
`static Object` | `STATE_VALID` One possible value for the setState/getState methods.

Method Summary
`void` | `addPropertyChangeListener(PropertyChangeListener l)` Property change listener: listenning here you will be notified when the state of the environment is has been changed.
`void` | `addVetoableChangeListener(VetoableChangeListener l)` Vetoable change listener: listenning here you will be notified when the state of the environment is being changed (when the setState method is being called).
`Object[]` | `getBeans()` Array of beans that the edited property belongs to.
`FeatureDescriptor` | `getFeatureDescriptor()` Feature descritor that describes the property.
`Object` | `getState()` A getter for the current state of the environment.
`void` | `registerInplaceEditorFactory(InplaceEditor.Factory factory)` Register a factory for InplaceEditor instances that the property sheet should use as an inline editor for the property.
`void` | `removePropertyChangeListener(PropertyChangeListener l)` Removes Property change listener.
`void` | `removeVetoableChangeListener(VetoableChangeListener l)` Vetoable change listener removal.
`void` | `setState(Object newState)` A setter that should be used by the property editor to change the state of the environment.
`String` | `toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### PROP_STATE

    public static final String PROP_STATE

  Name of the state property.

  See Also:
    Constant Field Values

### STATE_VALID

    public static final Object STATE_VALID

  One possible value for the setState/getState methods. With this value the editor is in a valid state.

### STATE_NEEDS_VALIDATION

    public static final Object STATE_NEEDS_VALIDATION

  One possible value for the setState/getState methods. This one means that the editor does not know its state and it has to validate it later.

### STATE_INVALID

    public static final Object STATE_INVALID

  One possible value for the setState/getState methods. With this one the editor is in invalid state (Ok button on custom editor panel is disabled and an invalid glyph shown on the property panel).

Method Detail

### getBeans

    public Object[] getBeans()

  Array of beans that the edited property belongs to.

### getFeatureDescriptor

    public FeatureDescriptor getFeatureDescriptor()

  Feature descritor that describes the property. It is feature descriptor so one can plug in PropertyDescritor and also Node.Property which both inherit from FeatureDescriptor

### setState

    public void setState(Object newState)

  A setter that should be used by the property editor to change the state of the environment. Even the state property is bound, changes made from the editor itself are allowed without restrictions.

### getState

    public Object getState()

  A getter for the current state of the environment.

  Returns:
    one of the constants STATE_VALID, STATE_INVALID, STATE_NEEDS_VALIDATION.

### addVetoableChangeListener

    public void addVetoableChangeListener(VetoableChangeListener l)

  Vetoable change listener: listenning here you will be notified when the state of the environment is being changed (when the setState method is being called). You can veto the change and provide a displayable information in the thrown exception. Use the ErrorManager annotaion feature for the your exception to modify the message and severity.

### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener l)

  Property change listener: listenning here you will be notified when the state of the environment is has been changed.

  Since:
    2.20

### removeVetoableChangeListener

    public void removeVetoableChangeListener(VetoableChangeListener l)

  Vetoable change listener removal.

### removePropertyChangeListener

    public void removePropertyChangeListener(PropertyChangeListener l)

  Removes Property change listener.

  Since:
    2.20

### registerInplaceEditorFactory

    public void registerInplaceEditorFactory(InplaceEditor.Factory factory)

  Register a factory for InplaceEditor instances that the property sheet should use as an inline editor for the property. This allows modules to supply custom inline editors globally for a type. It can be overridden on a property-by-property basis for properties that supply a hint for an inplace editor using `getValue(String)`.

  See Also:
    `Node.Property`, `InplaceEditor`

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

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.