001: /*BEGIN_COPYRIGHT_BLOCK
002: *
003: * Copyright (c) 2001-2007, JavaPLT group at Rice University (javaplt@rice.edu)
004: * All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions are met:
008: * * Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * * Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * * Neither the names of DrJava, the JavaPLT group, Rice University, nor the
014: * names of its contributors may be used to endorse or promote products
015: * derived from this software without specific prior written permission.
016: *
017: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
018: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
019: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
020: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
021: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
022: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
023: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
024: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
025: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
026: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
027: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028: *
029: * This software is Open Source Initiative approved Open Source Software.
030: * Open Source Initative Approved is a trademark of the Open Source Initiative.
031: *
032: * This file is part of DrJava. Download the current version of this project
033: * from http://www.drjava.org/ or http://sourceforge.net/projects/drjava/
034: *
035: * END_COPYRIGHT_BLOCK*/
036:
037: package edu.rice.cs.util.docnavigation;
038:
039: import java.io.File;
040: import java.util.*;
041: import java.awt.Container;
042: import java.awt.event.FocusEvent;
043: import java.awt.event.FocusListener;
044:
045: /** <code>IDocumentNavigator</code> provides a framework through which individual <code>IDocuments</code> can be
046: * navigated. */
047: public interface IDocumentNavigator<ItemT extends INavigatorItem>
048: extends IAWTContainerNavigatorActor {
049: /** @return an AWT component which interacts with this document navigator */
050: public Container asContainer();
051:
052: /** Adds an <code>IDocuemnt</code> to this navigator.
053: * @param doc the document to be added into this navigator.
054: */
055: public void addDocument(ItemT doc);
056:
057: /** Adds an <code>INavigatorItem</code> into this navigator in a position relative to a given path.
058: * @param doc the document to be added into this navigator.
059: * @param path the relative path to insert this INavigatorItem at.
060: */
061: public void addDocument(ItemT doc, String path);
062:
063: /** Returns the currently selected navigator item, or null if no navigator item is selected. */
064: public ItemT getCurrent();
065:
066: /** Returns the model lock for this navigator. Only used for locking in code external to the implementing class. */
067: public Object getModelLock();
068:
069: /** Removes a given <code>INavigatorItem<code> from this navigator. Removes all <code>INavigatorItem</code>s
070: * from this navigator that are "equal" (<code>.equals(...)</code>) to the passed argument. Any of the
071: * removed documents may be returned by this method.
072: * @param doc the docment to be removed
073: * @return doc a document removed from this navigator as a result of invoking this method.
074: * @throws IllegalArgumentException if this navigator contains no document equal to the passed document.
075: */
076: public ItemT removeDocument(ItemT doc);
077:
078: /** Resets a given <code>INavigatorItem<code> in the tree. This may affect the placement of the item or its
079: * display to reflect any changes made in the model.
080: * @param doc the docment to be refreshed
081: * @throws IllegalArgumentException if this navigator contains no document that is equal to the passed document.
082: */
083: public void refreshDocument(ItemT doc, String path);
084:
085: /** Sets the active document as specified.
086: * @param doc the document to select
087: */
088: public void setActiveDoc(ItemT doc);
089:
090: /** The following five operations impose a natural ordering on the documents in the navigator.
091: * For lists, it is order of insertion. For trees, it is depth-first enumeration.
092: * This convention supports operations setActiveNextDocument() in the global model of DrJava
093: * @return the INavigatorItem which comes after doc
094: * @param doc the INavigatorItem of interest
095: */
096: public ItemT getNext(ItemT doc);
097:
098: /** @return the INavigatorItem which comes before doc
099: * @param doc the INavigatorItem of interest
100: */
101: public ItemT getPrevious(ItemT doc);
102:
103: /** @return the INavigatorItem which comes first in the enumeration
104: */
105: public ItemT getFirst();
106:
107: /** @return the INavigatorItem which comes last in the enumeration
108: */
109: public ItemT getLast();
110:
111: /** Returns all the <code>IDocuments</code> in the collection in enumeration order.
112: * @return an <code>INavigatorItem<code> enumeration of this navigator's contents.
113: */
114: public Enumeration<ItemT> getDocuments();
115:
116: /** Returns all the <code>IDocuments</code> contained in the specified bin.
117: * @param binName name of bin
118: * @return an <code>INavigatorItem<code> enumeration of this navigator's contents.
119: */
120: public Enumeration<ItemT> getDocumentsInBin(String binName);
121:
122: /** Tests to see if a given document is contained in this navigator.
123: * @param doc the document to test for containment.
124: * @return <code>true</code> if this contains a document "equal" (<code>.equals(...)</code> method)
125: * to the passed document, else <code>false</code>.
126: */
127: public boolean contains(ItemT doc);
128:
129: /** Returns the number of <code>INavigatorItem</code>s contained by this <code>IDocumentNavigator</code>
130: * @return the number of documents within this navigator.
131: */
132: public int getDocumentCount();
133:
134: /** Returns whether this <code>IDocumentNavigator</code> contains any <code>INavigatorItem</code>s.
135: * @return <code>true</code> if this navigator contains one or more documents, else <code>false</code>.
136: */
137: public boolean isEmpty();
138:
139: /**Removes all <code>INavigatorItem</code>s from this <code>IDocumentNavigator</code>. */
140: public void clear();
141:
142: /** Adds an <code>INavigationListener</code> to this navigator. After invoking this method, the passed listener
143: * will observe events generated this navigator. If the provided listener is already observing this navigator
144: * (<code>==</code>), no action is taken.
145: * @param listener the listener to be added to this navigator.
146: */
147: public void addNavigationListener(
148: INavigationListener<? super ItemT> listener);
149:
150: /** Removes the given listener from observing this navigator. After invoking this method, all observers watching
151: * this navigator "equal" (<code>==</code>) will no longer receive observable dispatches.
152: *
153: * @param listener the listener to be removed from this navigator
154: */
155: public void removeNavigationListener(
156: INavigationListener<? super ItemT> listener);
157:
158: /** Add FocusListener to navigator. */
159: public void addFocusListener(FocusListener e);
160:
161: /** Remove FocusListener from navigator. */
162: public void removeFocusListener(FocusListener e);
163:
164: /** Gets the FocustListeners. */
165: public FocusListener[] getFocusListeners();
166:
167: /** Returns a collection of all listeners registered with this navigator.
168: * @return the collection of nav listeners listening to this navigator.
169: */
170: public Collection<INavigationListener<? super ItemT>> getNavigatorListeners();
171:
172: /** Selects the document at the x,y coordinates of the navigator pane and makes it the active document.
173: * @param x the x coordinate of the navigator pane
174: * @param y the y coordinate of the navigator pane
175: */
176: public boolean selectDocumentAt(int x, int y);
177:
178: /** Returns true if the item at the x,y coordinate of the navigator pane is currently selected.
179: * @param x the x coordinate of the navigator pane
180: * @param y the y coordinate of the navigator pane
181: * @return true if the item is currently selected
182: */
183: public boolean isSelectedAt(int x, int y);
184:
185: /** Visitor pattern hook method.
186: * @param algo the algorithm to run on this navigator
187: * @param input the input to the algorithm
188: */
189: public <InType, ReturnType> ReturnType execute(
190: IDocumentNavigatorAlgo<ItemT, InType, ReturnType> algo,
191: InType input);
192:
193: /** @return the number of selected items. */
194: public int getSelectionCount();
195:
196: /** @return true if at least one group of INavigatorItems is selected. */
197: public boolean isGroupSelected();
198:
199: /** @return the number of groups selected. */
200: public int getGroupSelectedCount();
201:
202: /** @return the folders currently selected. */
203: public java.util.List<File> getSelectedFolders();
204:
205: /** @return true if at least one document is selected. */
206: public boolean isDocumentSelected();
207:
208: /** @return the number of documents selected. */
209: public int getDocumentSelectedCount();
210:
211: /** @return the documents currently selected. */
212: public java.util.List<ItemT> getSelectedDocuments();
213:
214: /** Returns true if the root is selected. Only runs in event thread. */
215: public boolean isRootSelected();
216:
217: /** @return true if the INavigatorItem is in a selected group, if
218: * at least one group is selected. */
219: public boolean isSelectedInGroup(ItemT i);
220:
221: /** Adds the top level group with the specified name and filter. */
222: public void addTopLevelGroup(String name,
223: INavigatorItemFilter<? super ItemT> f);
224:
225: /** Returns true if at least one top level group is selected, false otherwise. */
226: public boolean isTopLevelGroupSelected();
227:
228: /** Returns the names of the top level groups that the selected items descend from.
229: * Throws a GroupNotSelectedException if no top level group is selected
230: */
231: public java.util.Set<String> getNamesOfSelectedTopLevelGroup()
232: throws GroupNotSelectedException;
233:
234: /** Switches the selection to the given INavigatorItem if the current selection is not already on an
235: * INavigatorItem. Since it may be possible that the currently selected item in the navigator does not
236: * correspond to an INavigatorItem, this method forces the navigator to select an item that does;
237: * specifically the one given. If the navigator already has an INavigatorItem selected, this method does
238: * nothing.
239: * @param i The suggested current INavigatorItem.
240: */
241: public void requestSelectionUpdate(ItemT i);
242:
243: /** The standard swing repaint() method. */
244: public void repaint();
245:
246: /** Marks the next selection change as model-initiated (true) or user-initiated (false; default). */
247: public void setNextChangeModelInitiated(boolean b);
248:
249: /** @return whether the next selection change is model-initiated (true) or user-initiated (false). */
250: public boolean isNextChangeModelInitiated();
251:
252: /** The name of the client property that determines whether a change is model- or user-initiated. */
253: public static final String MODEL_INITIATED_PROPERTY_NAME = "ModelInitiated";
254:
255: // public static edu.rice.cs.util.Log LOG = new edu.rice.cs.util.Log("browser.txt", true);
256: }
|