org.netbeans.lib.editor.util.swing

Class DocumentUtilities

java.lang.Object

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

public final class DocumentUtilities
extends Object

Various utility methods related to swing text documents.

Since:

1.4

Method Summary

Modifier and Type	Method and Description
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 void	addPropertyChangeListener(Document doc, PropertyChangeListener l) Adds PropertyChangeListener to a document.
static PropertyChangeListener	addWeakPropertyChangeListener(Document doc, PropertyChangeListener listenerImplementation) Adds a weak PropertyChangeListener to a document.
static StringBuilder	appendEvent(StringBuilder sb, DocumentEvent evt) Get string representation of an offset for debugging purposes in form "offset[line:column]".
static StringBuilder	appendOffset(StringBuilder sb, Document doc, int offset) Get string representation of an offset for debugging purposes in form "offset[line:column]".
static String	debugOffset(Document doc, int offset) Get string representation of an offset for debugging purposes in form "offset[line:column]".
static int	fixOffset(int offset, DocumentEvent evt) Fix the given offset according to the performed modification.
static int	getDocumentListenerCount(Document doc) Get total count of document listeners attached to a particular document (useful e.g.
static long	getDocumentTimestamp(Document doc) Attempts to get the timestamp of a Document.
static long	getDocumentVersion(Document doc) Attempts to get the version of a Document.
static Object	getEventProperty(DocumentEvent evt, Object key) Get a property of a given document event.
static String	getMimeType(Document doc) Gets the mime type of a document.
static String	getMimeType(JTextComponent component) Gets the mime type of a document in JTextComponent.
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 (write-locking grants the read-access automatically).
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 boolean	putEventPropertyIfSupported(DocumentEvent evt, Object key, Object value) Sets a property for the document event, if the event supports the feature.
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	removePropertyChangeListener(Document doc, PropertyChangeListener l) Removes PropertyChangeListener from a document.
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.

getDocumentListenerCount

public static int getDocumentListenerCount(Document doc)

Get total count of document listeners attached to a particular document (useful e.g. for logging).
If the document uses priority listening then get the count of listeners at all levels. If the document is not AbstractDocument the method returns zero.

Parameters:

doc - non-null document.

Returns:

total count of document listeners attached to the document.

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 DocumentUtilities.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:

DocumentUtilities.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:

DocumentUtilities.setTypingModification(Document, boolean)

isTypingModification

@Deprecated
public static boolean isTypingModification(DocumentEvent evt)

Deprecated.

See Also:

DocumentUtilities.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. Length of the character sequence is doc.getLength() + 1 where the extra character is '\n' (it corresponds to AbstractDocument-based document implementations).
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. It must be >= 0 and <doc.getLength() + 1.

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.

putEventPropertyIfSupported

public static boolean putEventPropertyIfSupported(DocumentEvent evt,
                                                  Object key,
                                                  Object value)

Sets a property for the document event, if the event supports the feature. Returns true, if the property was actually set.

Parameters:

evt - the event to modify

key - property key

value - property value

Returns:

true, if the property was set

Since:

1.59

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 DocumentUtilities.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 DocumentUtilities.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 (write-locking grants the read-access automatically).
The method currently only works for AbstractDocument based documents and it uses reflection.
Unfortunately the AbstractDocument only records number of read-lockers but not the thread references that performed the read-locking. Thus it can't be verified whether current thread has performed read locking or 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.

debugOffset

public static String debugOffset(Document doc,
                                 int offset)

Get string representation of an offset for debugging purposes in form "offset[line:column]". Both lines and columns start counting from 1 like in the editor's status bar. Tabs are expanded when counting the column.

Parameters:

doc - non-null document in which the offset is located.

offset - offset in the document.

Returns:

string representation of the offset.

Since:

1.25

appendOffset

public static StringBuilder appendOffset(StringBuilder sb,
                                         Document doc,
                                         int offset)

Get string representation of an offset for debugging purposes in form "offset[line:column]". Both lines and columns start counting from 1 like in the editor's status bar. Tabs are expanded when counting the column.

Parameters:

sb - valid string builder to which text will be appended or null in which case the method itself will create a string builder and it will return it.

doc - non-null document in which the offset is located.

offset - offset in the document.

Returns:

non-null string builder to which the description was added.

Since:

1.27

appendEvent

public static StringBuilder appendEvent(StringBuilder sb,
                                        DocumentEvent evt)

Get string representation of an offset for debugging purposes in form "offset[line:column]". Both lines and columns start counting from 1 like in the editor's status bar. Tabs are expanded when counting the column.

Parameters:

sb - valid string builder to which text will be appended or null in which case the method itself will create a string builder and it will return it.

evt - non-null document event.

Returns:

non-null string builder to which the description was added.

Since:

1.27

getMimeType

public static String getMimeType(Document doc)

Gets the mime type of a document. If the mime type can't be determined this method will return null. This method should work reliably for Netbeans documents that have their mime type stored in a special property. For any other documents it will probably just return null.

Parameters:

doc - The document to get the mime type for.

Returns:

The mime type of the document or null.

Since:

1.23

See Also:

NbEditorDocument#MIME_TYPE_PROP

getMimeType

public static String getMimeType(JTextComponent component)

Gets the mime type of a document in JTextComponent. If the mime type can't be determined this method will return null. It tries to determine the document's mime type first and if that does not work it uses mime type from the EditorKit attached to the component.

Parameters:

component - The component to get the mime type for.

Returns:

The mime type of a document opened in the component or null.

Since:

1.23

getDocumentVersion

public static long getDocumentVersion(Document doc)

Attempts to get the version of a Document. Netbeans editor documents are versioned, which means that every time a document is modified its version is incremented. This method can be used to read the latest version of a netbeans document.

Parameters:

doc - The document to get a version for.

Returns:

The document's version or 0 if the document does not support versioning (ie. is not a netbeans editor document).

Since:

1.27

getDocumentTimestamp

public static long getDocumentTimestamp(Document doc)

Attempts to get the timestamp of a Document. Netbeans editor documents are versioned and timestamped whenever they are modified. This method can be used to read the timestamp of the most recent modification. The timestamp is a number of milliseconds returned from System.currentTimeMillis() at the document modification.

Parameters:

doc - The document to get the timestamp for.

Returns:

The document's timestamp or 0 if the document does not support timestamps (ie. is not a netbeans editor document).

Since:

1.34

addPropertyChangeListener

public static void addPropertyChangeListener(Document doc,
                                             PropertyChangeListener l)

Adds PropertyChangeListener to a document.

In general, document properties are key-value pairs where both the key and the value can be any Object. Contrary to that PropertyChangeListeners can only handle named properties that can have an arbitrary value, but have String names. Therefore the listenera attached to a document will only ever recieve document properties, which keys are of java.lang.String type.

Additionally, the list of document properties that clients can listen on is not part of this contract.

Note that this method does not work with WeakListeners. Use DocumentUtilities.addWeakPropertyChangeListener(javax.swing.text.Document, java.beans.PropertyChangeListener) for that purpose.

Parameters:

doc - The document to add the listener to.

l - The listener to add to the document.

Since:

1.35

removePropertyChangeListener

public static void removePropertyChangeListener(Document doc,
                                                PropertyChangeListener l)

Removes PropertyChangeListener from a document.

Parameters:

doc - The document to remove the listener from.

l - The listener to remove from the document.

Since:

1.35

addWeakPropertyChangeListener

public static PropertyChangeListener addWeakPropertyChangeListener(Document doc,
                                                                   PropertyChangeListener listenerImplementation)

Adds a weak PropertyChangeListener to a document.

In general, document properties are key-value pairs where both the key and the value can be any Object. Contrary to that PropertyChangeListeners can only handle named properties that can have an arbitrary value, but have String names. Therefore the listenera attached to a document will only ever recieve document properties, which keys are of java.lang.String type.

Additionally, the list of document properties that clients can listen on is not part of this contract.

Parameters:

doc - The document to add the listener to.

listenerImplementation - The listener to be added weakly to the document.

Returns:

the created weak listener - only the returned listener can be used with DocumentUtilities.removePropertyChangeListener(javax.swing.text.Document, java.beans.PropertyChangeListener). If the document does not support PropertyChangeLister null is returned.

Since:

1.68