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(PropertyEnv.STATE_INVALID) as soon as the content of the custom property editor is invalid and then back by setState(PropertyEnv.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 PropertyEnv.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 PropertyEnv.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 PropertyEnv.STATE_NEEDS_VALIDATION to PropertyEnv.STATE_VALID which can either be accepted or vetoed.

Field Summary

Fields

Modifier and Type	Field and Description
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

Modifier and Type	Method and Description
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).
static PropertyEnv	create(FeatureDescriptor fd, Object... beans) Creates a PropertyEnv instance for given feature descriptor (property) and beans (nodes).
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

create

public static PropertyEnv create(FeatureDescriptor fd,
                                 Object... beans)

Creates a PropertyEnv instance for given feature descriptor (property) and beans (nodes). To be used for initializing property editors not managed by the property sheet classes.

Parameters:

fd - Feature descritor that describes the property.

beans - Objects that the edited property belongs to (typically its node).

Returns:

the created PropertyEnv instance

Since:

6.39

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