com.sun.javafx.beans.design.tool.DesignProperty Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of openjfx-78-backport Show documentation
This is a backport of OpenJFX 8 to run on Java 7.
The newest version!
/*
 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.javafx.beans.design.tool;

import com.sun.javafx.beans.metadata.PropertyMetaData;

/**
 * A DesignProperty represents a single property (setter/getter method pair) on a single instance
 * of a DesignBean at design-time.  All manipulation of properties at design-time should be done via
 * this interface.  This allows the IDE to both persist the changes as well as reflect them in the
 * design-time session.
 *
 * IMPLEMENTED BY THE IDE - This interface is implemented by the IDE for use by the
 * component (bean) author.
 *
 * @author Joe Nuxoll
 * @version 1.0
 * @see DesignBean#getProperties()
 * @see DesignBean#getProperty(String)
 */
public interface DesignProperty {

    /**
     * Returns the PropertyDescriptor associated with this DesignProperty
     *
     * @return the PropertyDescriptor associated with this DesignProperty
     */
    public PropertyMetaData getPropertyDescriptor();

    /**
     * Returns the DesignBean that this DesignProperty is associated with
     *
     * @return the DesignBean that this DesignProperty is associated with
     */
    public DesignBean getDesignBean();

    /**
     * Returns the current value of this DesignProperty.  The returned value is the *actual* value
     * that the design-time instance of the DesignBean has set for this property.
     *
     * @return the current value of this DesignProperty
     */
    public Object getValue();

    /**
     * Sets the current value of this DesignProperty.  This will set the *actual* value of this
     * property on the design-time instance of this DesignBean.  The associated PropertyEditor will
     * be used to produce the appropriate Java or markup code to set the property.  Calling this
     * method results in the persistence being written, and will cause the backing file buffer to
     * become "dirty".
     *
     * @param value The Object value to set as the current value of this property
     * @return true if the property setting was successful, false if it 
     *         was not
     * @see java.beans.PropertyEditor
     */
    public boolean setValue(Object value);

    /**
     * Returns the source-persistence String value of this property.  This is the value that
     * the associated PropertyEditor would use to persist the property's current value in source
     * code.
     *
     * @return the source-persistence String value of this property
     * @see java.beans.PropertyEditor#getJavaInitializationString()
     */
    public String getValueSource();

    /**
     * Sets the source-persistence String value for this property.  This is the value that will
     * actually appear in Java source code (or markup), depending on how the property setting is
     * persisted.
     *
     * @param source the source-persistence String value for this property
     * @return true if the property source setting was successful, false 
     *         if not
     */
    public boolean setValueSource(String source);

    /**
     * Returns the value that this property would have if it were unset.  This is the property's
     * original (default) state, which is determined by reading the property value on a fresh 
     * instance of the associated class (that owns this property).
     * 
     * @return The unset (default) value for this property
     */
    public Object getUnsetValue();

    /**
     * Removes the property setting (if it exists) from the source code, and reverts the property
     * setting back to its original (default) state.  The original state is determined by reading
     * the property value on a fresh instance of the associated class (that owns this property),
     * and reading the default value of the property.
     *
     * @return true if the unset operation was successful, false if not
     */
    public boolean unset();

    /**
     * Returns true if this DesignProperty has been modified from the 'default' value.
     * A 'modified' property is one that differs in value (== and .equals()) from a newly 
     * constructed instance of the DesignBean.
     *
     * @return true if this DesignProperty has been modified from the 'default' value, 
     *         false if not
     */
    public boolean isModified();
    
    /**
     * Returns true if this DesignProperty has been assigned a value. 
     * This method differs from {@link #isModified} in that a value may be set to the
     * default value, in which case {@link #isModified} would return false, and this method would return
     * true. However, a property which has not been defined will also not be modified, so !isDefined
     * implies !isModified.
     *
     * @return true is this DesignProperty has been assigned any value,
     *         false if not.
     */
    public boolean isDefined();

    /**
     * Returns the parent property that this property is a child of.  This may be null if this is
     * a top-level property.
     * 
     * @return Parent DesignProperty for this DesignProperty
     */
    public DesignProperty getParentProperty();

    /**
     * Returns an array of DesignProperty objects representing the sub-properties of this property
     * based on the static type of this property.
     *
     * @return An array of DesignProperty objects representing the sub-properties of this property
     */
    public DesignProperty[] getProperties();

    /**
     * Returns a single DesignProperty object representing the specified sub-property (by name).
     *
     * @param propertyName The name of the desired sub-property to retrieve.
     * @return The DesignProperty representing the desired property, or null if the specified 
     *         property does not exist as a child of this property.
     */
    public DesignProperty getProperty(String propertyName);

    /**
     * Returns a single DesignProperty object representing the specified sub-property (by descriptor).
     *
     * @param property The PropertyDescriptor of the desired sub-property to retrieve.
     * @return The DesignProperty representing the desired property, or null if the specified 
     *         property does not exist as a child of this property.
     */
    public DesignProperty getProperty(PropertyMetaData property);
}