DocumentUtilities (Editor Utilities) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.editor.util/1 1.17

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.lib.editor.util.swing
Class DocumentUtilities

java.lang.Object
  org.netbeans.lib.editor.util.swing.DocumentUtilities

public final class DocumentUtilities
extends Object
extends Object

Various utility methods related to swing text documents.

Since:: 1.4

Method Summary

static void addDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)
          Add document listener to document with given priority or default to using regular Document.addDocumentListener(DocumentListener) if the given document is not listener priority aware.

static void addEventPropertyStorage(DocumentEvent evt)
          Document provider should call this method to allow for document event properties being stored in document events.

static boolean addPriorityDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)
          Suitable for document implementations - adds document listener to document with given priority and does not do anything if the given document is not listener priority aware.

static int fixOffset(int offset, DocumentEvent evt)
          Fix the given offset according to the performed modification.

static Object getEventProperty(DocumentEvent evt, Object key)
          Get a property of a given document event.

static String getModificationText(DocumentEvent evt)
          Get text of the given document modification.

static Element getParagraphElement(Document doc, int offset)
          Get the paragraph element for the given document.

static Element getParagraphRootElement(Document doc)
          Get the root of the paragraph elements for the given document.

static CharSequence getText(Document doc)
          Get text of the given document as char sequence.

static CharSequence getText(Document doc, int offset, int length)
          Get a portion of text of the given document as char sequence.

static DocumentListener initPriorityListening(Document doc)
          This method should be used by swing document implementations that want to support document listeners prioritization.

static boolean isReadLocked(Document doc)
          Check whether the given document is read-locked by at least one thread or whether it was write-locked by the current thread.

static boolean isTypingModification(Document doc)
          This method should be used by document listeners to check whether the just performed document modification was caused by user's typing.

static boolean isTypingModification(DocumentEvent evt)
          Deprecated.

static boolean isWriteLocked(Document doc)
          Check whether the given document is write-locked by the current thread.

static void putEventProperty(DocumentEvent evt, Map.Entry mapEntry)
          Set a property of a given document event by using the given map entry.

static void putEventProperty(DocumentEvent evt, Object key, Object value)
          Set a property of a given document event.

static void removeDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)
          Remove document listener that was previously added to the document with given priority or use default Document.removeDocumentListener(DocumentListener) if the given document is not listener priority aware.

static boolean removePriorityDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)
          Suitable for document implementations - removes document listener from document with given priority and does not do anything if the given document is not listener priority aware.

static void setTypingModification(Document doc, boolean typingModification)
          Mark that the ongoing document modification(s) will be caused by user's typing.

Methods inherited from class java.lang.Object

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

Method Summary
`static void`	`addDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)` Add document listener to document with given priority or default to using regular `Document.addDocumentListener(DocumentListener)` if the given document is not listener priority aware.
`static void`	`addEventPropertyStorage(DocumentEvent evt)` Document provider should call this method to allow for document event properties being stored in document events.
`static boolean`	`addPriorityDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)` Suitable for document implementations - adds document listener to document with given priority and does not do anything if the given document is not listener priority aware.
`static int`	`fixOffset(int offset, DocumentEvent evt)` Fix the given offset according to the performed modification.
`static Object`	`getEventProperty(DocumentEvent evt, Object key)` Get a property of a given document event.
`static String`	`getModificationText(DocumentEvent evt)` Get text of the given document modification.
`static Element`	`getParagraphElement(Document doc, int offset)` Get the paragraph element for the given document.
`static Element`	`getParagraphRootElement(Document doc)` Get the root of the paragraph elements for the given document.
`static CharSequence`	`getText(Document doc)` Get text of the given document as char sequence.
`static CharSequence`	`getText(Document doc, int offset, int length)` Get a portion of text of the given document as char sequence.
`static DocumentListener`	`initPriorityListening(Document doc)` This method should be used by swing document implementations that want to support document listeners prioritization.
`static boolean`	`isReadLocked(Document doc)` Check whether the given document is read-locked by at least one thread or whether it was write-locked by the current thread.
`static boolean`	`isTypingModification(Document doc)` This method should be used by document listeners to check whether the just performed document modification was caused by user's typing.
`static boolean`	`isTypingModification(DocumentEvent evt)` Deprecated.
`static boolean`	`isWriteLocked(Document doc)` Check whether the given document is write-locked by the current thread.
`static void`	`putEventProperty(DocumentEvent evt, Map.Entry mapEntry)` Set a property of a given document event by using the given map entry.
`static void`	`putEventProperty(DocumentEvent evt, Object key, Object value)` Set a property of a given document event.
`static void`	`removeDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)` Remove document listener that was previously added to the document with given priority or use default `Document.removeDocumentListener(DocumentListener)` if the given document is not listener priority aware.
`static boolean`	`removePriorityDocumentListener(Document doc, DocumentListener listener, DocumentListenerPriority priority)` Suitable for document implementations - removes document listener from document with given priority and does not do anything if the given document is not listener priority aware.
`static void`	`setTypingModification(Document doc, boolean typingModification)` Mark that the ongoing document modification(s) will be caused by user's typing.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

