Document (Unofficial IntelliJ Community Edition API docs)

All Superinterfaces:

UserDataHolder

All Known Subinterfaces:

DocumentEx, DocumentWindow

All Known Implementing Classes:

DocumentImpl, EditorTextFieldRendererDocument, FrozenDocument
```
public interface Document
extends UserDataHolder
```
Represents the contents of a text file loaded into memory, and possibly opened in an IDE text editor. Line breaks in the document text are always normalized as single \n characters, and are converted to proper format when the document is saved.
Please see IntelliJ Platform Architectural Overview for high-level overview.

See Also:

Editor.getDocument(), PsiDocumentManager, FileDocumentManager, EditorFactory.createDocument(CharSequence)

Field Summary

Fields
Modifier and Type Field and Description

static Document[] EMPTY_ARRAY

static java.lang.String PROP_WRITABLE

Fields
Modifier and Type	Field and Description
`static Document[]`	`EMPTY_ARRAY`
`static java.lang.String`	`PROP_WRITABLE`

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default void`	`addDocumentListener(DocumentListener listener)` Adds a listener for receiving notifications about changes in the document content.
`default void`	`addDocumentListener(DocumentListener listener, Disposable parentDisposable)`
`default void`	`addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Adds a listener for receiving notifications about changes in the properties of the document (for example, its read-only state).
`RangeMarker`	`createGuardedBlock(int startOffset, int endOffset)` Marks a range of text in the document as read-only (attempts to modify text in the range cause `ReadOnlyFragmentModificationException` to be thrown).
`default RangeMarker`	`createRangeMarker(int startOffset, int endOffset)` Creates a range marker which points to the specified range of text in the document and is automatically adjusted when the document text is changed.
`RangeMarker`	`createRangeMarker(int startOffset, int endOffset, boolean surviveOnExternalChange)` Creates a range marker which points to the specified range of text in the document and is automatically adjusted when the document text is changed.
`default RangeMarker`	`createRangeMarker(TextRange textRange)`
`void`	`deleteString(int startOffset, int endOffset)` Deletes the specified range of text from the document.
`default void`	`fireReadOnlyModificationAttempt()` Fires a notification that the user would like to remove the read-only state from the document (the read-only state can be removed by checking the file out from the version control system, or by clearing the read-only attribute on the file).
`default char []`	`getChars()` Deprecated. Use `getCharsSequence()` or `getText()` instead.
`default java.lang.CharSequence`	`getCharsSequence()` Use this method instead of `getText()` if you do not need to create a copy of the content.
`java.lang.CharSequence`	`getImmutableCharSequence()`
`int`	`getLineCount()` Returns the number of lines in the document.
`int`	`getLineEndOffset(int line)` Returns the end offset for the line with the specified number.
`int`	`getLineNumber(int offset)` Returns the line number (0-based) corresponding to the specified offset in the document.
`default int`	`getLineSeparatorLength(int line)`
`int`	`getLineStartOffset(int line)` Returns the start offset for the line with the specified number.
`long`	`getModificationStamp()` Gets the modification stamp value.
`default RangeMarker`	`getOffsetGuard(int offset)` Returns the read-only marker covering the specified offset in the document.
`default RangeMarker`	`getRangeGuard(int start, int end)` Returns the read-only marker covering the specified range in the document.
`default java.lang.String`	`getText()` Retrieves a copy of the document content.
`default java.lang.String`	`getText(TextRange range)`
`default int`	`getTextLength()` Returns the length of the document text.
`void`	`insertString(int offset, java.lang.CharSequence s)` Inserts the specified text at the specified offset in the document.
`default boolean`	`isInBulkUpdate()`
`default boolean`	`isLineModified(int line)`
`boolean`	`isWritable()` Checks if the document text is read-only.
`default void`	`removeDocumentListener(DocumentListener listener)` Removes a listener for receiving notifications about changes in the document content, previously added via `addDocumentListener(DocumentListener)`.
`default void`	`removeGuardedBlock(RangeMarker block)` Removes a marker marking a range of text in the document as read-only.
`default void`	`removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Removes a listener for receiving notifications about changes in the properties of the document (for example, its read-only state).
`void`	`replaceString(int startOffset, int endOffset, java.lang.CharSequence s)` Replaces the specified range of text in the document with the specified string.
`default void`	`setCyclicBufferSize(int bufferSize)` Sets the maximum size of the cyclic buffer used for the document.
`default void`	`setInBulkUpdate(boolean value)` Enters or exits 'bulk' mode for processing of document changes.
`default void`	`setReadOnly(boolean isReadOnly)` Marks the document as read-only or read/write.
`void`	`setText(java.lang.CharSequence text)`
`default void`	`startGuardedBlockChecking()` Enables checking for read-only markers when the document is modified.
`default void`	`stopGuardedBlockChecking()` Disables checking for read-only markers when the document is modified.

Methods inherited from interface com.intellij.openapi.util.UserDataHolder
getUserData, putUserData

- Field Detail
  - EMPTY_ARRAY
```
static final Document[] EMPTY_ARRAY
```
  - PROP_WRITABLE
```
static final java.lang.String PROP_WRITABLE
```
    See Also:
    
    Constant Field Values
- Method Detail
  - getText
```
default java.lang.String getText()
```
    Retrieves a copy of the document content. For obvious performance reasons use getCharsSequence() whenever it's possible.
    
    Returns:
    
    document content.
  - getText
```
default java.lang.String getText(TextRange range)
```
  - getCharsSequence
```
default java.lang.CharSequence getCharsSequence()
```
    Use this method instead of getText() if you do not need to create a copy of the content. Content represented by returned CharSequence is subject to change whenever document is modified via delete/replace/insertString method calls. It is necessary to obtain Application.runWriteAction() to modify content of the document though so threading issues won't arise.
    
    Returns:
    
    inplace document content.
    
    See Also:
    
    getTextLength()
  - getImmutableCharSequence
```
java.lang.CharSequence getImmutableCharSequence()
```
    Returns:
    
    a char sequence representing document content that's guaranteed to be immutable. No read- or write-action is necessary.
    
    See Also:
    
    ImmutableCharSequence
  - getChars
```
@Deprecated
default char [] getChars()
```
    Deprecated. Use getCharsSequence() or getText() instead.
  - getTextLength
```
default int getTextLength()
```
    Returns the length of the document text.
    
    Returns:
    
    the length of the document text.
    
    See Also:
    
    getCharsSequence()
  - getLineCount
```
int getLineCount()
```
    Returns the number of lines in the document.
    
    Returns:
    
    the number of lines in the document.
  - getLineNumber
```
int getLineNumber(int offset)
```
    Returns the line number (0-based) corresponding to the specified offset in the document.
    
    Parameters:
    
    offset - the offset to get the line number for (must be in the range from 0 to getTextLength()-1)
    
    Returns:
    
    the line number corresponding to the offset.
  - getLineStartOffset
```
int getLineStartOffset(int line)
```
    Returns the start offset for the line with the specified number.
    
    Parameters:
    
    line - the line number (from 0 to getLineCount()-1)
    
    Returns:
    
    the start offset for the line.
  - getLineEndOffset
```
int getLineEndOffset(int line)
```
    Returns the end offset for the line with the specified number.
    
    Parameters:
    
    line - the line number (from 0 to getLineCount()-1)
    
    Returns:
    
    the end offset for the line.
  - isLineModified
```
default boolean isLineModified(int line)
```
    Returns:
    
    whether the line with the given index has been modified since the document has been saved
  - insertString
```
void insertString(int offset,
                  java.lang.CharSequence s)
