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 com.sun.rave.designtime.event.DesignBeanListener;
045:
046: /**
047: * <P>The DesignInfo interface is another type of BeanInfo interface to provide more live design-
048: * time functionality for a JavaBean. BeanInfo represents static meta-data about a JavaBean, while
049: * DesignInfo provides dynamic design-time behavior.</P>
050: *
051: * <P>To provide a DesignInfo for a JavaBean, a component author must provide an implementation
052: * of the DesignInfo interface available at design-time that matches the name of the JavaBean
053: * class with "DesignInfo" appended to it.</P>
054: *
055: * <P>For example, a component author may supply a JavaBean class named 'com.company.Donkey', and
056: * may also supply a corresponding 'com.company.DonkeyBeanInfo' (implements BeanInfo) as well as
057: * 'com.company.DonkeyDesignInfo' (implements DesignInfo). Note that these cannot be the same
058: * class, as there is no gaurantee that the supplied BeanInfo class will be the same instance that
059: * is used in the designer - typically, a BeanInfo class is 'deep-copied' into another instance
060: * inside of an IDE.</P>
061: *
062: * <P><B>IMPLEMENTED BY THE COMPONENT AUTHOR</B> - This interface is designed to be implemented by
063: * the component (bean) author. BasicDesignInfo is supplied for convenience for subclassing.</P>
064: *
065: * @author Joe Nuxoll
066: * @version 1.0
067: * @see com.sun.rave.designtime.impl.BasicDesignInfo
068: */
069: public interface DesignInfo extends DesignBeanListener {
070:
071: /**
072: * Returns the class type of the JavaBean that this DesignInfo was designed to work with
073: *
074: * @return The JavaBean's class type object
075: */
076: public Class getBeanClass();
077:
078: /**
079: * <p>Returns <code>true</code> if this child component (passed as 'childBean' and/or
080: * 'childClass') can be added as a child to the specified parent component (passed as
081: * 'parentBean'). This allows a component author to dynamically inspect the component hierarchy
082: * to determine if a particular component may be inserted.</p>
083: *
084: * <p>This method is called on the DesignInfo representing the childBean component any time a
085: * new component is being created, or dragged around in the visual designer.</p>
086: *
087: * <p>Note that the 'childBean' argument may be null if this operation is happening as a result
088: * of a fresh component drop from the palette. In that case, the child component instance will
089: * not be created until the actual drop happens, thus these checks must be done with only the
090: * child component's Class.</p>
091: *
092: * @param parentBean The DesignBean representing the potential parent component to receive the
093: * child
094: * @param childBean The DesignBean representing the potential child component that is being
095: * created or reparented. This argument may be null if this represents an initial drag
096: * from the palette, where the child bean has not been instantiated yet.
097: * @param childClass The Class object representing the potential child component that is being
098: * created or reparented.
099: * @return <code>true</code> if this parent bean is suitable for this child bean, or
100: * <code>false</code> if not
101: */
102: public boolean acceptParent(DesignBean parentBean,
103: DesignBean childBean, Class childClass);
104:
105: /**
106: * <p>Returns <code>true</code> if this child component (passed as 'childBean' and/or
107: * 'childClass') can be added as a child to the specified parent component (passed as
108: * 'parentBean'). This allows a component author to dynamically inspect the component hierarchy
109: * to determine if a particular component may be inserted.</p>
110: *
111: * <p>This method is called on the DesignInfo representing the parentBean component any time a
112: * new component is being created or dragged around in the visual designer.</p>
113: *
114: * <p>Note that the 'childBean' argument may be null if this operation is happening as a result
115: * of a fresh component drop from the palette. In that case, the child component instance will
116: * not be created until the actual drop happens, thus these checks must be done with only the
117: * child component's Class.</p>
118: *
119: * @param parentBean The DesignBean representing the potential parent component to receive the
120: * child
121: * @param childBean The DesignBean representing the potential child component that is being
122: * created or reparented. This argument may be null if this represents an initial drag
123: * from the palette, where the child bean has not been instantiated yet.
124: * @param childClass The Class object representing the potential child component that is being
125: * created or reparented.
126: * @return <code>true</code> if this child bean is suitable for this parent bean, or
127: * <code>false</code> if not
128: */
129: public boolean acceptChild(DesignBean parentBean,
130: DesignBean childBean, Class childClass);
131:
132: /**
133: * Provides an opportunity for a DesignInfo to setup the initial state of a newly created
134: * bean. Anything can be done here, including property settings, event hooks, and even the
135: * creation of other ancillary beans within the context. Note that this method is only called
136: * once after the component has been first created from the palette.
137: *
138: * @param designBean The bean that was just created
139: * @return A Result object, indicating success or failure and including messages for the user
140: */
141: public Result beanCreatedSetup(DesignBean designBean);
142:
143: /**
144: * Provides an opportunity for a DesignInfo to fix-up the state of a pasted bean. Anything can
145: * be done here, including property settings, event hooks, and even the creation of other
146: * ancillary beans within the context.
147: *
148: * @param designBean The bean that was just pasted from the clipboard
149: * @return A Result object, indicating success or failure and including messages for the user
150: */
151: public Result beanPastedSetup(DesignBean designBean);
152:
153: /**
154: * Provides an opportunity for a DesignInfo to cleanup just before a bean gets deleted.
155: * Anything can be done here, including property settings, event hooks, and even the
156: * creation/deletion of other ancillary beans within the context. Note, however, that this
157: * DesignBean will be deleted immediately upon the return of this method. This is intended for
158: * cleanup of ancillary items created in 'beanCreated'.
159: *
160: * @param designBean The bean that is about to be deleted
161: * @return A Result object, indicating success or failure and including messages for the user
162: */
163: public Result beanDeletedCleanup(DesignBean designBean);
164:
165: /**
166: * Returns the list (or hierarchy) of items to be included in a right-click context menu for
167: * this bean at design-time.
168: *
169: * @param designBean The DesignBean that a user has right-clicked on
170: * @return An array of DisplayAction objects representing a context menu to display to the user
171: */
172: public DisplayAction[] getContextItems(DesignBean designBean);
173:
174: /**
175: * This method is called when an object from a design surface or palette is being dragged 'over'
176: * a JavaBean type handled by this DesignInfo. If the 'sourceBean' or 'sourceClass' is of
177: * interest to the 'targetBean' instance or vice-versa (they can be "linked"), this method
178: * should return <code>true</code>. The user will then be presented with visual cues that this
179: * is an appropriate place to 'drop' the item and establish a link. If the user decides to drop
180: * the item on this targetBean, the 'linkBeans' method will be called. Note that the
181: * 'sourceBean' argument may be null if this drag operation is originating from the palette,
182: * because an instance of the bean will not have been created yet.
183: *
184: * @param targetBean The DesignBean instance that the user is 'hovering' the mouse over
185: * @param sourceBean The DesignBean instance that the user may potentially 'drop' to link - may
186: * be null if this drag operation originated from the palette, because the instance will
187: * not have been created yet
188: * @param sourceClass The class type of the object that the user may potentially 'drop' to link
189: * @return <code>true</code> if the 'targetBean' cares to have the 'sourceBean' or an instance
190: * of type 'sourceClass' linked to it, <code>false</code> if not
191: * @see linkBeans(DesignBean, DesignBean)
192: */
193: public boolean acceptLink(DesignBean targetBean,
194: DesignBean sourceBean, Class sourceClass);
195:
196: /**
197: * <P>This method is called when an object from a design surface or palette is being dropped or
198: * has been dropped 'on' a JavaBean type handled by this DesignInfo (to establish a link). This
199: * method will not be called unless the corresponding 'acceptLink' method call returned
200: * <code>true</code> for at least one of the beans involved. Typically, this results in new
201: * property settings on potentially both of the DesignBean objects.</P>
202: *
203: * @param targetBean The target DesignBean instance that the user has 'dropped' an object onto
204: * to establish a link
205: * @param sourceBean The DesignBean instance that has been 'dropped'
206: * @return A Result object, indicating success or failure and including messages for the user
207: * @see acceptLink(DesignBean, DesignBean, Class)
208: */
209: public Result linkBeans(DesignBean targetBean, DesignBean sourceBean);
210: }
|