org.netbeans.spi.editor.fold

Class FoldOperation

java.lang.Object

org.netbeans.spi.editor.fold.FoldOperation

public final class FoldOperation
extends Object

Fold operation represents services provided to an individual fold manager.
Each manager has its own dedicated instance of fold operation.

There are three main services - creation of a new fold and adding or removing it from the hierarchy.
Adding and removing of the folds requires a valid transaction that can be obtained by openTransaction().

Method Summary

Modifier and Type	Method and Description
Fold	addToHierarchy(FoldType type, int startOffset, int endOffset, Boolean collapsed, FoldTemplate template, String displayOverride, Object extraInfo, FoldHierarchyTransaction transaction) Adds a fold to the hierarchy.
Fold	addToHierarchy(FoldType type, String description, boolean collapsed, int startOffset, int endOffset, int startGuardedLength, int endGuardedLength, Object extraInfo, FoldHierarchyTransaction transaction) Deprecated. please use addToHierarchy(org.netbeans.api.editor.fold.FoldType, int, int, java.lang.Boolean, org.netbeans.api.editor.fold.FoldTemplate, java.lang.String, java.lang.Object, org.netbeans.spi.editor.fold.FoldHierarchyTransaction). This form of call does not support automatic state assignment and fold templates.
Iterator<Fold>	foldIterator() Enumerates all Folds defined by this Operation, in the document-range order.
Object	getExtraInfo(Fold fold) Return extra info object passed to fold at time of its creation.
FoldHierarchy	getHierarchy() Get the hierarchy for which this fold operations works.
boolean	isAddedOrBlocked(Fold fold) Check whether the fold is currently present in the hierarchy or blocked.
boolean	isBlocked(Fold fold) Is the given fold blocked by another fold?
static boolean	isBoundsValid(int startOffset, int endOffset, int startGuardedLength, int endGuardedLength) This static method can be used to check whether the bounds of the fold that is planned to be added are valid.
boolean	isEndDamaged(Fold fold) Check whether the ending guarded area of the fold is damaged by a document modification.
boolean	isReleased() Informs that the manager was released.
boolean	isStartDamaged(Fold fold) Check whether the starting guarded area of the fold is damaged by a document modification.
FoldHierarchyTransaction	openTransaction() Open a new transaction over the fold hierarchy.
boolean	owns(Fold fold) Check whether this fold operation has produced the given fold.
void	removeFromHierarchy(Fold fold, FoldHierarchyTransaction transaction) Remove the fold that is either present in the hierarchy or blocked by another fold.
Map<FoldInfo,Fold>	update(Collection<FoldInfo> infos, Collection<Fold> removed, Collection<FoldInfo> created) Performs refresh of folding information.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addToHierarchy

public Fold addToHierarchy(FoldType type,
                           String description,
                           boolean collapsed,
                           int startOffset,
                           int endOffset,
                           int startGuardedLength,
                           int endGuardedLength,
                           Object extraInfo,
                           FoldHierarchyTransaction transaction)
                    throws BadLocationException

Deprecated. please use addToHierarchy(org.netbeans.api.editor.fold.FoldType, int, int, java.lang.Boolean, org.netbeans.api.editor.fold.FoldTemplate, java.lang.String, java.lang.Object, org.netbeans.spi.editor.fold.FoldHierarchyTransaction). This form of call does not support automatic state assignment and fold templates.

Create new fold instance and add it to the hierarchy.
The fold will either become part of the hierarchy directly or it will become blocked by another fold already present in the hierarchy.
Once the blocking fold gets removed this fold will be phyiscally added to the hierarchy automatically.

The fold is logically bound to the fold manager that uses this fold operation.
The fold can only be removed by this fold operation.

Parameters:

type - type of the fold to be assigned to the fold.

description - textual description of the fold that will be displayed once the fold becomes collapsed.

collapsed - whether the fold should initially be collapsed or expanded.

startOffset - starting offset of the fold. The fold creates swing position for the offset.

endOffset - ending offset of the fold. The fold creates swing position for the offset.

startGuardedLength - >=0 initial guarded area of the fold (starting at the start offset). If the guarded area is modified the fold will be removed automatically.

endGuardedLength - >=0 ending guarded area of the fold (ending at the end offset). If the guarded area is modified the fold will be removed automatically.

extraInfo - arbitrary extra information specific for the fold being created. It's not touched or used by the folding infrastructure in any way. null can be passed if there is no extra information.
The extra info of the existing fold can be obtained by getExtraInfo(org.netbeans.api.editor.fold.Fold).

Returns:

new fold instance that was added to the hierarchy.

Throws:

BadLocationException

addToHierarchy

public Fold addToHierarchy(FoldType type,
                           int startOffset,
                           int endOffset,
                           Boolean collapsed,
                           FoldTemplate template,
                           String displayOverride,
                           Object extraInfo,
                           FoldHierarchyTransaction transaction)
                    throws BadLocationException