```
    Inserts the specified text at the specified offset in the document. Line breaks in the inserted text must be normalized as \n.
    
    Parameters:
    
    offset - the offset to insert the text at.
    
    s - the text to insert.
    
    Throws:
    
    ReadOnlyModificationException - if the document is read-only.
    
    ReadOnlyFragmentModificationException - if the fragment to be modified is covered by a guarded block.
  - deleteString
```
void deleteString(int startOffset,
                  int endOffset)
```
    Deletes the specified range of text from the document.
    
    Parameters:
    
    startOffset - the start offset of the range to delete.
    
    endOffset - the end offset of the range to delete.
    
    Throws:
    
    ReadOnlyModificationException - if the document is read-only.
    
    ReadOnlyFragmentModificationException - if the fragment to be modified is covered by a guarded block.
  - replaceString
```
void replaceString(int startOffset,
                   int endOffset,
                   java.lang.CharSequence s)
```
    Replaces the specified range of text in the document with the specified string. Line breaks in the text to replace with must be normalized as \n.
    
    Parameters:
    
    startOffset - the start offset of the range to replace.
    
    endOffset - the end offset of the range to replace.
    
    s - the text to replace with.
    
    Throws:
    
    ReadOnlyModificationException - if the document is read-only.
    
    ReadOnlyFragmentModificationException - if the fragment to be modified is covered by a guarded block.
  - isWritable
```
boolean isWritable()
```
    Checks if the document text is read-only.
    
    Returns:
    
    true if the document text is writable, false if it is read-only.
    
    See Also:
    
    fireReadOnlyModificationAttempt()
  - getModificationStamp
```
long getModificationStamp()
```
    Gets the modification stamp value. Modification stamp is a value changed by any modification of the content of the file. Note that it is not related to the file modification time.
    
    Returns:
    
    the modification stamp value.
    
    See Also:
    
    PsiFile.getModificationStamp(), VirtualFile.getModificationStamp()
  - fireReadOnlyModificationAttempt
```
default void fireReadOnlyModificationAttempt()
```
    Fires a notification that the user would like to remove the read-only state from the document (the read-only state can be removed by checking the file out from the version control system, or by clearing the read-only attribute on the file).
  - addDocumentListener
```
default void addDocumentListener(DocumentListener listener)
```
    Adds a listener for receiving notifications about changes in the document content.
    
    Parameters:
    
    listener - the listener instance.
  - addDocumentListener
```
default void addDocumentListener(DocumentListener listener,
                                 Disposable parentDisposable)
