org.openide.text
Class NbDocument

java.lang.Object
  org.openide.text.NbDocument

public final class NbDocument
extends Object

Dummy class holding utility methods for working with NetBeans document conventions.

Nested Class Summary

static interface	NbDocument.Annotatable Enhanced version of document which is capable of attaching/detaching of annotations.
static interface	NbDocument.CustomEditor Enabled documents to add special UI components to their Editor pane.
static interface	NbDocument.CustomToolbar Enabled documents to add special UI toolbar components to their Editor pane.
static interface	NbDocument.PositionBiasable Enhanced version of document that provides better support for holding and working with biased positions.
static interface	NbDocument.Printable Document which may support styled text printing.
static interface	NbDocument.WriteLockable Specialized version of document that knows how to lock the document for complex modifications.

Field Summary

static String	BREAKPOINT_STYLE_NAME Deprecated. since 6.29. Use Annotation instead.
static String	CURRENT_STYLE_NAME Deprecated. since 6.29. Use Annotation instead.
static String	ERROR_STYLE_NAME Deprecated. since 6.29. Use Annotation instead.
static Object	GUARDED Attribute that signals that a given character is guarded (cannot be modified).
static String	NORMAL_STYLE_NAME Deprecated. since 6.29. Use Annotation instead.

Method Summary

static void	addAnnotation(StyledDocument doc, Position startPos, int length, Annotation annotation) Add annotation to the document.
static Position	createPosition(Document doc, int offset, Position.Bias bias) Creates position with a bias.
static int	findLineColumn(StyledDocument doc, int offset) Finds column number given an offset.
static int	findLineNumber(StyledDocument doc, int offset) For given document and an offset, find the line number.
static int	findLineOffset(StyledDocument doc, int lineNumber) Finds offset of the beginning of a line.
static Element	findLineRootElement(StyledDocument doc) Find the root element of all lines.
static Object	findPageable(StyledDocument doc) Find a way to print a given document.
static JEditorPane	findRecentEditorPane(EditorCookie ec) Gets recently selected editor pane opened by editor cookie Can be called from AWT event thread only.
static StyledDocument	getDocument(Lookup.Provider provider) Get the document associated with a file.
static <T extends UndoableEdit> T	getEditToBeRedoneOfType(EditorCookie ec, Class<T> type) Get an edit of given type that would be redone if a redo operation would be invoked at this time for an editor cookie.
static <T extends UndoableEdit> T	getEditToBeUndoneOfType(EditorCookie ec, Class<T> type) Get an edit of given type that would be undone if an undo operation would be invoked at this time for an editor cookie.
static void	insertGuarded(StyledDocument doc, int offset, String txt) Inserts a text into given offset and marks it guarded.
static void	markBreakpoint(StyledDocument doc, int offset) Deprecated. since 1.20. Use addAnnotation() instead
static void	markCurrent(StyledDocument doc, int offset) Deprecated. since 1.20. Use addAnnotation() instead
static void	markError(StyledDocument doc, int offset) Deprecated. since 1.20. Use addAnnotation() instead
static void	markGuarded(StyledDocument doc, int offset, int len) Mark part of a document as guarded (immutable to the user).
static void	markNormal(StyledDocument doc, int offset) Deprecated. since 1.20. Use addAnnotation() instead
static boolean	openDocument(Lookup.Provider provider, int line, int column, Line.ShowOpenType openType, Line.ShowVisibilityType visibilityType) Open the document associated with a file in the Editor window in a position specified by the line and column while controlling open and visibility behavior.
static boolean	openDocument(Lookup.Provider provider, int offset, Line.ShowOpenType openType, Line.ShowVisibilityType visibilityType) Open the document associated with a file in the Editor window in a position specified by the offset while controlling open and visibility behavior.
static void	removeAnnotation(StyledDocument doc, Annotation annotation) Removal of added annotation.
static void	runAtomic(StyledDocument doc, Runnable run) Locks the document to have exclusive access to it.
static void	runAtomicAsUser(StyledDocument doc, Runnable run) Executes given runnable in "user mode" does not allowing any modifications to parts of text marked as guarded.
static void	unmarkGuarded(StyledDocument doc, int offset, int len) Remove guarded mark on a block of a document.

