IDocumentNavigator


1   /*BEGIN_COPYRIGHT_BLOCK
2    *
3    * This file is part of DrJava.  Download the current version of this project from http://www.drjava.org/
4    * or http://sourceforge.net/projects/drjava/
5    *
6    * DrJava Open Source License
7    * 
8    * Copyright (C) 2001-2005 JavaPLT group at Rice University (javaplt@rice.edu).  All rights reserved.
9    *
10   * Developed by:   Java Programming Languages Team, Rice University, http://www.cs.rice.edu/~javaplt/
11   * 
12   * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated 
13   * documentation files (the "Software"), to deal with the Software without restriction, including without limitation
14   * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and 
15   * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
16   * 
17   *     - Redistributions of source code must retain the above copyright notice, this list of conditions and the 
18   *       following disclaimers.
19   *     - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the 
20   *       following disclaimers in the documentation and/or other materials provided with the distribution.
21   *     - Neither the names of DrJava, the JavaPLT, Rice University, nor the names of its contributors may be used to 
22   *       endorse or promote products derived from this Software without specific prior written permission.
23   *     - Products derived from this software may not be called "DrJava" nor use the term "DrJava" as part of their 
24   *       names without prior written permission from the JavaPLT group.  For permission, write to javaplt@rice.edu.
25   * 
26   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
27   * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
28   * CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
29   * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
30   * WITH THE SOFTWARE.
31   * 
32   END_COPYRIGHT_BLOCK*/
33  
34  package edu.rice.cs.util.docnavigation;
35  
36  import java.util.*;
37  import java.awt.Container  ;
38  import java.awt.event.FocusEvent  ;
39  import java.awt.event.FocusListener  ;
40  
41  /** <code>IDocumentNavigator</code> provides a framework through which individual <code>IDocuments</code> can be 
42   *  navigated. */ 
43  public interface IDocumentNavigator<ItemT extends INavigatorItem> extends IAWTContainerNavigatorActor {
44    /** @return an AWT component which interacts with this document navigator */
45    public Container   asContainer();
46    
47    /** Adds an <code>IDocuemnt</code> to this navigator.
48     *  @param doc the document to be added into this navigator.
49     */
50    public void addDocument(ItemT doc);
51    
52    /** Adds an <code>INavigatorItem</code> into this navigator in a position relative to a given path.
53      * @param doc the document to be added into this navigator.
54      * @param path the relative path to insert this INavigatorItem at.
55      */
56    public void addDocument(ItemT doc, String   path);
57    
58    /** Returns the currently selected navigator item, or null if no navigator item is selected. */
59    public ItemT getCurrent();
60    
61    /** Returns the model lock for this navigator.  Only used for locking in code external to the implementing class. */
62    public Object   getModelLock();
63    
64    /** Removes a given <code>INavigatorItem<code> from this navigator. Removes all <code>INavigatorItem</code>s 
65     *  from this navigator that are "equal" (<code>.equals(...)</code>) to the passed argument. Any of the 
66     *  removed documents may be returned by this method.
67     *  @param doc the docment to be removed
68     *  @return doc a document removed from this navigator as a result of invoking this method.
69     *  @throws IllegalArgumentException if this navigator contains no document equal to the passed document.
70     */
71    public ItemT removeDocument(ItemT doc);
72    
73    /** Resets a given <code>INavigatorItem<code> in the tree.  This may affect the placement of the item or its 
74     *  display to reflect any changes made in the model.
75     *  @param doc the docment to be refreshed
76     *  @throws IllegalArgumentException if this navigator contains no document that is equal to the passed document.
77     */
78    public void refreshDocument(ItemT doc, String   path);
79    
80    /** Sets the active document as specified.
81     *  @param doc the document to select
82     */
83    public void setActiveDoc(ItemT doc);
84    
85    /** The following five operations impose a natural ordering on the documents in the navigator.
86     *  For lists, it is order of insertion. For trees, it is depth-first enumeration.
87     *  This convention supports operations setActiveNextDocument() in the global model of DrJava
88     *  @return the INavigatorItem which comes after doc
89     *  @param doc the INavigatorItem of interest
90     */
91    public ItemT getNext(ItemT doc);
92    
93    /** @return the INavigatorItem which comes before doc
94     *  @param doc the INavigatorItem of interest
95     */
96    public ItemT getPrevious(ItemT doc);
97    
98    /** @return the INavigatorItem which comes first in the enumeration
99     */
100   public ItemT getFirst();
101   
102   /** @return the INavigatorItem which comes last in the enumeration
103    */
104   public ItemT getLast();
105   
106   /** Returns all the <code>IDocuments</code> in the collection in enumeration order.
107    *  @return an <code>INavigatorItem<code> enumeration of this navigator's contents.
108    */
109   public Enumeration<ItemT> getDocuments();
110   
111   /** Tests to see if a given document is contained in this navigator.
112    *  @param doc the document to test for containment.
113    *  @return <code>true</code> if this contains a document "equal" (<code>.equals(...)</code> method)
114    *          to the passed document, else <code>false</code>.
115    */
116   public boolean contains(ItemT doc);
117   
118   /** Returns the number of <code>INavigatorItem</code>s contained by this <code>IDocumentNavigator</code>
119    *  @return the number of documents within this navigator.
120    */
121   public int getDocumentCount();
122   
123   /** Returns whether this <code>IDocumentNavigator</code> contains any <code>INavigatorItem</code>s.
124    *  @return <code>true</code> if this navigator contains one or more documents, else <code>false</code>.
125    */
126   public boolean isEmpty();
127   
128   /**Removes all <code>INavigatorItem</code>s from this <code>IDocumentNavigator</code>. */
129   public void clear();
130   
131   /** Adds an <code>INavigationListener</code> to this navigator. After invoking this method, the passed listener
132    *  will observe events generated this navigator.  If the provided listener is already observing this navigator
133    *  (<code>==</code>), no action is taken.
134    *  @param listener the listener to be added to this navigator.
135    */
136   public void addNavigationListener(INavigationListener<? super ItemT> listener);
137   
138   /** Removes the given listener from observing this navigator. After invoking this method, all observers watching
139    *  this navigator "equal" (<code>==</code>) will no longer receive observable dispatches.
140    *
141    * @param listener the listener to be removed from this navigator
142    */
143   public void removeNavigationListener(INavigationListener<? super ItemT> listener);
144   
145   /** Add FocusListener to navigator. */
146   public void addFocusListener(FocusListener   e);
147   
148   /** Remove FocusListener from navigator. */
149   public void removeFocusListener(FocusListener   e);
150   
151   /** Gets the FocustListeners. */
152   public FocusListener  [] getFocusListeners();
153   
154   /** Returns a collection of all listeners registered with this navigator.
155    *  @return the collection of nav listeners listening to this navigator.
156    */
157   public Collection<INavigationListener<? super ItemT>> getNavigatorListeners();
158   
159   /** Selects the document at the x,y coordinates of the navigator pane and makes it the active document.
160    *  @param x the x coordinate of the navigator pane
161    *  @param y the y coordinate of the navigator pane
162    */
163   public boolean selectDocumentAt(int x, int y);
164   
165   /** Visitor pattern hook method.
166    *  @param algo the algorithm to run on this navigator
167    *  @param input the input to the algorithm
168    */
169   public <InType, ReturnType> ReturnType execute(IDocumentNavigatorAlgo<ItemT, InType, ReturnType> algo, InType input);
170   
171   /** @return true if a group if INavigatorItems selected. */
172   public boolean isGroupSelected();
173   
174   /** @return true if the INavigatorItem is in the selected group, if a group is selected. */
175   public boolean isSelectedInGroup(ItemT i);
176   
177   /** Adds the top level group with the specified name and filter. */
178   public void addTopLevelGroup(String   name, INavigatorItemFilter<? super ItemT> f);
179   
180   /** Returns true if a top level group is selected, false otherwise. */
181   public boolean isTopLevelGroupSelected();
182   
183   /** Returns the name of the top level group that is selected, throws
184    *  a GroupNotSelectedException if a top level group is not selected
185    */
186   public String   getNameOfSelectedTopLevelGroup() throws GroupNotSelectedException;
187   
188   /** Switches the selection to the given INavigatorItem if the current selection is not already on an 
189    *  INavigatorItem.  Since it may be possible that the currently selected item in the navigator does not 
190    *  correspond to an INavigatorItem, this method forces the navigator to select an item that does; 
191    *  specifically the one given.  If the navigator already has an INavigatorItem selected, this method does
192    *  nothing.
193    *  @param i The suggested current INavigatorItem.
194    */
195   
196    public void requestSelectionUpdate(ItemT i);
197    
198    /** The standard swing repaint() method. */
199    public void repaint();
200    
201    /** Marks the next selection change as model-initiated (true) or user-initiated (false; default). */
202    public void setNextChangeModelInitiated(boolean b);
203   
204    /** @return whether the next selection change is model-initiated (true) or user-initiated (false). */
205    public boolean isNextChangeModelInitiated();
206    
207    /** The name of the client property that determines whether a change is model- or user-initiated. */
208    public static final String   MODEL_INITIATED_PROPERTY_NAME = "ModelInitiated";
209    
210 //   public static edu.rice.cs.util.Log LOG = new edu.rice.cs.util.Log("browser.txt", true);
211 }
212
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags