FoldHierarchy (NetBeans Code Folding API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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 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.