Methods inherited from class java.lang.Object

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

Field Detail

GUARDED

public static final Object GUARDED

Attribute that signals that a given character is guarded (cannot be modified). Implements AttributeSet.CharacterAttribute to signal that this attribute applies to characters, not paragraphs.

BREAKPOINT_STYLE_NAME

@Deprecated
public static final String BREAKPOINT_STYLE_NAME

Deprecated. since 6.29. Use Annotation instead.

Name of style attached to documents to mark a paragraph (line) as a (debugger) breakpoint.

See Also:

Constant Field Values

ERROR_STYLE_NAME

@Deprecated
public static final String ERROR_STYLE_NAME

Deprecated. since 6.29. Use Annotation instead.

Name of style attached to documents to mark a paragraph (line) as erroneous.

See Also:

Constant Field Values

CURRENT_STYLE_NAME

@Deprecated
public static final String CURRENT_STYLE_NAME

Deprecated. since 6.29. Use Annotation instead.

Name of style attached to documents to mark a paragraph (line) as current (in a debugger).

See Also:

Constant Field Values

NORMAL_STYLE_NAME

@Deprecated
public static final String NORMAL_STYLE_NAME

Deprecated. since 6.29. Use Annotation instead.

Name of style attached to documents to unmark a paragraph (line) as anything special.

See Also:

Constant Field Values

Method Detail

findLineRootElement

public static Element findLineRootElement(StyledDocument doc)

Find the root element of all lines. All conforming NetBeans documents should return a valid element.

Parameters:

doc - styled document (expecting NetBeans document)

Returns:

the root element

Throws:

NullPointerException - If the doc parameter is null.

findLineNumber

public static int findLineNumber(StyledDocument doc,
                                 int offset)

For given document and an offset, find the line number.

Parameters:

doc - the document

offset - offset in the document

Returns:

the line number for that offset

Throws:

NullPointerException - If the doc parameter is null.

findLineColumn

public static int findLineColumn(StyledDocument doc,
                                 int offset)

Finds column number given an offset.

Parameters:

doc - the document

offset - offset in the document

Returns:

column within the line of that offset (counting starts from zero)

Throws:

NullPointerException - If the doc parameter is null.

findLineOffset

public static int findLineOffset(StyledDocument doc,
                                 int lineNumber)

Finds offset of the beginning of a line.

Parameters:

doc - the document

lineNumber - number of the line to find the start of (zero-based)

Returns:

offset

Throws:

NullPointerException - If the doc parameter is null.

IndexOutOfBoundsException - when incorrect lineNumber value is inserted

createPosition

public static Position createPosition(Document doc,
                                      int offset,
                                      Position.Bias bias)
                               throws BadLocationException

Creates position with a bias. If the bias is Position.Bias.Backward then if an insert occures at the position, the text is inserted after the position. If the bias is Forward, then the text is inserted before the position.

The method checks if the document implements NbDocument.PositionBiasable, and if so, createPosition is called. Otherwise an attempt is made to provide a Position with the correct behavior.

Parameters:

doc - document to create position in

offset - the current offset for the position

bias - the bias to use for the position

Throws:

NullPointerException - If the doc parameter is null.

BadLocationException - if the offset is invalid

markGuarded

public static void markGuarded(StyledDocument doc,
                               int offset,
                               int len)

Mark part of a document as guarded (immutable to the user).

Parameters:

doc - styled document

offset - offset to start at

len - length of text to mark as guarded

Throws:

NullPointerException - If the doc parameter is null.

unmarkGuarded

public static void unmarkGuarded(StyledDocument doc,
                                 int offset,
                                 int len)

Remove guarded mark on a block of a document.

Parameters:

doc - styled document

offset - offset to start at

len - length of text to mark as unguarded

