001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package com.sun.rave.designtime;
043:
044: import java.beans.PropertyChangeListener;
045: import java.awt.Component;
046:
047: /**
048: * <p>The Customizer2 interface describes a context-aware customizer for a JavaBean. A component
049: * author may wish to supply a customizer for their JavaBean, which is a dialog that pops up and
050: * provides a rich set of UI controls to manipulate the configuration of the entire JavaBean. This
051: * type of Customizer has significantly more access to the context that the JavaBean is being
052: * designed in, and thus allows for much greater functionality.</p>
053: *
054: * <p>The dialog title and icon will use the values from 'getDisplayName()' and 'getSmallIcon()'
055: * respectively.</p>
056: *
057: * <p>If a Customizer2 is apply capable (isApplyCapable() returns true), the host dialog will
058: * have three buttons: "OK", "Apply", and "Cancel" (and possibly "Help" if there is a helpKey).
059: * The 'isModified' method will be called each time a PropertyChangeEvent is fired to check if the
060: * "Apply" button should be enabled. When the user clicks "OK" or "Apply", the 'applyChanges'
061: * method is called. This implies that manipulations in the dialog are not directly affecting the
062: * DesignBean. The DesignBean should not be touched until 'applyChanges' has been called.</p>
063: *
064: * <p>If a Customizer2 is NOT apply capable (isApplyCapable() returns false), the host dialog
065: * will only have one button: "Done" (and possibly "Help" if there is a helpKey). The DesignBean
066: * may be manipulated at will in this dialog, as it is considered to be non-stateful. When the user
067: * clicks "Done", the 'applyChanges' method will be called.</p>
068: *
069: * <P><B>IMPLEMENTED BY THE COMPONENT AUTHOR</B> - This interface is designed to be implemented by
070: * the component (bean) author.</P>
071: *
072: * @author Joe Nuxoll
073: * @version 1.0
074: * @see java.beans.Customizer
075: */
076: public interface Customizer2 extends DisplayItem {
077:
078: /**
079: * Returns a UI panel (should be lightweight) to be displayed to the user. The passed in
080: * DesignBean is the design-time proxy representing the JavaBean being customized. This method
081: * will be called *every* time the Customizer2 is invoked.
082: *
083: * @param designBean the DesignBean to be customized
084: * @return a lightweight panel to display to the user
085: */
086: public Component getCustomizerPanel(DesignBean designBean);
087:
088: /**
089: * <p>If a Customizer2 is apply capable (isApplyCapable() returns true), the host dialog will
090: * have three buttons: "OK", "Apply", and "Cancel" (and possibly "Help" if there is a helpKey).
091: * The 'isModified' method will be called each time a PropertyChangeEvent is fired to check if
092: * the "Apply" button should be enabled. When the user clicks "OK" or "Apply", the
093: * 'applyChanges' method is called. This implies that manipulations in the dialog are not
094: * directly affecting the DesignBean. The DesignBean should not be touched until 'applyChanges'
095: * has been called.</p>
096: *
097: * <p>If a Customizer2 is NOT apply capable (isApplyCapable() returns false), the host dialog
098: * will only have one button: "Done" (and possibly "Help" if there is a helpKey). The DesignBean
099: * may be manipulated at will in this dialog, as it is considered to be non-stateful. When the
100: * user clicks "Done", the 'applyChanges' method will be called.</p>
101: *
102: * @return returns <code>true</code> if the customizer is stateful and is capable of handling
103: * an apply operation
104: * @see isModified()
105: * @see applyChanges()
106: */
107: public boolean isApplyCapable();
108:
109: /**
110: * Returns <code>true</code> if the customizer is in an edited state - to notify the customizer
111: * dialog that the "Apply" button should be activated.
112: *
113: * @return returns <code>true</code> if the customizer is in an edited state, <code>false</code>
114: * if not
115: */
116: public boolean isModified();
117:
118: /**
119: * Notifies the customizer that the user has clicked "OK" or "Apply" and the customizer should
120: * commit it's changes to the DesignBean.
121: *
122: * @return A Result object, indicating success or failure, and optionally including messages
123: * for the user
124: */
125: public Result applyChanges();
126:
127: /**
128: * Standard propertyChange events - 'null' property name indicates that the bean changed in
129: * some other way than just a property. An apply capable Customizer2 can use this as a hook
130: * to notify the host dialog that the 'modified' state has changed.
131: *
132: * @param listener The PropertyChangeListener to add
133: */
134: public void addPropertyChangeListener(
135: PropertyChangeListener listener);
136:
137: /**
138: * Standard propertyChange events - 'null' property name indicates that the bean changed in
139: * some other way than just a property. An apply capable Customizer2 can use this as a hook
140: * to notify the host dialog that the 'modified' state has changed.
141: *
142: * @param listener The PropertyChangeListener to remove
143: */
144: public void removePropertyChangeListener(
145: PropertyChangeListener listener);
146:
147: /**
148: * Standard propertyChange events - 'null' property name indicates that the bean changed in
149: * some other way than just a property. An apply capable Customizer2 can use this as a hook
150: * to notify the host dialog that the 'modified' state has changed.
151: *
152: * @return An array of PropertyChangeListener representing all the current listeners
153: */
154: public PropertyChangeListener[] getPropertyChangeListeners();
155: }
|