Adds a fold to the hierarchy. The description and the guarded start/end is taken from the 'template' FoldTemplate. As the fold template display is the most common override, the override string can be passed in 'displayOverride' (and will be used instead of template and instead of type's template).

The collapsed state can be prescribed, but can null can be passed to indicate the infrastructure should assign collapsed state based on e.g. user preferences. The exact assignment algorithm is left unspecified. Callers are recommended not to assign collapsed/expanded state explicitly.

Usually, it's OK to pass null for collapsed, template and possibly extraInfo.

Events produced by this add- call will be fired when the 'transaction' is committed. However fold hierarch will be changed immediately.

Parameters:

type - type of the fold, cannot be null

startOffset - starting offset

endOffset - end offset

collapsed - the initial collapsed state; if null, the state will be assigned automatically.

template - the FoldTemplate to use instead of default template of the type. null, if the type's template should be used.

extraInfo - arbitrary extra information specific for the fold being created. It's not touched or used by the folding infrastructure in any way. null can be passed if there is no extra information.
The extra info of the existing fold can be obtained by getExtraInfo(org.netbeans.api.editor.fold.Fold).

transaction - the transaction that manages events, cannot be null.

Returns:

the created Fold instance

Throws:

BadLocationException

Since:

1.35

isBoundsValid

public static boolean isBoundsValid(int startOffset,
                                    int endOffset,
                                    int startGuardedLength,
                                    int endGuardedLength)

This static method can be used to check whether the bounds of the fold that is planned to be added are valid.
The conditions are:

  startOffset < endOffset
 

  startGuardedLength >= 0
 

  endGuardedLength >= 0
 

  startOffset + startGuardedLength <= endOffset - endGuardedLength
 

Returns:

true if the bounds are OK or false otherwise.

removeFromHierarchy

public void removeFromHierarchy(Fold fold,
                                FoldHierarchyTransaction transaction)

Remove the fold that is either present in the hierarchy or blocked by another fold.

Parameters:

fold - fold to be removed

transaction - non-null transaction under which the fold should be removed.

owns

public boolean owns(Fold fold)

Check whether this fold operation has produced the given fold.

Parameters:

fold - non-null fold.

Returns:

true if this fold operation produced the given fold (by its addToHierarchy() method) or false otherwise.

getExtraInfo

public Object getExtraInfo(Fold fold)

Return extra info object passed to fold at time of its creation.

Returns:

extra information object specific for the fold or null if there was no extra info.

isStartDamaged

public boolean isStartDamaged(Fold fold)

Check whether the starting guarded area of the fold is damaged by a document modification.

Parameters:

fold - fold to check. The fold must be managed by this fold operation.

Returns:

true if the starting area of the fold was damaged by the modification or false otherwise.

isEndDamaged

public boolean isEndDamaged(Fold fold)

Check whether the ending guarded area of the fold is damaged by a document modification.

Parameters:

fold - fold to check. The fold must be managed by this fold operation.

Returns:

true if the ending area of the fold was damaged by the modification or false otherwise.

openTransaction

public FoldHierarchyTransaction openTransaction()

Open a new transaction over the fold hierarchy.
Note: Always use the following pattern:

     FoldHierarchyTransaction transaction = operation.openTransaction();
     try {
         ...
     } finally {
         transaction.commit();
     }
 

Returns:

opened transaction for further use.

isAddedOrBlocked

public boolean isAddedOrBlocked(Fold fold)

Check whether the fold is currently present in the hierarchy or blocked.

Returns:

true if the fold is currently present in the hierarchy or blocked or false otherwise.

isBlocked

public boolean isBlocked(Fold fold)

Is the given fold blocked by another fold?

getHierarchy

public FoldHierarchy getHierarchy()

Get the hierarchy for which this fold operations works.

isReleased

public boolean isReleased()

Informs that the manager was released. Use the method to check whether the FoldManager should be still operational. Once released, the FoldManager (and its Operation) will not be used again by the infrastructure.

Returns:

true, if release() was called on the manager

Since:

1.35

foldIterator

public Iterator<Fold> foldIterator()

Enumerates all Folds defined by this Operation, in the document-range order. Outer folds precede the inner ones. Folds, which overlap are enumerated strictly in the order of their starting positions.

The method may be only called under FoldHierarchy.lock(). The Iterator may be only used until that lock is released. After releasing the lock, the Iterator may fail.

Returns:

readonly iterator for all folds defined through this FoldOperation

Since:

1.35

update

public Map<FoldInfo,Fold> update(Collection<FoldInfo> infos,
                                 Collection<Fold> removed,
                                 Collection<FoldInfo> created)
                          throws BadLocationException

Performs refresh of folding information. The method will:

• remove Folds, which do not appear among the supplied FoldInfos
• add Folds, which do not exist, but are described by some FoldInfo
• attempt to update Folds, which match the FoldInfos

For each of the supplied FoldInfos, there should be at most 1 Fold either created or found existing, and no Folds without a corresponding input FoldInfo should remain in the hierarchy after the call. The mapping from the input FoldInfo to the corresponding Fold (created or found existing) is returned.

Note that Folds, which are blocked (e.g. by a higher-priority manager) will be added/removed/updated and returned as well. In order to find whether a specific Fold is blocked, please call isBlocked(org.netbeans.api.editor.fold.Fold).

If the removed or created parameters are not null, the removed Fold instances, or the FoldInfos that created new Folds will be put into those collection as a supplemental return value. The caller may then update its own data with respect to the changes and the current Fold set.

Note: The method may be only called under FoldHierarchy.lock(). This implies the document is also read-locked. The caller must check whether a modification happen in between the FoldInfos were produced at the document + hierarchy lock. The method creates and commits its own FoldTransaction - they are not reentrant, so do not call the method under a transaction.

Parameters:

infos - current state of folds that should be updated to the hierarchy

removed - Collection that will receive Folds, which have been removed from the hierarchy, or null, if the caller does not want to receive the information

created - Collection that will receive FoldInfos that created new Folds in the hierarchy, null means the caller is not interested in the creation information.

Returns:

the mapping from FoldInfos supplied as an input to current Folds. null, if the manager has been released.

Throws:

BadLocationException

Since:

1.35