addDocumentListener

public static void addDocumentListener(Document doc,
                                       DocumentListener listener,
                                       DocumentListenerPriority priority)

Add document listener to document with given priority or default to using regular Document.addDocumentListener(DocumentListener) if the given document is not listener priority aware.

Parameters:: doc - document to which the listener should be added.; listener - document listener to add.; priority - priority with which the listener should be added. If the document does not support document listeners ordering then the listener is added in a regular way by using Document.addDocumentListener( javax.swing.event.DocumentListener) method.

addPriorityDocumentListener

public static boolean addPriorityDocumentListener(Document doc,
                                                  DocumentListener listener,
                                                  DocumentListenerPriority priority)

Suitable for document implementations - adds document listener to document with given priority and does not do anything if the given document is not listener priority aware.
Using this method in the document impls and defaulting to super.addDocumentListener() in case it returns false will ensure that there won't be an infinite loop in case the super constructors would add some listeners prior initing of the priority listening.

Parameters:: doc - document to which the listener should be added.; listener - document listener to add.; priority - priority with which the listener should be added.
Returns:: true if the priority listener was added or false if the document does not support priority listening.

removeDocumentListener

public static void removeDocumentListener(Document doc,
                                          DocumentListener listener,
                                          DocumentListenerPriority priority)

Remove document listener that was previously added to the document with given priority or use default Document.removeDocumentListener(DocumentListener) if the given document is not listener priority aware.

Parameters:: doc - document from which the listener should be removed.; listener - document listener to remove.; priority - priority with which the listener should be removed. It should correspond to the priority with which the listener was added originally.

removePriorityDocumentListener

public static boolean removePriorityDocumentListener(Document doc,
                                                     DocumentListener listener,
                                                     DocumentListenerPriority priority)

Suitable for document implementations - removes document listener from document with given priority and does not do anything if the given document is not listener priority aware.
Using this method in the document impls and defaulting to super.removeDocumentListener() in case it returns false will ensure that there won't be an infinite loop in case the super constructors would remove some listeners prior initing of the priority listening.

Parameters:: doc - document from which the listener should be removed.; listener - document listener to remove.; priority - priority with which the listener should be removed.
Returns:: true if the priority listener was removed or false if the document does not support priority listening.

initPriorityListening

public static DocumentListener initPriorityListening(Document doc)

This method should be used by swing document implementations that want to support document listeners prioritization.
It should be called from document's constructor in the following way:


 class MyDocument extends AbstractDocument {

     MyDocument() {
         super.addDocumentListener(DocumentUtilities.initPriorityListening(this));
     }

     public void addDocumentListener(DocumentListener listener) {
         if (!DocumentUtilities.addDocumentListener(this, listener, DocumentListenerPriority.DEFAULT))
             super.addDocumentListener(listener);
     }

     public void removeDocumentListener(DocumentListener listener) {
         if (!DocumentUtilities.removeDocumentListener(this, listener, DocumentListenerPriority.DEFAULT))
             super.removeDocumentListener(listener);
     }

 }

Parameters:: doc - document to be initialized.
Returns:: the document listener instance that should be added as a document listener typically by using super.addDocumentListener() in document's constructor.
Throws:: IllegalStateException - when the document already has the property initialized.

setTypingModification

public static void setTypingModification(Document doc,
                                         boolean typingModification)

Mark that the ongoing document modification(s) will be caused by user's typing. It should be used by default-key-typed-action and the actions for backspace and delete keys.
The document listeners being fired may query it by using isTypingModification(Document). This method should always be used in the following pattern:

 DocumentUtilities.setTypingModification(doc, true);
 try {
     doc.insertString(offset, typedText, null);
 } finally {
    DocumentUtilities.setTypingModification(doc, false);
 }

See Also:: isTypingModification(Document)

isTypingModification

public static boolean isTypingModification(Document doc)

This method should be used by document listeners to check whether the just performed document modification was caused by user's typing.
Certain functionality such as code completion or code templates may benefit from that information. For example the java code completion should only react to the typed "." but not if the same string was e.g. pasted from the clipboard.

See Also:: setTypingModification(Document, boolean)

