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.markup;
043:
044: import com.sun.rave.designtime.DesignBean;
045: import com.sun.rave.designtime.DisplayAction;
046: import com.sun.rave.designtime.DisplayItem;
047: import com.sun.rave.designtime.Result;
048:
049: /**
050: * <p>A MarkupMouseRegion represents a portion (sub-region) of a markup component's rendered
051: * markup that has special design-time behavior. This special behavior may include a name,
052: * description, right-click context menu, and/or custom behavior in response to mouse clicks.
053: * </p>
054: *
055: * <p>An instance of MarkupMouseRegion is associated with a particular sub-region of markup via
056: * a unique attribute name-value pair. The 'MarkupDesignInfo.annoteRender' method adds the
057: * additional design-time only attributes to the markup, as well as supplies an array of these
058: * MarkupMouseRegion instances.</p>
059: *
060: * <P><B>IMPLEMENTED BY THE COMPONENT AUTHOR</B> - This interface is designed to be implemented by
061: * the component (bean) author. BasicMarkupMouseRegion is available for convenient subclassing.</P>
062: *
063: * @author Joe Nuxoll
064: * @version 1.0
065: * @see BasicMarkupMouseRegion
066: */
067: public interface MarkupMouseRegion extends DisplayItem {
068:
069: /**
070: * Returns an array of DisplayAction objects - used to render a right-click context menu when
071: * the user right-clicks on this mouse region.
072: *
073: * @return An array of DisplayAction objects
074: */
075: public DisplayAction[] getContextItems();
076:
077: /**
078: * Returns <code>true</code> if this markup region wishes to respond to a mouse click (or series
079: * of clicks).
080: *
081: * @return <code>true</code> if mouse clicks should be sent to this mouse region,
082: * <code>false</code> if not
083: * @see regionClicked(int)
084: */
085: public boolean isClickable();
086:
087: /**
088: * This method is called when a user clicks the mouse within the bounds of this mouse region.
089: * This method is only called if the 'isClickable()' method returns <code>true</code>.
090: *
091: * @param clickCount The count of mouse clicks
092: * @return A Result object
093: * @see isClickable()
094: */
095: public Result regionClicked(int clickCount);
096:
097: /**
098: * This method is called when an object from a design surface or palette is being dragged 'over'
099: * a region represented by this MarkupMouseRegion. If the 'sourceBean' or 'sourceClass' is of
100: * interest to the 'targetBean' instance or vice-versa (they can be "linked"), this method
101: * should return <code>true</code>. The user will then be presented with visual cues that this
102: * is an appropriate place to 'drop' the item and establish a link. If the user decides to drop
103: * the item on this targetBean, the 'linkBeans' method will be called. Note that the
104: * 'sourceBean' argument may be null if this drag operation is originating from the palette,
105: * because an instance of the bean will not have been created yet.
106: *
107: * @param targetBean The DesignBean instance that the user is 'hovering' the mouse over
108: * @param sourceBean The DesignBean instance that the user may potentially 'drop' to link - may
109: * be null if this drag operation originated from the palette, because the instance will
110: * not have been created yet
111: * @param sourceClass The class type of the object that the user may potentially 'drop' to link
112: * @return <code>true</code> if the 'targetBean' cares to have an instance of type 'sourceClass'
113: * linked to it, <code>false</code> if not
114: * @see linkBeans(DesignBean, DesignBean)
115: */
116: public boolean acceptLink(DesignBean targetBean,
117: DesignBean sourceBean, Class sourceClass);
118:
119: /**
120: * <P>This method is called when an object from a design surface or palette has been dropped
121: * 'on' a region represented by this MarkupMouseRegion (to establish a link). This method
122: * will not be called unless the corresponding 'acceptLink' method call returned
123: * <code>true</code>. Typically, this results in property settings on potentially both of the
124: * DesignBean objects.</P>
125: *
126: * @param targetBean The target DesignBean instance that the user has dropped an object onto to
127: * establish a link
128: * @param sourceBean The DesignBean instance that has been dropped.
129: * @return A Result object, indicating success or failure and including messages for the user
130: * @see acceptLink(DesignBean, DesignBean, Class)
131: */
132: public Result linkBeans(DesignBean targetBean, DesignBean sourceBean);
133: }
|