org.netbeans.modules.editor.fold/1 1.5.22

org.netbeans.api.editor.fold
Class FoldHierarchy

java.lang.Object
  extended by org.netbeans.api.editor.fold.FoldHierarchy

public final class FoldHierarchy
extends Object

Hierarchy of the folds for a single text component represents a model of the code-folding.
It is the main entry point into the Code Folding API.
Its instance can be obtained by get(javax.swing.text.JTextComponent).
The hierarhcy mainly provides access to the root fold by getRootFold() and allows to expand/collapse the folds and listen for fold events describing folds structure changes and state changes of any of the folds in the hierarchy.

Hierarchy is logically bound to view i.e. JTextComponent instead of the document model because if there would be two views over the same document then a particular fold can be collapsed in one view but uncollapsed in another.
It's up to the concrete fold implementations to possibly share some common information even on document model level e.g. java-related folds in multiple views over a single java source document can share the document-level parsing information.
On the other hand user-defined folds (e.g. by collapsing caret selection) will only be held for the component in which they were created.

Only one thread at the time can access the code folding hierarchy. Prior working with the hierarchy a document-level lock must be obtained first followed by call to render(Runnable) (or lock() for advanced uses) which ensure that the hierarchy gets locked exclusively.
The document lock can be either readlock e.g. by using Document.render(Runnable) or writelock e.g. when in DocumentListener) and must be obtained on component's document i.e. JTextComponent.getDocument() should be used.

The whole fold hierarchy related code expects that the document instances of the text component will subclass javax.swing.text.AbstractDocument.


Field Summary
static FoldType ROOT_FOLD_TYPE
          Fold type for the root fold.
 
Method Summary
 void addFoldHierarchyListener(FoldHierarchyListener l)
          Add listener for changes done in the hierarchy.
 void collapse(Collection c)
          Collapse all the folds contained in the given collection.
 void collapse(Fold f)
          Collapse the given fold.
 void expand(Collection c)
          Expand all the folds contained in the given collection.
 void expand(Fold f)
          Expand the given fold.
static FoldHierarchy get(JTextComponent component)
          Get the fold hierarchy for the given component.
 JTextComponent getComponent()
          Get the text component for which this fold hierarchy was created.
 Fold getRootFold()
          Get the root fold of this hierarchy.
 void lock()
          Lock the hierarchy for exclusive use.
 void removeFoldHierarchyListener(FoldHierarchyListener l)
          Remove previously added listener for changes done in the hierarchy.
 void render(Runnable r)
          Execute the given runnable over the exclusively locked hierarchy.
 void toggle(Fold f)
          Collapse the given fold if it's expanded and expand it if it's collapsed.
 String toString()
          Get a string description of the hierarchy for debugging purposes.
 void unlock()
          Unlock the hierarchy from exclusive use.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ROOT_FOLD_TYPE

public static final FoldType ROOT_FOLD_TYPE
Fold type for the root fold.

Method Detail

get

public static FoldHierarchy get(JTextComponent component)
Get the fold hierarchy for the given component. If the hierarchy does not exist yet it will get created.
The hierarchy will exist for the entire lifetime of the component. It is maintained as a client property of it.

Returns:
non-null fold hierarchy for the component.

render

public void render(Runnable r)
Execute the given runnable over the exclusively locked hierarchy.
Prior using this method the document must be locked. The document lock can be either readlock e.g. by using Document.render(Runnable) or writelock e.g. when in DocumentListener) and must be obtained on component's document i.e. JTextComponent.getDocument() should be used.

Parameters:
r - the runnable to be executed.

lock

public void lock()
Lock the hierarchy for exclusive use. This method must only be used together with unlock() in try..finally block.
Prior using this method the document must be locked. The document lock can be either readlock e.g. by using Document.render(Runnable) or writelock e.g. when in DocumentListener) and must be obtained on component's document i.e. JTextComponent.getDocument() should be used.

Note: The clients using this method must ensure that they always use this method in the following pattern:


     lock();
     try {
         ...
     } finally {
         unlock();
     }
 

See Also:
render(Runnable)

unlock

public void unlock()
Unlock the hierarchy from exclusive use. This method must only be used together with lock() in try..finally block.


collapse

public void collapse(Fold f)
Collapse the given fold.
Nothing is done if the fold is already collapsed.

Note: The hierarchy must be locked prior using of this method.

Parameters:
f - fold to be collapsed.

collapse

public void collapse(Collection c)
Collapse all the folds contained in the given collection.

Note: The hierarchy must be locked prior using of this method.

Parameters:
c - collection of the Folds to be collapsed. The folds must be present in this hierarchy.

expand

public void expand(Fold f)
Expand the given fold.
Nothing is done if the fold is already expanded.

Note: The hierarchy must be locked prior using of this method.

Parameters:
f - fold to be expanded.

expand

public void expand(Collection c)
Expand all the folds contained in the given collection.

Note: The hierarchy must be locked prior using of this method.

Parameters:
c - collection of the Folds to be collapsed. The folds must be present in this hierarchy.

toggle

public void toggle(Fold f)
Collapse the given fold if it's expanded and expand it if it's collapsed.

Note: The hierarchy must be locked prior using of this method.

Parameters:
f - fold which state should be toggled.

getComponent

public JTextComponent getComponent()
Get the text component for which this fold hierarchy was created.

Returns:
non-null text component for which this fold hierarchy was created.

getRootFold

public Fold getRootFold()
Get the root fold of this hierarchy.

Returns:
root fold of this hierarchy. The root fold covers the whole document and is uncollapsable.

addFoldHierarchyListener

public void addFoldHierarchyListener(FoldHierarchyListener l)
Add listener for changes done in the hierarchy.

Parameters:
l - non-null listener to be added.

removeFoldHierarchyListener

public void removeFoldHierarchyListener(FoldHierarchyListener l)
Remove previously added listener for changes done in the hierarchy.

Parameters:
l - non-null listener to be removed.

toString

public String toString()
Get a string description of the hierarchy for debugging purposes.
Like all other methods this one can only be used under locking conditions for the hierarchy.

Overrides:
toString in class Object

org.netbeans.modules.editor.fold/1 1.5.22

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.