```
  - removeDocumentListener
```
default void removeDocumentListener(DocumentListener listener)
```
    Removes a listener for receiving notifications about changes in the document content, previously added via addDocumentListener(DocumentListener). Don't call this method for listeners added via addDocumentListener(DocumentListener, Disposable), as that might cause memory leaks.
    
    Parameters:
    
    listener - the listener instance.
  - createRangeMarker
```
default RangeMarker createRangeMarker(int startOffset,
                                      int endOffset)
```
    Creates a range marker which points to the specified range of text in the document and is automatically adjusted when the document text is changed. The marker is invalidated by external changes to the document text (for example, reloading the file from disk).
    
    Parameters:
    
    startOffset - the start offset for the range of text covered by the marker.
    
    endOffset - the end offset for the range of text covered by the marker.
    
    Returns:
    
    the marker instance.
  - createRangeMarker
```
RangeMarker createRangeMarker(int startOffset,
                              int endOffset,
                              boolean surviveOnExternalChange)
```
    Creates a range marker which points to the specified range of text in the document and is automatically adjusted when the document text is changed. The marker is optionally invalidated by external changes to the document text (for example, reloading the file from disk).
    
    Parameters:
    
    startOffset - the start offset for the range of text covered by the marker.
    
    endOffset - the end offset for the range of text covered by the marker.
    
    surviveOnExternalChange - if true, the marker is not invalidated by external changes.
    
    Returns:
    
    the marker instance.
  - addPropertyChangeListener
```
default void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
```
    Adds a listener for receiving notifications about changes in the properties of the document (for example, its read-only state).
    
    Parameters:
    
    listener - the listener instance.
  - removePropertyChangeListener
```
default void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
```
    Removes a listener for receiving notifications about changes in the properties of the document (for example, its read-only state).
    
    Parameters:
    
    listener - the listener instance.
  - setReadOnly
```
default void setReadOnly(boolean isReadOnly)
```
    Marks the document as read-only or read/write. This method only modifies the flag stored in the document instance - no checkouts or file changes are performed.
    
    Parameters:
    
    isReadOnly - the new value of the read-only flag.
    
    See Also:
    
    isWritable(), fireReadOnlyModificationAttempt()
  - createGuardedBlock
```
RangeMarker createGuardedBlock(int startOffset,
                               int endOffset)
