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: package org.netbeans.api.visual.anchor;
042:
043: import org.netbeans.modules.visual.util.GeomUtil;
044: import org.netbeans.api.visual.widget.ConnectionWidget;
045: import org.netbeans.api.visual.widget.Widget;
046:
047: import java.awt.*;
048: import java.util.List;
049: import java.util.EnumSet;
050: import java.util.Collections;
051: import java.util.ArrayList;
052:
053: /**
054: * This class represents an anchor for connections. An anchor is usually attached to widget and resolves a source or target
055: * point of a connection where it is used. Single instance of an anchor could be used by multiple entries. An entry represents
056: * the place where the anchor is used. An anchor can by attached to so-called proxy-anchor also.
057: * The proxy-anchor uses a set of anchor and allows smooth switching of the active anchor.
058: *
059: * @author David Kaspar
060: */
061: public abstract class Anchor implements Widget.Dependency {
062:
063: /**
064: * The set of all orthogonal directions.
065: */
066: public static final EnumSet<Direction> DIRECTION_ANY = EnumSet
067: .allOf(Direction.class);
068:
069: /**
070: * The direction of the anchor. Used by orthogonal routing alogorithms to resolve which way the path can be directed.
071: */
072: public enum Direction {
073: LEFT, TOP, RIGHT, BOTTOM
074: }
075:
076: private boolean attachedToWidget;
077: private Widget relatedWidget;
078: private ArrayList<Entry> entries = new ArrayList<Entry>();
079:
080: /**
081: * Creates an anchor that is related to a widget.
082: * @param relatedWidget the related widget; if null then the anchor is not related to any widget
083: */
084: protected Anchor(Widget relatedWidget) {
085: this .relatedWidget = relatedWidget;
086: }
087:
088: /**
089: * Called by ConnectionWidget to register the usage of the anchor.
090: * @param entry the anchor entry
091: */
092: public final void addEntry(Anchor.Entry entry) {
093: if (entry == null)
094: return;
095: notifyEntryAdded(entry);
096: entries.add(entry);
097: if (!attachedToWidget && entries.size() > 0) {
098: attachedToWidget = true;
099: if (relatedWidget != null)
100: relatedWidget.addDependency(this );
101: notifyUsed();
102: }
103: revalidateDependency();
104: }
105:
106: /**
107: * Called by ConnectionWidget to unregister the usage of the anchor.
108: * @param entry the anchor entry
109: */
110: public final void removeEntry(Entry entry) {
111: entries.remove(entry);
112: notifyEntryRemoved(entry);
113: if (attachedToWidget && entries.size() <= 0) {
114: attachedToWidget = false;
115: if (relatedWidget != null)
116: relatedWidget.removeDependency(this );
117: notifyUnused();
118: }
119: revalidateDependency();
120: }
121:
122: /**
123: * Registers multiple entries at once.
124: * @param entries a list of entries
125: */
126: public final void addEntries(List<Entry> entries) {
127: for (Entry entry : entries)
128: addEntry(entry);
129: }
130:
131: /**
132: * Unregisters multiple entries at once.
133: * @param entries a list of entries
134: */
135: public final void removeEntries(List<Entry> entries) {
136: for (Entry entry : entries)
137: removeEntry(entry);
138: }
139:
140: /**
141: * Returns a list of registered entries
142: * @return the list of entries
143: */
144: public final List<Entry> getEntries() {
145: return Collections.unmodifiableList(entries);
146: }
147:
148: /**
149: * Notifies when an entry is registered
150: * @param entry the registered entry
151: */
152: protected void notifyEntryAdded(Entry entry) {
153: }
154:
155: /**
156: * Notifies when an entry is unregistered
157: * @param entry the unregistered entry
158: */
159: protected void notifyEntryRemoved(Entry entry) {
160: }
161:
162: /**
163: * Returns whether the anchor is used.
164: * @return true if there is at least one entry registered
165: */
166: protected final boolean isUsed() {
167: return attachedToWidget;
168: }
169:
170: /**
171: * Notifies when the anchor is going to be used.
172: */
173: protected void notifyUsed() {
174: }
175:
176: /**
177: * Notifies when the anchor is going to be not used.
178: */
179: protected void notifyUnused() {
180: }
181:
182: /**
183: * Notifies when the anchor is going to be revalidated.
184: * @since 2.8
185: */
186: protected void notifyRevalidate() {
187: }
188:
189: /**
190: * This method is called by revalidation-change of related widget and notifies all entries about the anchor change.
191: */
192: public final void revalidateDependency() {
193: notifyRevalidate();
194: for (Entry entry : entries)
195: entry.revalidateEntry();
196: }
197:
198: /**
199: * Returns a related widget.
200: * @return the related widget; null if no related widget is assigned
201: */
202: public Widget getRelatedWidget() {
203: return relatedWidget;
204: }
205:
206: /**
207: * Returns a scene location of a related widget.
208: * @return the scene location; null if no related widget is assigned
209: */
210: public Point getRelatedSceneLocation() {
211: if (relatedWidget != null) {
212: Rectangle bounds = relatedWidget.getBounds();
213: if (bounds == null)
214: throw new IllegalStateException("Widget ("
215: + relatedWidget
216: + ") was not added into the scene");
217: return GeomUtil.center(relatedWidget
218: .convertLocalToScene(bounds));
219: }
220: assert false : "Anchor.getRelatedSceneLocation has to be overridden when a related widget is not used";
221: return null;
222: }
223:
224: /**
225: * Returns a scene location of a related widget of an opposite anchor.
226: * @param entry the entry to which the opposite anchor searched
227: * @return the scene location
228: */
229: public Point getOppositeSceneLocation(Entry entry) {
230: Anchor oppositeAnchor = entry.getOppositeAnchor();
231: return oppositeAnchor != null ? oppositeAnchor
232: .getRelatedSceneLocation() : null;
233: }
234:
235: /**
236: * Computes a result (position and direction) for a specific entry.
237: * @param entry the entry
238: * @return the calculated result
239: */
240: public abstract Result compute(Entry entry);
241:
242: /**
243: * Represents calculated scene location and orthogonal direction(s) of an anchor.
244: * Usually created within Anchor.compute method and used by Router.
245: */
246: public final class Result {
247:
248: private Point anchorSceneLocation;
249: private EnumSet<Anchor.Direction> directions;
250:
251: /**
252: * Creates a result with calculated scene location and single direction.
253: * @param anchorSceneLocation the scene location of an anchor
254: * @param direction the single direction of an anchor
255: */
256: public Result(Point anchorSceneLocation, Direction direction) {
257: this (anchorSceneLocation, EnumSet.of(direction));
258: }
259:
260: /**
261: * Creates a result with calculated scene location and possible directions.
262: * @param anchorSceneLocation the scene location of an anchor
263: * @param directions the possible directions of an anchor
264: */
265: public Result(Point anchorSceneLocation,
266: EnumSet<Direction> directions) {
267: this .anchorSceneLocation = anchorSceneLocation;
268: this .directions = directions;
269: }
270:
271: /**
272: * Returns a scene location of an anchor.
273: * @return the scene location
274: */
275: public Point getAnchorSceneLocation() {
276: return anchorSceneLocation;
277: }
278:
279: /**
280: * Returns possible directions of an anchor.
281: * @return the directions
282: */
283: public EnumSet<Direction> getDirections() {
284: return directions;
285: }
286:
287: }
288:
289: /**
290: * Represents a place where an anchor is used. Usually it is implemented by ConnectionWidget.getSourceAnchorEntry or
291: * ConnectionWidget.getTargetAnchorEntry or ProxyAnchor.
292: */
293: public interface Entry {
294:
295: /**
296: * Called for notifying that an anchor is changed and the entry has to me revalidated too.
297: * Usually called by Anchor.revalidateDependency.
298: */
299: void revalidateEntry();
300:
301: /**
302: * Returns a connection widget where the entry is attached to.
303: * @return the connection widget
304: */
305: ConnectionWidget getAttachedConnectionWidget();
306:
307: /**
308: * Returns whether an entry is attached to the source or the target of a connection widget.
309: * @return true if attached to the source
310: */
311: boolean isAttachedToConnectionSource();
312:
313: /**
314: * Returns an anchor of a connection widget which relates to the entry.
315: * @return the attached anchor
316: */
317: Anchor getAttachedAnchor();
318:
319: /**
320: * Returns an anchor of a connection widget which is opposite to the related anchor
321: * @return the opposite anchor
322: */
323: Anchor getOppositeAnchor();
324:
325: }
326:
327: }
|