org.openide.text
Class NbDocument

java.lang.Object
  extended byorg.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 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.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
          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.

See Also:
Constant Field Values

ERROR_STYLE_NAME

public static final String ERROR_STYLE_NAME
Name of style attached to documents to mark a paragraph (line) as erroneous.

See Also:
Constant Field Values

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

See Also:
Constant Field Values

NORMAL_STYLE_NAME

public static final String NORMAL_STYLE_NAME
Name of style attached to documents to unmark a paragraph (line) as anything special.

See Also:
Constant Field Values

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

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

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

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

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.

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

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

 

Built on May 3 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.