```
    Marks a range of text in the document as read-only (attempts to modify text in the range cause ReadOnlyFragmentModificationException to be thrown).
    
    Parameters:
    
    startOffset - the start offset of the text range to mark as read-only.
    
    endOffset - the end offset of the text range to mark as read-only.
    
    Returns:
    
    the marker instance.
    
    See Also:
    
    removeGuardedBlock(RangeMarker), startGuardedBlockChecking(), EditorActionManager.setReadonlyFragmentModificationHandler(com.intellij.openapi.editor.actionSystem.ReadonlyFragmentModificationHandler)
  - removeGuardedBlock
```
default void removeGuardedBlock(RangeMarker block)
```
    Removes a marker marking a range of text in the document as read-only.
    
    Parameters:
    
    block - the marker to remove.
    
    See Also:
    
    createGuardedBlock(int, int)
  - getOffsetGuard
```
default RangeMarker getOffsetGuard(int offset)
```
    Returns the read-only marker covering the specified offset in the document.
    
    Parameters:
    
    offset - the offset for which the marker is requested.
    
    Returns:
    
    the marker instance, or null if the specified offset is not covered by a read-only marker.
  - getRangeGuard
```
default RangeMarker getRangeGuard(int start,
                                  int end)
```
    Returns the read-only marker covering the specified range in the document.
    
    Parameters:
    
    start - the start offset of the range for which the marker is requested.
    
    end - the end offset of the range for which the marker is requested.
    
    Returns:
    
    the marker instance, or null if the specified range is not covered by a read-only marker.
  - startGuardedBlockChecking
```
default void startGuardedBlockChecking()
```
    Enables checking for read-only markers when the document is modified. Checking is disabled by default.
    
    See Also:
    
    createGuardedBlock(int, int), stopGuardedBlockChecking()
  - stopGuardedBlockChecking
```
default void stopGuardedBlockChecking()
```
    Disables checking for read-only markers when the document is modified. Checking is disabled by default.
    
    See Also:
    
    createGuardedBlock(int, int), startGuardedBlockChecking()
  - setCyclicBufferSize
```
default void setCyclicBufferSize(int bufferSize)
```
    Sets the maximum size of the cyclic buffer used for the document. If the document uses a cyclic buffer, text added to the end of the document exceeding the maximum size causes text to be removed from the beginning of the document.
    
    Parameters:
    
    bufferSize - the cyclic buffer size, or 0 if the document should not use a cyclic buffer.
  - setText
```
void setText(java.lang.CharSequence text)
```
  - createRangeMarker
```
default RangeMarker createRangeMarker(TextRange textRange)
```
  - getLineSeparatorLength
```
default int getLineSeparatorLength(int line)
```
  - isInBulkUpdate
```
default boolean isInBulkUpdate()
```
    See Also:
    
    setInBulkUpdate(boolean)
  - setInBulkUpdate
```
default void setInBulkUpdate(boolean value)
```
    Enters or exits 'bulk' mode for processing of document changes. Bulk mode should be used when a large number of document changes are applied in batch (without user interaction for each change), to improve performance. E.g. this mode is sometimes used by the platform code during code formatting. In this mode some activities that usually happen on each document change will be muted, with reconciliation happening on bulk mode exit.
    As the reconciliation after exiting bulk mode implies some additional overhead, bulk mode shouldn't be used if the number of document changes to be performed is relatively small. The number of changes which justifies switching to bulk mode is usually determined empirically, but typically it's around hundred(s) of changes.
    In bulk mode editor(s) associated with the document will stop updating internal caches on each document change. As a result, certain operations with editor can return invalid results or lead to exception, if they are preformed in bulk mode. They include: querying or updating folding or soft wrap data, editor position recalculation functions (offset to logical position, logical to visual position, etc), querying or updating caret position or selection state.
    Bulk mode shouldn't span more than one thread or EDT event. Typically it should turned on/off in a try/finally statement.
    
    See Also:
    
    DocumentUtil.executeInBulk(Document, boolean, Runnable), BulkAwareDocumentListener

Interface Document

Field Summary

Method Summary

Methods inherited from interface com.intellij.openapi.util.UserDataHolder

Field Detail

EMPTY_ARRAY

PROP_WRITABLE

Method Detail

getText

getText

getCharsSequence

getImmutableCharSequence

getChars

getTextLength

getLineCount

getLineNumber

getLineStartOffset

getLineEndOffset

isLineModified

insertString

deleteString

replaceString

isWritable

getModificationStamp

fireReadOnlyModificationAttempt

addDocumentListener

addDocumentListener

removeDocumentListener

createRangeMarker

createRangeMarker

addPropertyChangeListener

removePropertyChangeListener

setReadOnly

createGuardedBlock

removeGuardedBlock

getOffsetGuard

getRangeGuard

startGuardedBlockChecking

stopGuardedBlockChecking

setCyclicBufferSize

setText

createRangeMarker

getLineSeparatorLength

isInBulkUpdate

setInBulkUpdate