org.netbeans.api.editor.fold

Class FoldHierarchy

java.lang.Object

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 FoldHierarchy.get(javax.swing.text.JTextComponent).
The hierarhcy mainly provides access to the root fold by FoldHierarchy.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 FoldHierarchy.render(Runnable) (or FoldHierarchy.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

Fields

Modifier and Type	Field and Description
static FoldType	ROOT_FOLD_TYPE Fold type for the root fold.

Method Summary

Modifier and Type	Method and Description
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.
boolean	isActive() Determines whether the hierarchy can have some folds.
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 FoldHierarchy.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:

FoldHierarchy.render(Runnable)

unlock

public void unlock()

Unlock the hierarchy from exclusive use. This method must only be used together with FoldHierarchy.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

isActive

public boolean isActive()

Determines whether the hierarchy can have some folds. If the method returns false, there is no provider currently that could define folds. If true is returned, then there are 'just' no folds at the moment, but they could appear.

Note that provider may (dis)appear, so clients should subscribe their FoldHierarchyListener, and react if a Fold appears.

Returns:

false, if there is no FoldManager providing folds.

Since:

1.34