Documents

You may perform any operations that access or modify the file contents on the "plain text" level (as a sequence of characters, not as a tree of Program Structure Interface (PSI) elements).

Document instances are created when some operation needs to access the text contents of a file (in particular, this is necessary to build the PSI for a file). Also, document instances not linked to any Virtual Files can be created temporarily, for example, representing the contents of a text editor field in a dialog.

Document instances are weakly referenced from VirtualFile instances. Thus, an unmodified Document instance can be garbage-collected if no one references it, and a new instance is created if the document contents are reaccessed later.

warning

Storing Document references in long-term data structures of a plugin will cause memory leaks.

For creating a new file on disk, please do not create a Document but a PSI file and get its Document (see How do I create a PSI file?). To create a Document instance that isn't bound to anything, use EditorFactory.createDocument().

• Document.addDocumentListener() allows receiving notifications about changes in a particular Document instance.

• EditorFactory.getEventMulticaster().addDocumentListener() allows receiving notifications about changes in all open documents.

• Register FileDocumentManagerListener listener or subscribe to AppTopics.FILE_DOCUMENT_SYNC on any level bus to receive notifications when a Document is saved or reloaded from disk.

The general read/write action rules are in effect (see Threading Model). Besides, any operations which modify the contents of the document must be wrapped in a command (CommandProcessor.executeCommand()). executeCommand() calls can be nested, and the outermost executeCommand() call is added to the undo stack. If multiple documents are modified within a command, undoing this command will, by default, show a confirmation dialog to the user.

If the file corresponding to a Document is read-only (for example, not checked out from the version control system), document modifications will fail. Thus, before modifying the Document, it is necessary to call ReadonlyStatusHandler.ensureFilesWritable() to check out the file.

All text strings passed to Document modification methods (setText(), insertString(), replaceString()) must use only \n as line separators.

See also Working with Text in Editors Basics tutorial.

DocumentUtil contains utility methods for Document processing. This allows you to get information like the text offsets of particular lines. This is particularly useful when you need text location/offset information about a given PsiElement.