FoldOperation


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.spi.editor.fold;
21  
22  import javax.swing.text.BadLocationException  ;
23  import org.netbeans.api.editor.fold.Fold;
24  import org.netbeans.api.editor.fold.FoldHierarchy;
25  import org.netbeans.api.editor.fold.FoldType;
26  import org.netbeans.modules.editor.fold.FoldHierarchyTransactionImpl;
27  import org.netbeans.modules.editor.fold.FoldOperationImpl;
28  import org.netbeans.modules.editor.fold.SpiPackageAccessor;
29  
30  
31  /**
32   * Fold operation represents services
33   * provided to an individual fold manager.
34   * <br>
35   * Each manager has its own dedicated instance
36   * of fold operation.
37   *
38   * <p>
39   * There are three main services - creation of a new fold
40   * and adding or removing it from the hierarchy.
41   * <br>
42   * Adding and removing of the folds requires a valid transaction
43   * that can be obtained by {@link #openTransaction()}.
44   *
45   * @author Miloslav Metelka
46   * @version 1.00
47   */
48  
49  public final class FoldOperation {
50      
51      private static boolean spiPackageAccessorRegistered;
52  
53      static {
54          ensureSpiAccessorRegistered();
55      }
56      
57      private static void ensureSpiAccessorRegistered() {
58          if (!spiPackageAccessorRegistered) {
59              spiPackageAccessorRegistered = true;
60              SpiPackageAccessor.register(new SpiPackageAccessorImpl());
61          }
62      }
63      
64      private final FoldOperationImpl impl;
65      
66      private FoldOperation(FoldOperationImpl impl) {
67          this.impl = impl;
68      }
69   
70      
71      /**
72       * Create new fold instance and add it to the hierarchy.
73       * <br>
74       * The fold will either become part of the hierarchy directly or it will
75       * become blocked by another fold already present in the hierarchy.
76       * <br>
77       * Once the blocking fold gets removed this fold will be phyiscally added
78       * to the hierarchy automatically.
79       *
80       * <p>
81       * The fold is logically bound to the fold manager that uses this fold operation.
82       * <br>
83       * The fold can only be removed by this fold operation.
84       *
85       * @param type type of the fold to be assigned to the fold.
86       * @param description textual description of the fold that will be displayed
87       *  once the fold becomes collapsed.
88       * @param collapsed whether the fold should initially be collapsed or expanded.
89       * @param startOffset starting offset of the fold. The fold creates swing position
90       *  for the offset.
91       * @param endOffset ending offset of the fold. The fold creates swing position
92       *  for the offset.
93       * @param startGuardedLength &gt;=0 initial guarded area of the fold (starting at the start offset).
94       *  If the guarded area is modified the fold will be removed automatically.
95       * @param endGuardedLength &gt;=0 ending guarded area of the fold (ending at the end offset).
96       *  If the guarded area is modified the fold will be removed automatically.
97       * @param extraInfo arbitrary extra information specific for the fold being created.
98       *  It's not touched or used by the folding infrastructure in any way.
99       *  <code>null<code> can be passed if there is no extra information.
100      *  <br>
101      *  The extra info of the existing fold can be obtained by
102      *  {@link #getExtraInfo(org.netbeans.api.editor.fold.Fold)}.
103      *
104      * @return new fold instance that was added to the hierarchy.
105      */
106     public Fold addToHierarchy(FoldType type, String   description, boolean collapsed,
107     int startOffset, int endOffset, int startGuardedLength, int endGuardedLength,
108     Object   extraInfo, FoldHierarchyTransaction transaction)
109     throws BadLocationException   {
110         Fold fold = impl.createFold(type, description, collapsed,
111             startOffset, endOffset, startGuardedLength, endGuardedLength,
112             extraInfo
113         );
114         impl.addToHierarchy(fold, transaction.getImpl());
115         return fold;
116     }
117     
118     /**
119      * This static method can be used to check whether the bounds
120      * of the fold that is planned to be added are valid.
121      * <br>
122      * The conditions are:<pre>
123      *  startOffset &lt; endOffset
124      * </pre>
125      *
126      * <pre>
127      *  startGuardedLength &gt;= 0
128      * </pre>
129      *
130      * <pre>
131      *  endGuardedLength &gt;= 0
132      * </pre>
133      *
134      * <pre>
135      *  startOffset + startGuardedLength &lt;= endOffset - endGuardedLength
136      * </pre>
137      *
138      * @return true if the bounds are OK or false otherwise.
139      */
140     public static boolean isBoundsValid(int startOffset, int endOffset,
141     int startGuardedLength, int endGuardedLength) {
142         return (startOffset < endOffset)
143             && (startGuardedLength >= 0)
144             && (endGuardedLength >= 0)
145             && ((startOffset + startGuardedLength) <= (endOffset -endGuardedLength));
146     }
147     
148     /**
149      * Remove the fold that is either present in the hierarchy or blocked
150      * by another fold.
151      *
152      * @param fold fold to be removed
153      * @param transaction non-null transaction under which the fold should be removed.
154      */
155     public void removeFromHierarchy(Fold fold, FoldHierarchyTransaction transaction) {
156         impl.removeFromHierarchy(fold, transaction.getImpl());
157     }
158     
159     /**
160      * Return extra info object passed to fold at time of its creation.
161      *
162      * @return extra information object specific for the fold
163      *  or null if there was no extra info.
164      */
165     public Object   getExtraInfo(Fold fold) {
166         return impl.getExtraInfo(fold);
167     }
168     
169     /**
170      * Check whether the starting guarded area of the fold
171      * is damaged by a document modification.
172      *
173      * @param fold fold to check. The fold must be managed by this fold operation.
174      * @return true if the starting area of the fold was damaged by the modification
175      *  or false otherwise.
176      */
177     public boolean isStartDamaged(Fold fold) {
178         return impl.isStartDamaged(fold);
179     }
180 
181     /**
182      * Check whether the ending guarded area of the fold
183      * is damaged by a document modification.
184      *
185      * @param fold fold to check. The fold must be managed by this fold operation.
186      * @return true if the ending area of the fold was damaged by the modification
187      *  or false otherwise.
188      */
189     public boolean isEndDamaged(Fold fold) {
190         return impl.isEndDamaged(fold);
191     }
192 
193     /**
194      * Open a new transaction over the fold hierarchy.
195      * <br>
196      * <b>Note:</b> Always use the following pattern:
197      * <pre>
198      *     FoldHierarchyTransaction transaction = operation.openTransaction();
199      *     try {
200      *         ...
201      *     } finally {
202      *         transaction.commit();
203      *     }
204      * </pre>
205      *
206      * @return opened transaction for further use.
207      */
208     public FoldHierarchyTransaction openTransaction() {
209         return impl.openTransaction().getTransaction();
210     }
211     
212     /**
213      * Check whether the fold is currently present in the hierarchy or blocked.
214      *
215      * @return true if the fold is currently present in the hierarchy or blocked
216      *  or false otherwise.
217      */
218     public boolean isAddedOrBlocked(Fold fold) {
219         return impl.isAddedOrBlocked(fold);
220     }
221     
222     /**
223      * Is the given fold blocked by another fold?
224      */
225     public boolean isBlocked(Fold fold) {
226         return impl.isBlocked(fold);
227     }
228     
229     /**
230      * Get the hierarchy for which this fold operations works.
231      */
232     public FoldHierarchy getHierarchy() {
233         return impl.getHierarchy();
234     }
235 
236     public boolean isReleased() {
237         return impl.isReleased();
238     }
239     
240     
241     private static final class SpiPackageAccessorImpl extends SpiPackageAccessor {
242 
243         public FoldHierarchyTransaction createFoldHierarchyTransaction(
244         FoldHierarchyTransactionImpl impl) {
245             return new FoldHierarchyTransaction(impl);
246         }
247         
248         public FoldHierarchyTransactionImpl getImpl(FoldHierarchyTransaction transaction) {
249             return transaction.getImpl();
250         }
251         
252         public FoldOperation createFoldOperation(FoldOperationImpl impl) {
253             return new FoldOperation(impl);
254         }
255         
256     }
257 }
258
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags