mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-30 10:17:50 +08:00
48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
---
|
|
layout: editable
|
|
title: Documents
|
|
---
|
|
|
|
A document is an editable sequence of Unicode characters, which typically corresponds to the text contents of a virtual file.
|
|
Line breaks in a document are always normalized to \n. IntelliJ IDEA handles encoding and line break conversions when loading and saving documents transparently.
|
|
|
|
## How do I get one?
|
|
|
|
* 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()```
|
|
|
|
## What can I do with one?
|
|
|
|
Any operations which access or modify the file contents on "plain text" level (as a sequence of characters, not as a tree of Java elements).
|
|
|
|
## Where does it come from?
|
|
|
|
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). Also, document instances not linked to any virtual files can be created temporarily, for example, to represent the contents of a text editor field in a dialog.
|
|
|
|
## How long does it live?
|
|
|
|
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.
|
|
|
|
## How do I create one?
|
|
|
|
If you need to create a new file on disk, you don't create a document: you create a PSI file and then get its document. If you need to create a document instance which isn't bound to anything, you can use ```EditorFactory.createDocument```.
|
|
|
|
## How do I get notified when it changes?
|
|
|
|
* ```Document.addDocumentListener``` allows you to receive notifications about changes in a particular Document instance.
|
|
* ```EditorFactory.getEventMulticaster().addDocumentListener``` allows you to receive notifications about changes in all open documents.
|
|
* ```FileDocumentManager.addFileDocumentManagerListener``` allows you to receive notifications when any document is saved or reloaded from disk.
|
|
|
|
## What are the rules of working with it?
|
|
|
|
The general read/write action rules are in effect. In addition to that, any operations which modify the contents of the document must be wrapped in a command (```CommandProcessor.getInstance().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.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.
|
|
|
|
## Samples
|
|
|
|
A sample plugin project that illustrates how to work with document files is available in the _<%IDEA project directory%>/community/samples/textEditor_ directory. For more information, see [Sample Text File Editor]().
|