Idea Plugin Dev - Documents

Instantiation / Creation

Document instances are created:

• when some operation needs to access the text contents of a file (in particular, this is needed to build the PSI for a file).
• when document instances are not linked to any virtual files. They are then created temporarily, for example, to represent the contents of a text editor field in a dialog.

Normally, you don't create a document as it's bounded (to a PSI file, virtual file, …). See get section.

If you still need to create a Document instance which isn’t bound to anything, you can use EditorFactory.createDocument

Get

• From an action: e.getData(PlatformDataKeys.EDITOR).getDocument()
• From a virtual file: FileDocumentManager.getDocument(). This call forces the document content to be loaded from disk if it wasn’t loaded previously; if you’re only interested in open documents or documents which may have been modified, use FileDocumentManager.getCachedDocument() instead.
• From a PSI file: PsiDocumentManager.getInstance().getDocument() or PsiDocumentManager.getInstance().getCachedDocument()

Operations

You may perform any operations that access or modify the file contents on “plain text” level (as a sequence of characters, not as a tree of Java elements).

The general read/write action rules are in effect.

Any operations which modify the contents of the document must be wrapped in a command (CommandProcessor.getInstance().executeCommand()).

• executeCommand() calls can be nested,
• 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.getInstance(project).ensureFilesWritable() to check out the file if necessary.

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

Persistence

Document instances are weakly referenced from VirtualFile instances. Thus, an unmodified Document instance can be garbage-collected if it isn’t referenced by anyone, and a new instance will be created if the document contents is accessed again later. Storing Document references in long-term data structures of your plugin will cause memory leaks.

Watcher / Notification

Scope

A document has an application scope (even if multiple projects are open, each file is represented by the same VirtualFile instance).