PropertyPanel is a generic GUI component for displaying and editing a JavaBeans™ + * property or any compatible getter/setter pair for which there is a property editor + * available, in accordance with the JavaBeans specification. It makes it possible to + * instantiate an appropriate GUI component for a property and provides the plumbing + * between user interation with the gui component and calls to the getter/setter pair + * to update the value.
+ * + *The simplest way to use PropertyPanel is by driving it from an instance of
+ * PropertySupport.Reflection. To do that, simply pass the name of the
+ * property and an object with a getter/setter pair matching that property to the
+ * PropertySupport.Reflection's constructor, and pass the resulting instance of
+ * PropertySupport.Reflection to the PropertyPanel constructor.
A more efficient approach is to implement Node.Property or pass an existing Node.Property + * object to the PropertyPanel's constructor or PropertyPanel.setProperty - thus + * bypassing the use of reflection to locate the getter and setter.
+ * + *A note on uses of Node.Property and PropertyModel: PropertyPanel was + * originally designed to work with instances of PropertyModel, and has since been + * rewritten to be driven by instances of Node.Property. The main reason for this + * is simplification - there is considerable overlap between PropertyModel and + * Node.Property; particularly, DefaultPropertyModel and PropertySupport.Reflection + * effectively are two ways of doing exactly the same thing.
+ * + *Use of PropertyModel is still supported, but discouraged except under special
+ * circumstances. The one significant difference between Node.Property
+ * and PropertyModel is that PropertyModel permits listening for changes.
It is generally accepted that GUI components whose contents unexpectedly change
+ * due to events beyond their control does not tend to lead to quality, usable user
+ * interfaces. However, there are cases where a UI will, for example, contain several
+ * components and modification to one should immediately be reflected in the other.
+ * For such a case, use of PropertyModel is still supported. For other cases,
+ * it makes more sense to use BeanNode and for the designer of the UI
+ * to make a design choice as to how to handle (if at all) unexpected changes happening to
+ * properties it is displaying. If all you need to do is display or edit a
+ * property, use one of the constructors that takes a Node.Property object or
+ * use setProperty. PropertyModel will be deprecated at some point
+ * in the future, when a suitable replacement more consistent with
+ * Node.Property is created.
Note:
+ * This method is primarily here for backward compatibility, and the single
+ * use case where it is truly desirable to have a GUI component which reflects
+ * changes made by some source other than itself. If you have used one
+ * of the constructors which takes a Node.Property instance
+ * or the setProperty method, this method will return a
+ * PropertyModel instance generated for the underlying Node.Property object.
+ * In such a case, the PropertyModel instance thus obtained will not
+ * fire changes due to changes made by calling setValue
+ * on the Node.Property. For details on why this is the case,
+ * see issue
+ * 37779.
*
- * @return Value of property model.
+ * @return Either the PropertyModel set in the constructor or via setModel,
+ * or a generated instance of PropertyModel which wraps the Node.Property
+ * which was set in the constructor or via setProperty.
*/
public PropertyModel getModel() {
return model;