Throws:

NullPointerException - If the doc parameter is null.

insertGuarded

public static void insertGuarded(StyledDocument doc,
                                 int offset,
                                 String txt)
                          throws BadLocationException

Inserts a text into given offset and marks it guarded.

Parameters:

doc - document to insert to

offset - offset of insertion

txt - string text to insert

Throws:

NullPointerException - If the doc parameter is null.

BadLocationException

markBreakpoint

@Deprecated
public static void markBreakpoint(StyledDocument doc,
                                             int offset)

Deprecated. since 1.20. Use addAnnotation() instead

Attach a breakpoint to a line in the document. If the document has a defined style named BREAKPOINT_STYLE_NAME, it is used. Otherwise, a new style is defined.

Parameters:

doc - the document

offset - identifies the line to set breakpoint to

Throws:

NullPointerException - If the doc parameter is null.

markError

@Deprecated
public static void markError(StyledDocument doc,
                                        int offset)

Deprecated. since 1.20. Use addAnnotation() instead

Mark a line as erroneous (e.g. by the compiler). If the document has a defined style named ERROR_STYLE_NAME, it is used. Otherwise, a new style is defined.

Parameters:

doc - the document

offset - identifies the line to mark

Throws:

NullPointerException - If the doc parameter is null.

markCurrent

@Deprecated
public static void markCurrent(StyledDocument doc,
                                          int offset)

Deprecated. since 1.20. Use addAnnotation() instead

Marks a line as current (e.g. for the debugger). If the document has a defined style named CURRENT_STYLE_NAME, it is used. Otherwise, a new style is defined.

Parameters:

doc - the document

offset - identifies the line to mark

Throws:

NullPointerException - If the doc parameter is null.

markNormal

@Deprecated
public static void markNormal(StyledDocument doc,
                                         int offset)

Deprecated. since 1.20. Use addAnnotation() instead

Mark a line as normal (no special attributes). This uses the dummy style named NORMAL_STYLE_NAME. This method should be used to undo the effect of markBreakpoint(javax.swing.text.StyledDocument, int), markError(javax.swing.text.StyledDocument, int) and markCurrent(javax.swing.text.StyledDocument, int).

Parameters:

doc - the document

offset - identified the line to unmark

Throws:

NullPointerException - If the doc parameter is null.

findRecentEditorPane

public static JEditorPane findRecentEditorPane(EditorCookie ec)

Gets recently selected editor pane opened by editor cookie Can be called from AWT event thread only.

Parameters:

ec - EditorCookie used to find out recently selected editor pane

Returns:

pane or null

Since:

6.24

runAtomic

public static void runAtomic(StyledDocument doc,
                             Runnable run)

Locks the document to have exclusive access to it. Documents implementing NbDocument.WriteLockable can specify exactly how to do this.

Parameters:

doc - document to lock

run - the action to run

Throws:

NullPointerException - If the doc parameter is null.

runAtomicAsUser

public static void runAtomicAsUser(StyledDocument doc,
                                   Runnable run)
                            throws BadLocationException

Executes given runnable in "user mode" does not allowing any modifications to parts of text marked as guarded. The actions should be run as "atomic" so either happen all at once or none at all (if a guarded block should be modified).

Parameters:

doc - document to modify

run - runnable to run in user mode that will have exclusive access to modify the document

Throws:

NullPointerException - If the doc parameter is null.

BadLocationException - if a modification of guarded text occured and that is why no changes to the document has been done.

findPageable

public static Object findPageable(StyledDocument doc)

Find a way to print a given document. If the document implements the correct interface(s) then the document is returned, else a default Printable is used as a wrapper. In this last case it is useful to implement NbDocument.Printable to describe how to print in terms of attributed characters, rather than specifying the complete page layout from scratch.

Parameters:

doc - the document to find printing support for

Returns:

an object that is instance of eith Printable or Pageable

addAnnotation

public static void addAnnotation(StyledDocument doc,
                                 Position startPos,
                                 int length,
                                 Annotation annotation)

