com.intellij.openapi.editor
Interface Document

All Superinterfaces:

UserDataHolder

public interface Document
extends UserDataHolder

Represents the contents of a text file loaded into memory, and possibly opened in an IDEA 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.

See Also:

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

Field Summary

static java.lang.String

PROP_WRITABLE

Method Summary

void	addDocumentListener(DocumentListener listener) Adds a listener for receiving notifications about changes in the document content.
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).
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.
void	deleteString(int startOffset, int endOffset) Deletes the specified range of text from the document.
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).
char[]	getChars() Deprecated. Use getCharsSequence() or getText() instead.
java.lang.CharSequence	getCharsSequence() Use this method instead of getText() if you do not need to create a copy of the content.
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.
int	getLineStartOffset(int line) Returns the start offset for the line with the specified number.
MarkupModel	getMarkupModel() Deprecated. use getMarkupModel(com.intellij.openapi.project.Project) instead.
MarkupModel	getMarkupModel(Project project) Returns the markup model for the specified project.
long	getModificationStamp() Gets the modification stamp value.
RangeMarker	getOffsetGuard(int offset) Returns the read-only marker covering the specified offset in the document.
RangeMarker	getRangeGuard(int start, int end) Returns the read-only marker covering the specified range in the document.
java.lang.String	getText() Retreives a copy of the document content.
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.
boolean	isWritable() Checks if the document text is read-only.
void	removeDocumentListener(DocumentListener listener) Removes a listener for receiving notifications about changes in the document content.
void	removeGuardedBlock(RangeMarker block) Removes a marker marking a range of text in the document as read-only.
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.
void	setCyclicBufferSize(int bufferSize) Sets the maximum size of the cyclic buffer used for the document.
void	setReadOnly(boolean isReadOnly) Marks the document as read-only or read/write.
void	startGuardedBlockChecking() Enables checking for read-only markers when the document is modified.
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

PROP_WRITABLE

@NonNls
static final java.lang.String PROP_WRITABLE

See Also:

Constant Field Values

Method Detail

getText

java.lang.String getText()

Retreives a copy of the document content. For obvious performance reasons use getCharsSequence() whenever it's possible.

Returns:

document content.

getCharsSequence

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

getChars

char[] getChars()

Deprecated. Use getCharsSequence() or getText() instead.

getTextLength

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.

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

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

void addDocumentListener(DocumentListener listener)

Adds a listener for receiving notifications about changes in the document content.

Parameters:

listener - the listener instance.

removeDocumentListener

void removeDocumentListener(DocumentListener listener)

Removes a listener for receiving notifications about changes in the document content.

Parameters:

listener - the listener instance.

createRangeMarker

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.

getMarkupModel

MarkupModel getMarkupModel()

Deprecated. use getMarkupModel(com.intellij.openapi.project.Project) instead.

getMarkupModel

@NotNull
MarkupModel getMarkupModel(@Nullable
                                   Project project)

Returns the markup model for the specified project. A document can have multiple markup models for different projects if the file to which it corresponds belongs to multiple projects opened in different IDEA frames at the same time.

Parameters:

project - the project for which the markup model is requested, or null if the default markup model is requested.

Returns:

the markup model instance.

See Also:

Editor.getMarkupModel()

addPropertyChangeListener

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

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

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.

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

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

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

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

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

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

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.