FoldManager (Editor Code Folding) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.spi.editor.fold
Interface FoldManager

public interface FoldManager

Fold manager maintains folds in the hierarchy for which it is constructed.
There can be multiple individually operating managers over a single fold hierarchy each managing its own set of folds.
The only time when the fold managers can collide is when they attempt to add overlapping folds into fold hierarchy.
In that case the fold from the manager with a higher priority (will be explained later) will be added to the hierarchy and the other one will remain outside of the hierarchy until the colliding fold will get removed from the hierarchy.
The priority of the manager (and all its folds) in the list of the managers for the particular hierarchy is defined by the order of the fold manager's factories in the layer (see FoldManagerFactory for more information).

The fold manager typically creates an initial set of folds during the initFolds(FoldHierarchyTransaction). Those folds typically mimic certain "primary data structure" e.g. java folds mimic certain AST nodes created by a java parser.
Typically the fold manager attaches a listener to a primary data structure and once it gets notified about its change it should rebuild the folds accordingly.
That set can later be modified upon notifications from primary data structure.

Upon notification the folds can be updated synchronously but that can potentially lead to deadlocks in case the view hierarchy (which shares the same lock with fold hierarchy) would access the primary data structure at the same time.
A safer approach is to remember the changes during notification from the primary data structure and schedule the updates to the fold hierarchy to be done independently.
Ideally the physical creation of folds should be done in EDT (Event Dispatch Thread) because there would be no risk of the document switching in the text component by JTextComponent.setDocument(javax.swing.text.Document).

Method Summary

void changedUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)
          Called by hierarchy upon the change in the underlying document.

void expandNotify(Fold expandedFold)
          Notify that the fold was expanded automatically by fold hierarchy infrastructure processing because its isExpandNecessary() return true.

void init(FoldOperation operation)
          Initialize this manager.

void initFolds(FoldHierarchyTransaction transaction)
          Initialize the folds provided by this manager.

void insertUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)
          Called by hierarchy upon the insertion to the underlying document.

void release()
          Notification that this manager will no longer be used by the hierarchy.

void removeDamagedNotify(Fold damagedFold)
          Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it was damaged by a document modification.

void removeEmptyNotify(Fold epmtyFold)
          Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it became empty (by a document modification).

void removeUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)
          Called by hierarchy upon the removal in the underlying document.

Method Summary
`void`	`changedUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)` Called by hierarchy upon the change in the underlying document.
`void`	`expandNotify(Fold expandedFold)` Notify that the fold was expanded automatically by fold hierarchy infrastructure processing because its `isExpandNecessary()` return true.
`void`	`init(FoldOperation operation)` Initialize this manager.
`void`	`initFolds(FoldHierarchyTransaction transaction)` Initialize the folds provided by this manager.
`void`	`insertUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)` Called by hierarchy upon the insertion to the underlying document.
`void`	`release()` Notification that this manager will no longer be used by the hierarchy.
`void`	`removeDamagedNotify(Fold damagedFold)` Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it was damaged by a document modification.
`void`	`removeEmptyNotify(Fold epmtyFold)` Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it became empty (by a document modification).
`void`	`removeUpdate(DocumentEvent evt, FoldHierarchyTransaction transaction)` Called by hierarchy upon the removal in the underlying document.

Method Detail

init

void init(FoldOperation operation)

Initialize this manager.

Parameters:: operation - fold hierarchy operation dedicated to the fold manager.

initFolds

void initFolds(FoldHierarchyTransaction transaction)

Initialize the folds provided by this manager.
The fold manager should create initial set of folds here if it does not require too much resource consumption.
As this method is by default called at the file opening time then it may be better to schedule the initial fold computations for later time and do nothing here.

Any listeners necessary for the maintenance of the folds can be attached here.
Generally there should be just weak listeners used to not prevent the GC of the text component.

Parameters:: transaction - transaction in terms of which the intial fold changes can be performed.

insertUpdate

void insertUpdate(DocumentEvent evt,
                  FoldHierarchyTransaction transaction)

Called by hierarchy upon the insertion to the underlying document.
If there would be any fold modifications required they may be added to the given transaction.

Parameters:: evt - document event describing the document modification.; transaction - open transaction to which the manager can add the fold changes.

removeUpdate

void removeUpdate(DocumentEvent evt,
                  FoldHierarchyTransaction transaction)

Called by hierarchy upon the removal in the underlying document.
If there would be any fold modifications required they may be added to the given transaction.

Parameters:: evt - document event describing the document modification.; transaction - open transaction to which the manager can add the fold changes.

changedUpdate

void changedUpdate(DocumentEvent evt,
                   FoldHierarchyTransaction transaction)

Called by hierarchy upon the change in the underlying document.
If there would be any fold modifications required they may be added to the given transaction.

Parameters:: evt - document event describing the document change.; transaction - open transaction to which the manager can add the fold changes.

removeEmptyNotify

void removeEmptyNotify(Fold epmtyFold)

Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it became empty (by a document modification).

removeDamagedNotify

void removeDamagedNotify(Fold damagedFold)

Notify that the fold was removed from hierarchy automatically by fold hierarchy infrastructure processing because it was damaged by a document modification.

expandNotify

void expandNotify(Fold expandedFold)

Notify that the fold was expanded automatically by fold hierarchy infrastructure processing because its isExpandNecessary() return true.

release

void release()

Notification that this manager will no longer be used by the hierarchy.
The folds that it maintains are still valid but after this method finishes they will be removed from the hierarchy.

This method is not guaranteed to be called. Therefore the manager must only listen weekly on the related information providers so that it does not block the hierarchy from being garbage collected.