Add annotation to the document. For annotation of whole line the length parameter can be ignored (specify value -1).
Note: since 6.35 the requests (delegated to document) are no longer replanned to EDT.

Parameters:

doc - the document which will be annotated

startPos - position which represent begining of the annotated text

length - length of the annotated text. If -1 is specified the whole line will be annotated

annotation - annotation which is attached to this text

Since:

1.20

removeAnnotation

public static void removeAnnotation(StyledDocument doc,
                                    Annotation annotation)

Removal of added annotation.
Note: since 6.35 the requests (delegated to document) are no longer replanned to EDT.

Parameters:

doc - the annotated document

annotation - annotation which is going to be removed

Since:

1.20

getEditToBeUndoneOfType

public static <T extends UndoableEdit> T getEditToBeUndoneOfType(EditorCookie ec,
                                                                 Class<T> type)

Get an edit of given type that would be undone if an undo operation would be invoked at this time for an editor cookie.
The edit to be undone may be composed from instances of various undoable edit types (see UndoableEditWrapper).

Type Parameters:

T - type of undoable edit to be retrieved.

Parameters:

ec - editor cookie providing an undo/redo manager.

type - class of undoable edit to be retrieved.

Returns:

undoable edit of given type or null if there is no edit to be undone or an instance of the given type is not contained in the edit to be undone.

Since:

6.49

getEditToBeRedoneOfType

public static <T extends UndoableEdit> T getEditToBeRedoneOfType(EditorCookie ec,
                                                                 Class<T> type)

Get an edit of given type that would be redone if a redo operation would be invoked at this time for an editor cookie.
The edit to be undone may be composed from instances of various undoable edit types (see UndoableEditWrapper).

Type Parameters:

T - type of undoable edit to be retrieved.

Parameters:

ec - editor cookie providing an undo/redo manager.

type - class of undoable edit to be retrieved.

Returns:

undoable edit of given type or null if there is no edit to be redone or an instance of the given type is not contained in the edit to be redone.

Since:

6.49

getDocument

public static StyledDocument getDocument(Lookup.Provider provider)

Get the document associated with a file.

Method will throw UserQuestionException exception if file size is too big. This exception is caught and its method UserQuestionException.confirmed() is used for confirmation.

Parameters:

provider - for example a org.openide.loaders.DataObject

Returns:

a document or null

Since:

org.openide.text 6.46

openDocument

public static boolean openDocument(Lookup.Provider provider,
                                   int offset,
                                   Line.ShowOpenType openType,
                                   Line.ShowVisibilityType visibilityType)

Open the document associated with a file in the Editor window in a position specified by the offset while controlling open and visibility behavior. This method can be called from any thread but blocks until the document is opened.

Parameters:

provider - for example a org.openide.loaders.DataObject

offset - the position the document should be opened (starting at 0)

openType - control open behavior, Line.ShowOpenType.OPEN would typically be used

visibilityType - control visibility behavior, Line.ShowVisibilityType.FOCUS would typically be used

Returns:

true if the Document is opened - false otherwise

Since:

org.openide.text 6.46

See Also:

UserQuestionException handling

openDocument

public static boolean openDocument(Lookup.Provider provider,
                                   int line,
                                   int column,
                                   Line.ShowOpenType openType,
                                   Line.ShowVisibilityType visibilityType)

Open the document associated with a file in the Editor window in a position specified by the line and column while controlling open and visibility behavior. This method can be called from any thread but blocks until the document is opened.

Parameters:

provider - for example a org.openide.loaders.DataObject

line - the line the document should be opened (starting at 0)

column - the column which should be selected (starting at 0), value -1 does not change previously selected column

openType - control open behavior, Line.ShowOpenType.OPEN would typically be used

visibilityType - control visibility behavior, Line.ShowVisibilityType.FOCUS would typically be used

Returns:

true if the Document is opened - false otherwise

Since:

org.openide.text 6.46

See Also:

UserQuestionException handling