PropertyEnv (NetBeans Explorer API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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()