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.

Inner Class Summary

static interface	NbDocument.Annotatable Enhanced version of document which is capable of attaching/detaching of annotations.
static class	NbDocument.Colors Deprecated. Not useful for anything.
static interface	NbDocument.CustomEditor Enabled documents to add special UI 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 Name of style attached to documents to mark a paragraph (line) as a (debugger) breakpoint.
static NbDocument.Colors	COLORS Deprecated. Not useful for anything.
static String	CURRENT_STYLE_NAME Name of style attached to documents to mark a paragraph (line) as current (in a debugger).
static String	ERROR_STYLE_NAME Name of style attached to documents to mark a paragraph (line) as erroneous.
static Object	GUARDED Attribute that signals that a given character is guarded (cannot be modified).
static String	NORMAL_STYLE_NAME Name of style attached to documents to unmark a paragraph (line) as anything special.

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

public static final String BREAKPOINT_STYLE_NAME

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

ERROR_STYLE_NAME

public static final String ERROR_STYLE_NAME

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

CURRENT_STYLE_NAME

public static final String CURRENT_STYLE_NAME

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

NORMAL_STYLE_NAME

public static final String NORMAL_STYLE_NAME

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

COLORS

public static final NbDocument.Colors COLORS

Deprecated. Not useful for anything.

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

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

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)

findLineOffset

public static int findLineOffset(StyledDocument doc,
                                 int lineNumber)

Finds offset of the beginning of a line.

Parameters:

doc - the document

line - number of the line to find the start of

Returns:

offset

Throws:

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:

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

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

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

markBreakpoint

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

markError

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

markCurrent

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

markNormal

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

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

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:

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

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.

Parameters:

doc - the annotated document

annotation - annotation which is going to be removed

Since:

1.20