isTypingModification

public static boolean isTypingModification(DocumentEvent evt)

Deprecated.

See Also:: isTypingModification(Document)

getText

public static CharSequence getText(Document doc)

Get text of the given document as char sequence.

Parameters:: doc - document for which the charsequence is being obtained.
Returns:: non-null character sequence.
The returned character sequence should only be accessed under document's readlock (or writelock).

getText

public static CharSequence getText(Document doc,
                                   int offset,
                                   int length)
                            throws BadLocationException

Get a portion of text of the given document as char sequence.

Parameters:: doc - document for which the charsequence is being obtained.; offset - starting offset of the charsequence to obtain.; length - length of the charsequence to obtain
Returns:: non-null character sequence.
Throws:: BadLocationException - some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.
The returned character sequence should only be accessed under document's readlock (or writelock).

addEventPropertyStorage

public static void addEventPropertyStorage(DocumentEvent evt)

Document provider should call this method to allow for document event properties being stored in document events.

Parameters:: evt - document event to which the storage should be added. It must be an undoable edit allowing to add an edit.

getEventProperty

public static Object getEventProperty(DocumentEvent evt,
                                      Object key)

Get a property of a given document event.

Parameters:: evt - non-null document event from which the property should be retrieved.; key - non-null key of the property.
Returns:: value for the given property.

putEventProperty

public static void putEventProperty(DocumentEvent evt,
                                    Object key,
                                    Object value)

Set a property of a given document event.

Parameters:: evt - non-null document event to which the property should be stored.; key - non-null key of the property.; value - for the given property.

putEventProperty

public static void putEventProperty(DocumentEvent evt,
                                    Map.Entry mapEntry)

Set a property of a given document event by using the given map entry.
The present implementation is able to directly store instances of CompactMap.MapEntry. Other map entry implementations will be delegated to putEventProperty(DocumentEvent, Object, Object).

Parameters:: evt - non-null document event to which the property should be stored.; mapEntry - non-null map entry which should be stored. Generally after this method finishes the getEventProperty(DocumentEvent, Object) will return mapEntry.getValue() for mapEntry.getKey() key.

fixOffset

public static int fixOffset(int offset,
                            DocumentEvent evt)

Fix the given offset according to the performed modification.

Parameters:: offset - >=0 offset in a document.; evt - document event describing change in the document.
Returns:: offset updated by applying the document change to the offset.

getModificationText

public static String getModificationText(DocumentEvent evt)

Get text of the given document modification.
It's implemented as retrieving of a String.class.

Parameters:: evt - document event describing either document insertion or removal (change event type events will produce null result).
Returns:: text that was inserted/removed from the document by the given document modification or null if that information is not provided by that document event.

isReadLocked

public static boolean isReadLocked(Document doc)

Check whether the given document is read-locked by at least one thread or whether it was write-locked by the current thread.
The method currently only works for AbstractDocument based documents and it uses reflection.
Unfortunately the AbstractDocument does not allow to detect whether exactly this thread has done the read locking or whether it was another thread.

Parameters:: doc - non-null document instance.
Returns:: true if the document was read-locked by some thread or false if not (or if doc not-instanceof AbstractDocument).
Since:: 1.17

isWriteLocked

public static boolean isWriteLocked(Document doc)

Check whether the given document is write-locked by the current thread.
The method currently only works for AbstractDocument based documents and it uses reflection.

Parameters:: doc - non-null document instance.
Returns:: true if the document was write-locked by the current thread or false if not (or if doc not-instanceof AbstractDocument).
Since:: 1.17

getParagraphElement

public static Element getParagraphElement(Document doc,
                                          int offset)

Get the paragraph element for the given document.

Parameters:: doc - non-null document instance.; offset - offset in the document >=0
Returns:: paragraph element containing the given offset.

getParagraphRootElement

public static Element getParagraphRootElement(Document doc)

Get the root of the paragraph elements for the given document.

Parameters:: doc - non-null document instance.
Returns:: root element of the paragraph elements.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.editor.util/1 1.17

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

DocumentUtilities (Editor Utilities) - NetBeans API Javadoc (Current Development Version)

org.netbeans.lib.editor.util.swing Class DocumentUtilities

addDocumentListener

addPriorityDocumentListener

removeDocumentListener

removePriorityDocumentListener

initPriorityListening

setTypingModification

isTypingModification

isTypingModification

getText

getText

addEventPropertyStorage

getEventProperty

putEventProperty

putEventProperty

fixOffset

getModificationText

isReadLocked

isWriteLocked

getParagraphElement

getParagraphRootElement

org.netbeans.lib.editor.util.swing
Class DocumentUtilities