hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-29 17:57:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Migrate links to .java classes from GitHub to Upsource.

Browse Source 
The first step in migrating the documentation to Upsource. This has the added benefit of tying us to a specific version in case of code drift. Future migrations will be required in order to use method links (when supported).
This commit is contained in:
breandan 2015-08-18 16:30:40 -04:00
parent d5952b46f7
commit 21581f88a5
59 changed files with 501 additions and 501 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
basics/action_system.md
View File

@ -6,7 +6,7 @@ title: Action System
The system of actions allows plugins to add their own items to IDEA menus and toolbars.
An action is a class, derived from the
[AnAction](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class, whose actionPerformed method is called when the menu item or toolbar button is selected.
For example, one of the action classes is responsible for the "File \| Open File..." menu item and for the "Open File" toolbar button.
@ -15,12 +15,12 @@ Subgroups of the group can form submenus of the menu.
Every action and action group has an unique identifier.
Identifiers of many of the standard IDEA actions are defined in the
[IdeActions](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java)
[IdeActions](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java)
class.
Every action can be included in multiple groups, and thus appear in multiple places within the IDEA user interface.
Different places where actions can appear are defined by constants in the
[ActionPlaces](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java)
[ActionPlaces](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java)
interface. For every place where the action appears, a new `Presentation` is created.
Thus, the same action can have different text or icons when it appears in different places of the user interface.
Different presentations for the action are created by copying the presentation returned by the `AnAction.getTemplatePresentation()` method.
@ -101,11 +101,11 @@ Registering actions in plugin.xml is demonstrated in the following example. The
To register an action from code, two steps are required.
First, an instance of the class derived from `AnAction` must be passed to the `registerAction` method of the
[ActionManager](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionManager.java)
[ActionManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionManager.java)
class, to associate the action with an ID.
Second, the action needs to be added to one or more groups.
To get an instance of an action group by ID, it is necessary to call `ActionManager.getAction()` and cast the returned value to the
[DefaultActionGroup](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
[DefaultActionGroup](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
class.
You can create a plugin that registers actions on IDEA startup using the following procedure.

12
basics/architectural_overview/file_view_providers.md
View File

@ -2,9 +2,9 @@
title: File View Providers
---
A file view provider (see the [FileViewProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/FileViewProvider.java) class) was introduced in IntelliJ IDEA 6.0. Its main purpose is to manage access to multiple PSI trees within a single file.
A file view provider (see the [FileViewProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/FileViewProvider.java) class) was introduced in IntelliJ IDEA 6.0. Its main purpose is to manage access to multiple PSI trees within a single file.
For example, a JSPX page has a separate PSI tree for the Java code in it (`PsiJavaFile`), a separate tree for the XML code (`XmlFile`), and a separate tree for JSP as a whole
[JspFile](https://github.com/JetBrains/intellij-community/blob/master/java/jsp-openapi/src/com/intellij/psi/jsp/JspFile.java)).
[JspFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/jsp-openapi/src/com/intellij/psi/jsp/JspFile.java)).
Each of the PSI trees covers the entire contents of the file, and contains special "outer language elements" in the places where contents in a different language can be found.
A `FileViewProvider` instance corresponds to a single `VirtualFile`, a single `Document`, and can be used to retrieve multiple `PsiFile` instances.
@ -18,9 +18,9 @@ A `FileViewProvider` instance corresponds to a single `VirtualFile`, a single `D
* To get the list of all languages for which PSI trees exist in a file: `fileViewProvider.getLanguages()`
* To get the PSI tree for a particular language: `fileViewProvider.getPsi(language)`, where the `language` parameter can take values of the
[Language](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Language.java)
[Language](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Language.java)
type defined in
[StdLanguages](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/lang/StdLanguages.java)
[StdLanguages](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/lang/StdLanguages.java)
class. For example, to get the PSI tree for XML, use `fileViewProvider.getPsi(StdLanguages.XML)`.
* To find an element of a particular language at the specified offset in the file: `fileViewProvider.findElementAt(offset,language)`
@ -30,10 +30,10 @@ To create a file type that has multiple interspersing trees for different langua
[extension point](http://www.jetbrains.org/intellij/sdk/docs/basics/plugin_structure/plugin_extensions_and_extension_points.html)
available in the IntelliJ Platform core.
This extension point is declared using the
[FileTypeExtensionPoint](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/fileTypes/FileTypeExtensionPoint.java)
[FileTypeExtensionPoint](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/FileTypeExtensionPoint.java)
bean class.
To access this extension point, create a Java class that implements the
[FileViewProviderFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/FileViewProviderFactory.java)
[FileViewProviderFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/FileViewProviderFactory.java)
interface, and in this class, override the `createFileViewProvider` method.
To declare the extension to the _fileType.fileViewProviderFactory_ extension point, to the `<extensions>` section of the plugin.xml file, add the following syntax:

2
basics/architectural_overview/psi_elements.md
View File

@ -8,7 +8,7 @@ PSI elements and operations on the level of individual PSI elements are used to
or
[intention actions](http://www.jetbrains.com/idea/help/intention-actions.html).
The
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
class is the common base class for PSI elements.
## How do I get a PSI element?

12
basics/architectural_overview/psi_files.md
View File

@ -4,12 +4,12 @@ title: PSI Files
A PSI (Program Structure Interface) file is the root of a structure representing the contents of a file as a hierarchy of elements in a particular programming language.
The
[PsiFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFile.java)
[PsiFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFile.java)
class is the common base class for all PSI files, while files in a specific language are usually represented by its subclasses.
For example, the
[PsiJavaFile](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-api/src/com/intellij/psi/PsiJavaFile.java)
[PsiJavaFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-api/src/com/intellij/psi/PsiJavaFile.java)
class represents a Java file, and the
[XmlFile](https://github.com/JetBrains/intellij-community/blob/master/xml/xml-psi-api/src/com/intellij/psi/xml/XmlFile.java)
[XmlFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/xml-psi-api/src/com/intellij/psi/xml/XmlFile.java)
class represents an XML file.
Unlike `VirtualFile` and `Document`, which have application scope (even if multiple projects are open, each file is represented by the same `VirtualFile` instance), PSI has project scope (the same file is represented by multiple PsiFile instances if the file belongs to multiple projects open at the same time).
@ -31,7 +31,7 @@ To iterate over the elements in a file, use `psiFile.accept(new PsiRecursiveElem
## Where does it a PSI file come from?
As PSI is language-dependent, PSI files are created through the
[Language](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Language.java)
[Language](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Language.java)
object, by using the `LanguageParserDefinitions.INSTANCE.forLanguage(language).createFile(fileViewProvider)` method.
Like documents, PSI files are created on demand when the PSI is accessed for a particular file.
@ -43,10 +43,10 @@ Like documents, PSI files are weakly referenced from the corresponding `VirtualF
## How do I create a PSI file?
The
[PsiFileFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFileFactory.java).
[PsiFileFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFileFactory.java).
`getInstance(project).createFileFromText()` method creates an in-memory PSI file with the specified contents.
To save the PSI file to disk, use the
[PsiDirectory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiDirectory.java).
[PsiDirectory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiDirectory.java).
`add()` method.
## How do I get notified when PSI files change?

6
basics/architectural_overview/virtual_file.md
View File

@ -3,7 +3,7 @@ title: Virtual Files
---
A virtual file
[com.intellij.openapi.vfs.VirtualFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) is IntelliJ IDEA's representation of a file in a file system (VFS). Most commonly, a virtual file is a file in your local file system. However, IntelliJ IDEA supports multiple pluggable file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from the CVS repository, and so on.
[com.intellij.openapi.vfs.VirtualFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) is IntelliJ IDEA's representation of a file in a file system (VFS). Most commonly, a virtual file is a file in your local file system. However, IntelliJ IDEA supports multiple pluggable file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from the CVS repository, and so on.
The VFS level deals only with binary content. You can get or set the contents of a VirtualFile as a stream of bytes, but concepts like encodings and line separators are handled on higher system levels.
@ -47,11 +47,11 @@ The `VirtualFileManager.addVirtualFileListener()` method allows you to receive n
#### How do I extend VFS?
To provide an alternative file system implementation (for example, an FTP file system), implement the
[VirtualFileSystem](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileSystem.java)
[VirtualFileSystem](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileSystem.java)
class (most likely you'll also need to implement `VirtualFile`), and register your implementation as an
[application component](http://www.jetbrains.org/intellij/sdk/docs/basics/plugin_structure/plugin_components.html).
To hook into operations performed in the local file system (for example, if you are developing a version control system integration that needs custom rename/move handling), implement the
[LocalFileOperationsHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/vfs/LocalFileOperationsHandler.java)
[LocalFileOperationsHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/vfs/LocalFileOperationsHandler.java)
interface and register it through the`LocalFileSystem.registerAuxiliaryFileOperationsHandler` method.
#### What are the rules for working with VFS?

2
basics/checkout_and_build_community.md
View File

@ -115,7 +115,7 @@ or
## Building and Running from the Command Line
To build the distribution archive of *IntelliJ IDEA Community Edition*, execute
[build.xml](https://github.com/JetBrains/intellij-community/blob/master/build.xml)
[build.xml](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/build.xml)
Ant build script in the root directory of the source code.

14
basics/indexing_and_psi_stubs/file_based_indexes.md
View File

@ -21,11 +21,11 @@ When you access the index, you specify the key that you're interested in and get
## Implementing a File-based Index
A fairly simple file-based index implementation is the
[UI Designer bound forms index](https://github.com/JetBrains/intellij-community/blob/master/plugins/ui-designer/src/com/intellij/uiDesigner/binding/FormClassIndex.java).
[UI Designer bound forms index](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/ui-designer/src/com/intellij/uiDesigner/binding/FormClassIndex.java).
Refer to it as an example to understand this topic better.
Each specific index implementation is a class extending
[FileBasedIndexExtension](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndexExtension.java).
[FileBasedIndexExtension](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndexExtension.java).
A file-base index should be registered in the `<fileBasedIndex>` extension point.
The implementation of a file-based contains of the following main parts:
@ -44,7 +44,7 @@ The implementation of a file-based contains of the following main parts:
The index is automatically rebuilt if the current version differs from the version of the index implementation used to build the index.
If you don't need to associate any value with the files (i.e. your value type is Void), you can simplify the implementation by using
[ScalarIndexExtension](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-impl/src/com/intellij/util/indexing/ScalarIndexExtension.java)
[ScalarIndexExtension](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/util/indexing/ScalarIndexExtension.java)
as the base class.
**Note:** The data returned by `DataIndexer.map()` must depend only on input data passed to the method, and must not depend on any external files.
@ -52,7 +52,7 @@ Otherwise your index will not be correctly updated when the external data change
## Accessing a File-based Index
Access to file-based indexes is performed through the [FileBasedIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndex.java)
Access to file-based indexes is performed through the [FileBasedIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndex.java)
class.
The following primary operations are supported:
@ -74,11 +74,11 @@ The most useful indexes for plugin developers are:
* File name index
Generally, the word index should be accessed indirectly, but using the helper methods in the
[PsiSearchHelper](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/psi/search/PsiSearchHelper.java)
[PsiSearchHelper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/psi/search/PsiSearchHelper.java)
class.
The second index is
[FilenameIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java).
[FilenameIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java).
It provides a quick way to find all files matching a certain file name.
[FileTypeIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-impl/src/com/intellij/psi/search/FileTypeIndex.java)
[FileTypeIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FileTypeIndex.java)
serves a similar goal: it allows to quickly find all files of a certain file type.

12
basics/indexing_and_psi_stubs/stub_indexes.md
View File

@ -22,17 +22,17 @@ You usually don't need to have stubs for things like statements or local variabl
For each element type that you want to store in the stub tree, you need to perform the following steps:
* Define an interface for the stub, derived from the `StubElement` interface ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertyStub.java)).
* Define an interface for the stub, derived from the `StubElement` interface ([example](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertyStub.java)).
* Provide an implementation for the interface ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyStubImpl.java)).
* Provide an implementation for the interface ([example](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyStubImpl.java)).
* Make sure that the interface for the PSI element extends `StubBasedPsiElement` parameterized by the type of the stub interface ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java)).
* Make sure that the interface for the PSI element extends `StubBasedPsiElement` parameterized by the type of the stub interface ([example](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java)).
* Make sure that the implementation class for the PSI element extends `StubBasedPsiElementBase` parameterized by the type of the stub interface ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyImpl.java#L45)). Provide both a constructor that accepts an ASTNode and a constructor which accepts a stub.
* Create a class which implements `IStubElementType` and is parameterized with the stub interface and the actual PSI element interface ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertyStubElementType.java)). Implement the createPsi() and createStub() methods for creating PSI from a stub and vice versa. Implement the serialize() and deserialize() methods for storing the data in a binary stream.
* Create a class which implements `IStubElementType` and is parameterized with the stub interface and the actual PSI element interface ([example](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertyStubElementType.java)). Implement the createPsi() and createStub() methods for creating PSI from a stub and vice versa. Implement the serialize() and deserialize() methods for storing the data in a binary stream.
* Use the class implementing `IStubElementType` as the element type constant when parsing ([example](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesElementTypes.java))
* Use the class implementing `IStubElementType` as the element type constant when parsing ([example](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesElementTypes.java))
* Make sure that all methods in the PSI element interface access the stub data rather than the PSI tree when appropriate ([example: Property.getKey() implementation](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/psi/impl/PropertyImpl.java#L95))
@ -62,7 +62,7 @@ Otherwise the stub tree will not be rebuilt when an external dependency changes,
When building the stub tree, you can at the same time put some data about the stub elements into a number of indexes, which then can be used to find the PSI elements by the corresponding key. Unlike file-based indexes, stub indexes do not support storing custom data as values; the value is always a PSI element. Keys in stub indexes are normally strings (such as class names); other data types are also supported if desired.
A stub index is a class which extends [AbstractStubIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/psi/stubs/AbstractStubIndex.java). In the most common case, when the key type is String, you use a more specific base class, namely [StringStubIndexExtension](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/psi/stubs/StringStubIndexExtension.java).
A stub index is a class which extends [AbstractStubIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/psi/stubs/AbstractStubIndex.java). In the most common case, when the key type is String, you use a more specific base class, namely [StringStubIndexExtension](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/psi/stubs/StringStubIndexExtension.java).
Stub index implementation classes are registered in the `<stubIndex>` extension point.
To put data into an index, you implement the method `IStubElementType.indexStub()` ([example: JavaClassElementType.indexStub()](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-impl/src/com/intellij/psi/impl/java/stubs/JavaClassElementType.java#L189)). This method accepts an `IndexSink` as a parameter, and puts in the index ID and the key for each index in which the element should be stored.

2
basics/persisting_state_of_components.md
View File

@ -5,7 +5,7 @@ title: Persisting State of Components
The IntelliJ Platform provides an API that allows components or services to persist their state between restarts of the IDE.
You can use either a simple API to persist a few values, or persist the state of more complicated components using the
[PersistentStateComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
[PersistentStateComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
interface.
## Using PropertiesComponent for Simple non-roamable Persistence

2
basics/plugin_structure/plugin_actions.md
View File

@ -4,7 +4,7 @@ title: Plugin Actions
*Intellij IDEA* provides the concept of _actions_.
An action is a class, derived from the
[AnAction](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class, whose `actionPerformed` method is called when the menu item or toolbar button is selected.
The system of actions allows plugins to add their own items to IDEA menus and toolbars.
Actions are organized into groups, which, in turn, can contain other groups.

50
basics/plugin_structure/plugin_components.md
View File

@ -15,26 +15,26 @@ There are three kinds of components:
Application-level components are created and initialized when IntelliJ IDEA starts up.
They can be acquired from the
[Application](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/application/Application.java)
[Application](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java)
instance by using the `getComponent(Class)` method.
Project-level components are created for each
[Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java)
[Project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java)
instance in IntelliJ IDEA. (Please note that components may be created even for unopened projects.)
They can be acquired from the Project instance by using the `getComponent(Class)` method.
Module-level components are created for each
[Module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java)
[Module](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java)
in every project loaded in IntelliJ IDEA.
Module-level components can be acquired from a Module instance with the same method.
Every component should have interface and implementation classes specified in the configuration file.
The interface class will be used for retrieving the component from other components, and the implementation class will be used for component instantiation.
Note that two components of the same level (
[Application](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/application/Application.java),
[Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java)
[Application](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java),
[Project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java)
or
[Module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java)
[Module](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java)
) cannot have the same interface class.
Interface and implementation classes may be the same.
@ -48,7 +48,7 @@ It is recommended to name components in `<plugin_name>.<component_name>` form.
### Application Level Components
Optionally, application-level component's implementation class may implement the
[ApplicationComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
[ApplicationComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
interface.
An application component that has no dependencies should have a constructor with no parameters which will be used for its instantiation.
If an application component depends on other application components, it can specify these components as constructor parameters. IntelliJ IDEA will ensure that the components are instantiated in the correct order to satisfy the dependencies.
@ -68,16 +68,16 @@ The IntelliJ interface will help you declare the application component's impleme
3. In the *New Application Component* dialog box that opens, enter the application component name, and then click *OK*.
*IntelliJ IDEA* will generate a new Java class that implements the
[ApplicationComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
[ApplicationComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
interface; register the newly created component in the *plugin.xml* file; add a node to the module tree view; and open the created application component class file in the editor.
### Project Level Components
Project-level component's implementation class may implement the
[ProjectComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
[ProjectComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
interface.
The constructor of a project-level component can have a parameter of the
[Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java)
[Project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java)
type, if it needs the project instance.
It can also specify other application-level or project-level components as parameters, if it depends on those components.
@ -98,14 +98,14 @@ The IDEA interface will help you declare the project component's implementation
3. In the *New Project Component* dialog box that opens, enter the project component name, and then click *OK*.
*IntelliJ IDEA* will generate a new Java class that implements the
[ProjectComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
[ProjectComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
interface; register the newly created component in the *plugin.xml* file; add a node to the module tree view; and open the created application component class file in the editor.
### Module Level Components
Optionally, Module-level component's implementation class may implement the
[ModuleComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
[ModuleComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
interface.
The constructor of a module-level component can have a parameter of the Module type, if it needs the module instance.
It can also specify other application-level, project-level or module-level components as parameters, if it depends on those components.
@ -124,27 +124,27 @@ The IDEA interface will help you declare the module component's implementation c
* In the *New Module Component* dialog box that opens, enter the module component name, and then click *OK*.
*IntelliJ IDEA* will generate a new Java class that implements the
[ModuleComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
[ModuleComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
interface; register the newly created component in the `plugin.xml` file; add a node to the module tree view; and open the created application component class file in the editor.
### Persisting State of Components
The state of every component will be automatically saved and loaded if the component's class implements the
[JDOMExternalizable](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
[JDOMExternalizable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
(deprecated) or
[PersistentStateComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
[PersistentStateComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
interface.
When the component's class implements the
[PersistentStateComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
[PersistentStateComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
interface, the component state is saved in an XML file that you can specify using the
[@State](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/components/State.java)
[@State](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/components/State.java)
and
[@Storage](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/components/Storage.java)
[@Storage](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/components/Storage.java)
annotations in your Java code.
When the component's class implements the
[JDOMExternalizable](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
[JDOMExternalizable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
interface, the components save their state in the following files:
* Project-level components save their state to the project (.ipr) file.
@ -175,27 +175,27 @@ The components are loaded in the following order:
* Creation - constructor is invoked.
* Initialization - the `initComponent` method is invoked (if the component implements the
[ApplicationComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
[ApplicationComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java)
interface).
* Configuration - the `readExternal` method is invoked (if the component implements
[JDOMExternalizable](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
[JDOMExternalizable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
interface), or the `loadState` method is invoked (if the component implements
[PersistentStateComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
[PersistentStateComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java)
and has non-default persisted state).
* For module components, the `moduleAdded` method of the
[ModuleComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
[ModuleComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java)
interface is invoked to notify that a module has been added to the project.
* For project components, the `projectOpened` method of the
[ProjectComponent](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
[ProjectComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
interface is invoked to notify that a project has been loaded.
The components are unloaded in the following order:
* Saving configuration - the `writeExternal` method is invoked (if the component implements the
[JDOMExternalizable](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
[JDOMExternalizable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java)
interface), or the `getState` method is invoked (if the component implements PersistentStateComponent).
* Disposal - the `disposeComponent` method is invoked.

10
basics/plugin_structure/plugin_extensions_and_extension_points.md
View File

@ -33,7 +33,7 @@ To clarify this procedure, consider the following sample section of the plugin.x
The *interface* attribute sets an interface the plugin that contributes to the extension point must implement.
The *beanClass* attribute sets a bean class that specifies one or several properties annotated with the
[@Attribute](https://github.com/JetBrains/intellij-community/blob/master/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java)
[@Attribute](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java)
annotation.
The plugin that contributes to the extension point will read those properties from the plugin.xml file.
To clarify this, consider the following sample `MyBeanClass1` bean class used in the above plugin.xml file:
@ -74,7 +74,7 @@ The child element name must match the name of the extension point you want the e
* If the extension point was declared using the *interface* attribute, for newly added child element, set the *implementation* attribute to the name of the class that implements the specified interface.
* If the extension point was declared using the *beanClass* attribute, for newly added child element, set all attributes annotated with the
[@Attribute](https://github.com/JetBrains/intellij-community/blob/master/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java)
[@Attribute](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java)
annotations in the specified bean class.
To clarify this procedure, consider the following sample section of the plugin.xml file that defines two extensions designed to access the _appStarter_ and _applicationConfigurable_ extension points in the IDEA core and one extension to access the _MyExtensionPoint1_ extension point in a test plugin:
@ -99,11 +99,11 @@ To clarify this procedure, consider the following sample section of the plugin.x
To get a list of extension points available in the *IntelliJ Platform* core, consult the `<extensionPoints>` section of the following XML configuration files:
* [LangExtensionPoints.xml](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-resources/src/META-INF/LangExtensionPoints.xml)
* [LangExtensionPoints.xml](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/LangExtensionPoints.xml)
* [PlatformExtensionPoints.xml](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml)
* [PlatformExtensionPoints.xml](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml)
* [VcsExtensionPoints.xml](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-resources/src/META-INF/VcsExtensionPoints.xml)
* [VcsExtensionPoints.xml](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/VcsExtensionPoints.xml)
## Additional Information and Samples

2
basics/plugin_structure/plugin_services.md
View File

@ -4,7 +4,7 @@ title: Plugin Services
*IntelliJ Platform* provides the concept of _services_.
A _service_ is a plugin component loaded on demand, when your plugin calls the `getService` method of the
[ServiceManager](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ServiceManager.java)
[ServiceManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ServiceManager.java)
class.
*IntelliJ Platform* ensures that only one instance of a service is loaded even though the service is called several times.
A service must have the interface and implementation classes specified in the plugin.xml file.

32
basics/project_structure.md
View File

@ -95,10 +95,10 @@ As for the file-based format projects, .IML files describe modules.
To work with projects and project files, you can use the following classes and interfaces:
* [Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java) interface.
* [ProjectRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class.
* [ProjectManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class.
* [ProjectFileIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) interface.
* [Project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java) interface.
* [ProjectRootManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class.
* [ProjectManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class.
* [ProjectFileIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) interface.
Note that you don't need to access project files directly to load or save settings.
See
@ -194,13 +194,13 @@ Note that by default, the project modules use the project SDK. Optionally, you c
*IntelliJ Platform* provides a number of Java classes and interfaces you can use to work with modules:
* [ModuleManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class.
* [Module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java) interface.
* [ModuleRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class.
* [ModuleRootModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface.
* [ModuleUtil](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class.
* [ModifiableModuleModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface.
* [ModifiableRootModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModifiableRootModel.java) interface.
* [ModuleManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class.
* [Module](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java) interface.
* [ModuleRootManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class.
* [ModuleRootModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface.
* [ModuleUtil](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class.
* [ModifiableModuleModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface.
* [ModifiableRootModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModifiableRootModel.java) interface.
This section discusses how to complete some common tasks related to management of modules.
@ -217,7 +217,7 @@ tab of the *Project Structure* dialog box.
To explore the
[module dependencies](http://www.jetbrains.com/idea/help/dependencies-tab.html),
use the
[OrderEnumerator](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/OrderEnumerator.java)
[OrderEnumerator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/OrderEnumerator.java)
class.
The following code snippet illustrates how you can get classpath (classes root of all dependencies) for a module:
@ -230,7 +230,7 @@ VirtualFile[] roots = ModuleRootManager.getInstance(module).orderEntries().class
Use the `ModuleRootManager.getSdk()` method.
This method returns a value of the
[Sdk](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/projectRoots/Sdk.java)
[Sdk](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/projectRoots/Sdk.java)
type.
The following code snippet illustrates how you can get detailed information on SDK the specified module uses:
@ -313,13 +313,13 @@ Messages.showInfoMessage(roots.toString(), "Library Info");
```
In this sample code, `lib` is of the
[Library](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/libraries/Library.java)
[Library](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/libraries/Library.java)
type.
#### How do I get a set of facets the module includes?
Use the
[FacetManager](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/facet/FacetManager.java)
[FacetManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/facet/FacetManager.java)
and
[Facet](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/facet/Facet.java)
[Facet](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/facet/Facet.java)
classes.

24
basics/run_configurations/run_configuration_execution.md
View File

@ -23,7 +23,7 @@ The standard execution of a run action goes through the following steps:
## Executor
The
[Executor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/Executor.java)
[Executor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/Executor.java)
interface describes a specific way of executing any possible run configuration.
The three default executors provided by the IntelliJ Platform by default are _Run_, _Debug_ and (in IntelliJ IDEA Ultimate and certain platform-based IDEs) _Run with Coverage_.
Each executor gets its own toolbar button, which starts the selected run configuration using this executor, and its own context menu item for starting a configuration using this executor.
@ -38,22 +38,22 @@ It describes a process which is ready to be started and holds the information li
(The existence of RunProfileState as a separate step in the execution flow allows run configuration extensions and other components to patch the configuration and to modify the parameters before it gets executed.)
The standard base class used as implementation of RunProfileState is
[CommandLineState](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/CommandLineState.java).
[CommandLineState](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/CommandLineState.java).
It contains the logic for putting together a running process and a console into an
[ExecutionResult](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/ExecutionResult.java),
[ExecutionResult](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/ExecutionResult.java),
but doesn't know anything how the process is actually started. For starting the process, it's best to use the
[GeneralCommandLine](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/execution/configurations/GeneralCommandLine.java)
[GeneralCommandLine](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/execution/configurations/GeneralCommandLine.java)
class, which takes care of setting up the command line parameters and executing the process.
Alternatively, if the process you need to run is a JVM-based one, you can use the
[JavaCommandLineState](https://github.com/JetBrains/intellij-community/blob/master/java/execution/openapi/src/com/intellij/execution/configurations/JavaCommandLineState.java)
[JavaCommandLineState](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/execution/openapi/src/com/intellij/execution/configurations/JavaCommandLineState.java)
base class. It knows about the command line parameters of the JVM and can take care of details like calculating the classpath for the JVM.
To monitor the execution of a process and capture its output, the
[OSProcessHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/execution/process/OSProcessHandler.java)
[OSProcessHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/execution/process/OSProcessHandler.java)
class is normally used.
Once you've created an instance of OSProcessHandler from either a command line or a Process object, you need to call the `startNotify()` method to start capturing its output.
You may also want to attach a [ProcessTerminatedListener](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/execution/process/ProcessTerminatedListener.java)
You may also want to attach a [ProcessTerminatedListener](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/execution/process/ProcessTerminatedListener.java)
to the OSProcessHandler, so that the exit status of the process will be displayed in the console.
## Displaying the Process Output
@ -62,22 +62,22 @@ If you're using `CommandLineState`, a console view will be automatically created
Alternatively, you can arrange this yourself:
* `TextConsoleBuilderFactory.createBuilder(project).getConsole()` creates a
[ConsoleView](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/ui/ConsoleView.java)
[ConsoleView](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/ui/ConsoleView.java)
instance;
* `ConsoleView.attachToProcess()` attaches it to the output of a process.
If the process you're running uses ANSI escape codes to color its output, the
[ColoredProcessHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/execution/process/ColoredProcessHandler.java)
[ColoredProcessHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/execution/process/ColoredProcessHandler.java)
class will parse it and display the colors in the IntelliJ console.
Console
[filters](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/filters/Filter.java)
[filters](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/filters/Filter.java)
allow you to convert certain strings found in the process output to clickable hyperlinks. To attach a filter to the console, use `CommandLineState.addConsoleFilters()` or, if you're creating a console manually, `TextConsoleBuilder.addFilter()`.
Two common filter implementations you may want to reuse are
[RegexpFilter](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/filters/RegexpFilter.java)
[RegexpFilter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/filters/RegexpFilter.java)
and
[UrlFilter](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/filters/UrlFilter.java).
[UrlFilter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/filters/UrlFilter.java).
## Starting a Run Configuration from Code

28
basics/run_configurations/run_configuration_management.md
View File

@ -10,14 +10,14 @@ This document describes main classes to work with run configurations and common
## ConfigurationType
The starting point for implementing any run configuration type is the
[ConfigurationType](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
[ConfigurationType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
interface.
List of available configuration type is shown when a user opens _'Edit run configurations'_ dialog and executes _'Add'_ action:
![Create](/basics/img/create-1.png)
Every type there is represented as an instance of
[ConfigurationType](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
[ConfigurationType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
and registered like below:
```xml
@ -25,14 +25,14 @@ and registered like below:
```
The easiest way to implement this interface is to use the
[ConfigurationTypeBase](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationTypeBase.java) base class. In order to use it, you need to inherit from it and to provide the configuration type parameters (ID, name, description and icon) as constructor parameters. In addition to that, you need to call the
[ConfigurationTypeBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationTypeBase.java) base class. In order to use it, you need to inherit from it and to provide the configuration type parameters (ID, name, description and icon) as constructor parameters. In addition to that, you need to call the
[addFactory()](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationTypeBase.java#L46)
method to add a configuration factory.
## ConfigurationFactory
All run configurations are created by
[ConfigurationFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java)
[ConfigurationFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java)
registered for particular _ConfigurationType_.
It's possible that one _ConfigurationType_
[has more than one](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java#L34)
@ -41,7 +41,7 @@ _ConfigurationFactory_:
![Configuration Factory](/basics/img/create-3.png)
The key API of
[ConfigurationFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java),
[ConfigurationFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java),
and the only method that you're required to implement, is the
[createTemplateConfiguration](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java#L45)
method.
@ -60,7 +60,7 @@ These additional overrides are optional.
## RunConfiguration
Is represented by
[RunConfiguration](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
[RunConfiguration](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
interface.
_'Run configuration'_ here is some named profile which can be executed, e.g. application started via _'main()'_ class, test, remote debug to particular machine/port etc.
Here is an example of a Java run configurations defined for a particular project:
@ -69,14 +69,14 @@ Here is an example of a Java run configurations defined for a particular project
When implementing a run configuration, you may want to use one of the common base classes:
* [RunConfigurationBase](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RunConfigurationBase.java)
* [RunConfigurationBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfigurationBase.java)
is a general-purpose superclass that contains the most basic implementation of a run configuration.
* [LocatableConfigurationBase](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java)
* [LocatableConfigurationBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java)
is a common base class that should be used for configurations that can be created from context by a `RunConfigurationProducer`.
It supports automatically generating a name for a configuration from its settings and keeping track of whether the name was changed by the user.
* [ModuleBasedConfiguration](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ModuleBasedConfiguration.java)
* [ModuleBasedConfiguration](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ModuleBasedConfiguration.java)
is a base class for a configuration that is associated with a specific module (for example, Java run configurations use the selected module to determine the run classpath).
## SettingsEditor
@ -100,11 +100,11 @@ That is performed via
and
[readExternal()](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java#L26)
methods of
[RunConfiguration](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
[RunConfiguration](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
class correspondingly.
The actual configurations stored by the IntelliJ Platform are represented by instances of the
[RunnerAndConfigurationSettings](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/RunnerAndConfigurationSettings.java)
[RunnerAndConfigurationSettings](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/RunnerAndConfigurationSettings.java)
class, which combines a run configuration with runner-specific settings, as well as keeping track of certain run configuration flags such as "temporary" or "singleton".
Dealing with instances of this class becomes necessary when you need to create run configurations from code. This is accomplished with the following two steps:
@ -119,14 +119,14 @@ Dealing with instances of this class becomes necessary when you need to create r
Most run configurations contain references to classes, files or directories in their settings, and these settings usually need to be updated when the corresponding element is renamed or moved.
In order to support that, your run configuration needs to implement the
[RefactoringListenerProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RefactoringListenerProvider.java)
[RefactoringListenerProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RefactoringListenerProvider.java)
interface.
In your implementation of `getRefactoringElementListener()`, you need to check whether the element being refactored is the one that your run configuration refers to, and if it is, you return a `RefactoringElementListener` that updates your configuration according to the new name and location of the element.
## Creating Configurations from Context
Many plugins support automatic creation of run configurations from context, so that the user can click, for example, on an application or test class and automatically run it using the correct run configuration type. In order to support that, you need to provide an implementation of the
[RunConfigurationProducer](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/actions/RunConfigurationProducer.java)
[RunConfigurationProducer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/actions/RunConfigurationProducer.java)
interface and to register it as `<runConfigurationProducer>` in your plugin.xml.
(Note that this API has been redesigned in IntelliJ IDEA 13; `RuntimeConfigurationProducer` is an older and much more confusing version of the same API).
@ -140,5 +140,5 @@ The two main methods that you need to implement are:
Implementing this method allows you to reuse an existing run configuration which is applicable to the current context instead of creating a new one and possibly ignoring the customisations the user has performed in the existing one.
Note that, in order to support automatic naming of configurations created from context, your configuration should use
[LocatableConfigurationBase](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java)
[LocatableConfigurationBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java)
as the base class.

2
basics/virtual_file_system.md
View File

@ -65,7 +65,7 @@ Both synchronous and asynchronous refreshes can be initiated from any thread.
If a refresh is initiated from a background thread, the calling thread must not hold a read action, because otherwise a deadlock would occur.
See [IntelliJ Platform Architectural Overview] for more details on the threading model and read/write actions.
The same threading requirements also apply to functions like
[LocalFileSystem.refreshAndFindFileByPath()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/vfs/LocalFileSystem.java),
[LocalFileSystem.refreshAndFindFileByPath()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/vfs/LocalFileSystem.java),
which perform a partial refresh if the file with the specified path is not found in the snapshot.
In nearly all cases, using asynchronous refreshes is strongly preferred.

22
drafts/project_model.md
View File

@ -85,11 +85,11 @@ As for the file-based format projects, .IML files describe modules.
Main classes providing work with the project model are located in the package
[projectModel-api.openapi](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi).
Basic API classes and interfaces for the concepts of
[project] (https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java),
[module] (https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java),
[application] (https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/application/Application.java),
[project] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java),
[module] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java),
[application] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java),
and
[component] (https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
[component] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
are placed in the
[core-api.openapi] (https://github.com/JetBrains/intellij-community/tree/master/platform/core-api/src/com/intellij/openapi)
package.
@ -102,7 +102,7 @@ To clarify this, see the following:
[code sample] (https://github.com/JetBrains/intellij-sdk/blob/master/code_samples/project_model/src/com/intellij/plugins/project/model/ShowSourceRootsActions.java).
##How do I check whether a file is related to a project?
Use [ProjectFileIndex.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
Use [ProjectFileIndex.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
to get this information.
###How do I get an instance of the ProjectFileIndex interface?
@ -155,11 +155,11 @@ Note that by default, the project modules use the project SDK. Optionally, you c
###How to get a module file index?
Information about model roots can be accessed via the class
[ModuleRootManager.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java),
[ModuleRootManager.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java),
for example, an instance of
[ModuleFileIndex.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java)
[ModuleFileIndex.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java)
can be obtained, which is analogical to the
[ProjectFileIndex.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
[ProjectFileIndex.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
but in the scope of a module
`ModuleRootManager.getInstance(currentModule).getFileIndex()`
@ -170,9 +170,9 @@ Utility classes which can be used for modifying a project structure can be found
It's
[roots] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-impl/src/com/intellij/openapi/roots/)
subpackage contains instances and utilities meant to work with project and module source roots, including
[ModuleRootModificationUtil.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-impl/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java)
[ModuleRootModificationUtil.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-impl/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java)
and
[ProjectRootUtil.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java)
[ProjectRootUtil.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java)
A basic example can be viewed
[here] (https://github.com/JetBrains/intellij-sdk/blob/master/code_samples/project_model/src/com/intellij/plugins/project/model/ModificationAction.java)
@ -191,7 +191,7 @@ More details can be found in this
##Project Sdk information
Main information about the project Sdk can be accessed via
[ProjectRootManager.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
[ProjectRootManager.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
like the following example shows
`String projectSdk = ProjectRootManager.getInstance(project).getProjectSdk();`

18
drafts/project_wizard/project_wizard.md
View File

@ -8,7 +8,7 @@ Working with the project wizard can be excessively illustrated with the followin
##Implementing new module type
Additional support for specific tools and technologies is usually done via implementing some certain module type which is attached to the project.
New module type should be derived from the class
[ModuleType.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java).
[ModuleType.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java).
[Code sample] (https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleType.java)
@ -28,16 +28,16 @@ To create a new module type and an extension
`<moduleType id="MY_MODULE" implementationClass="st.redline.smalltalk.module.MyModuleType"/>`
to the [plugin.xml] (https://github.com/bulenkov/RedlineSmalltalk/blob/master/resources/META-INF/plugin.xml).
A custom module type should extend the
[ModuleType.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java)
[ModuleType.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java)
generic from
[ModuleBuilder.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java).
[ModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java).
The following
[sample] (https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleType.java)
of a custom module type show how this instance can be registered and implemented.
###Implementing module builder
To set up a new module environment
[ModuleBuilder.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java)
[ModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java)
class should be extended and registered as an extension point like the following snippet shows:
<extensions>
@ -51,22 +51,22 @@ Functionality which is mandatory to implement consists of:
* Getting a module type `public abstract ModuleType getModuleType();`
See
[JavaModuleBuilder.java] (https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
[JavaModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
to understand better how to implement a module builder.
If your module type is based on the java module and meant to support Java as well, extending
[JavaModuleBuilder.java] ((https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java))
[JavaModuleBuilder.java] ((https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java))
is enough. No extension point needs no be registered.
A [code sample] (https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleType.java)
illustrating how
[JavaModuleBuilder.java] (https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
[JavaModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
can be derived.
###Implementing module builder listener
Module builder listener reacts on a new module creation, which could be done either as a part of the project creation process,
or as adding a new module to the already existing project.
To provide a certain behavior right after a module has been created, module builder should implement
[ModuleBuilderListener.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java)
[ModuleBuilderListener.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java)
Method `public void moduleCreated(@NotNull final Module module);` executed tasks right after a module has been created,
these may include configuring roots looking up for an SDK and setting it up, adding a specific facet if required and others.
For more details please see this
@ -82,7 +82,7 @@ This
[code sample] (https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleWizardStep.java)
illustrates how a custom wizard step can be created.
This class is derived from
[ModuleWizardStep.java] (https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java),
[ModuleWizardStep.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java),
which has two methods to be overridden:
* `public JComponent getComponent();` defines how the step will look like

34
reference_guide/custom_language_support/additional_minor_features.md
View File

@ -4,9 +4,9 @@ title: Additional Minor Features
In order to implement *brace matching*, once the syntax highlighting lexer has been implemented, all that is required is to implement the
[PairedBraceMatcher](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/PairedBraceMatcher.java)
[PairedBraceMatcher](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/PairedBraceMatcher.java)
interface and to return an array of brace pairs (
[BracePair](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/BracePair.java)
[BracePair](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/BracePair.java)
) for the language.
Each brace pair specifies the characters for the opening and closing braces and the lexer token types for these characters.
(In principle, it is possible to return multi-character tokens, like "begin" and "end", as the start and end tokens of a brace pair.
@ -16,36 +16,36 @@ Certain types of braces can be marked as structural.
Structural braces have higher priority than regular braces: they are matched with each other even if there are unmatched braces of other types between them, and an opening non-structural braces is not matched with a closing one if one of them is inside a pair of matched structural braces and another is outside.
The *code folding* is controlled by the plugin through the
[FoldingBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/folding/FoldingBuilder.java)
[FoldingBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/folding/FoldingBuilder.java)
interface.
The interface returns the list of text ranges which are foldable (as an array of
[FoldingDescriptor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java)
[FoldingDescriptor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java)
objects), the replacement text which is shown for each range when it is folded, and the default state of each folding region (folded or unfolded).
The *Comment Code* feature is controlled through the
[Commenter](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Commenter.java)
[Commenter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Commenter.java)
interface.
The interface can return the prefix for the line comment, and the prefix and suffix for the block comment, if such features are supported by the language.
**Example:**
[Commenter](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesCommenter.java)
[Commenter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesCommenter.java)
for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)
To support smart/semantic *Join Lines* see
[JoinLinesHandlerDelegate](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java).
[JoinLinesHandlerDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java).
*Smart Enter* (e.g. autocomplete missing semicolon/parentheses) can be provided via
[SmartEnterProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java).
[SmartEnterProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java).
*Naming suggestions* for Rename Refactoring can be provided via
[NameSuggestionProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/refactoring/rename/NameSuggestionProvider.java).
[NameSuggestionProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/refactoring/rename/NameSuggestionProvider.java).
*Semantic highlight usages* (e.g. exit points) can be achieved using
[HighlightUsagesHandlerFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-impl/src/com/intellij/codeInsight/highlighting/HighlightUsagesHandlerFactory.java).
[HighlightUsagesHandlerFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/codeInsight/highlighting/HighlightUsagesHandlerFactory.java).
*View\|Parameter Info* is provided via
[ParameterInfoHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/parameterInfo/ParameterInfoHandler.java)
[ParameterInfoHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/parameterInfo/ParameterInfoHandler.java)
(extension point `codeInsight.parameterInfo`).
The *To Do view* is supported automatically if the plugin provides a correct implementation of the
@ -54,19 +54,19 @@ method.
The *View \| Context Info* feature is supported for custom languages since IntelliJ IDEA 10.5.
In order for it to work, you need to have a structure view implementation based on a
[TreeBasedStructureViewBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java),
[TreeBasedStructureViewBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java),
and additionally to provide an implementation of
[DeclarationRangeHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/hint/DeclarationRangeHandler.java)
[DeclarationRangeHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/hint/DeclarationRangeHandler.java)
for your language and to register it in the `declarationRangeHandler` extension point.
*Spellchecking* can be provided via EP `spellchecker.support` (
[SpellcheckingStrategy](https://github.com/JetBrains/intellij-community/blob/master/spellchecker/src/com/intellij/spellchecker/tokenizer/SpellcheckingStrategy.java)
[SpellcheckingStrategy](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/spellchecker/src/com/intellij/spellchecker/tokenizer/SpellcheckingStrategy.java)
) where you can return
[Tokenizer](https://github.com/JetBrains/intellij-community/blob/master/spellchecker/src/com/intellij/spellchecker/tokenizer/Tokenizer.java)
[Tokenizer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/spellchecker/src/com/intellij/spellchecker/tokenizer/Tokenizer.java)
to use, possibly depending on the passed in
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
(or `EMPTY_TOKENIZER` for no spellchecking).
New in 13: user-configurable *reference injections* can be provided via `referenceInjector` extension point (
[ReferenceInjector](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/psi/injection/ReferenceInjector.java)
[ReferenceInjector](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/injection/ReferenceInjector.java)
) (IntelliLang plugin required).

20
reference_guide/custom_language_support/code_completion.md
View File

@ -10,32 +10,32 @@ Contributor-based completion provides more features, supports all three completi
### Reference Completion
To fill the completion list, the IDE calls
[PsiReference.getVariants()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference.getVariants()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
either on the reference at the caret location or on a dummy reference that would be placed at the caret.
This method needs to return an array of objects containing either strings,
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
instances or instances of the
[LookupElement](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java)
[LookupElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java)
class.
If a
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
instance is returned in the array, the completion list shows the icon for the element.
The most common way to implement `getVariants()` is to use the same function for walking up the tree as in
[PsiReference.resolve()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java),
[PsiReference.resolve()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java),
and a different implementation of
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
which collects all declarations passed to its `processDeclarations()` method and returns them as an array for filling the completion list.
### Contributor-based Completion
Implementing the
[CompletionContributor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java)
[CompletionContributor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java)
interface gives you the greatest control over the operation of code completion for your language.
Note that the JavaDoc of that class contains a detailed FAQ for implementing code completion.
The core scenario of using
[CompletionContributor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java)
[CompletionContributor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java)
consists of calling the `extend()` method and passing in the *pattern* specifying the context in which this completion variant is applicable, as well as a *completion provider* which generates the items to show in the completion list.
**Example**:
@ -44,10 +44,10 @@ for completing keywords in MANIFEST.MF files.
Items shown in the completion list are represented by instances of the
[LookupElement](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java)
[LookupElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java)
interface.
These instances are normally created through the
[LookupElementBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElementBuilder.java)
[LookupElementBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElementBuilder.java)
class.
For every lookup element, you can specify the following attributes:

18
reference_guide/custom_language_support/code_formatting.md
View File

@ -8,13 +8,13 @@ In this framework, the plugin specifies the *constraints* on the spacing between
The process of formatting a file or a file fragment consists of the following main steps:
* The _formatting model builder_ (
[FormattingModelBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/FormattingModelBuilder.java)
[FormattingModelBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/FormattingModelBuilder.java)
), implemented by the plugin, provides a formatting model (
[FormattingModel](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/FormattingModel.java)
[FormattingModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/FormattingModel.java)
) for the document to be formatted
* The formatting model is requested to build the structure of the file as applies to formatting, as a tree of _blocks_ (
[Block](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/Block.java)
[Block](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Block.java)
) with associated indent, wrap, alignment and spacing settings.
* The formatting engine calculates the sequence of whitespace characters (spaces, tabs and/or line breaks) that needs to be placed at every block boundary, based on the formatting model provided by the plugin.
@ -28,7 +28,7 @@ If the formatting operation does not affect the entire file (for example, if the
For every block, the plugin specifies the following properties:
* The _spacing_ (
[Spacing](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/Spacing.java)
[Spacing](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Spacing.java)
) specifies what spaces or line breaks are inserted between the specified children of the block.
The spacing object specifies the minimum and maximum number of spaces that must be placed between the specified child blocks, the minimum number of line breaks to place there, and whether the existing line breaks and blank lines should be preserved.
The formatting model can also specify that the spacing between the specified blocks may not be modified by the formatter.
@ -39,19 +39,19 @@ For every block, the plugin specifies the following properties:
If the formatting model does not specify an indent, the "continuation without first" mode is used, which means that the first block in a sequence of blocks with that type is not indented and the following blocks are indented with a continuation indent.
* The _wrap_ (
[Wrap](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/Wrap.java)
[Wrap](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Wrap.java)
) specifies whether the content of the block is wrapped to the next line.
Wrapping is performed by inserting a line break before the block content.
The plugin can specify that a particular block is never wrapped, always wrapped, or wrapped only if it exceeds the right margin.
* The _alignment_ (
[Alignment](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/Alignment.java)
[Alignment](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Alignment.java)
) specifies which blocks should be aligned with each other.
If two blocks with the alignment property set to the same object instance are placed in different lines, and if the second block is the first non-whitespace block in its line, the formatter inserts white spaces before the second block so that it starts from the same column as the first one.
For each of these properties, a number of special use settings exists, which are described in the JavaDoc comments for the respective classes.
See also
[SpacingBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/formatting/SpacingBuilder.java)
[SpacingBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/SpacingBuilder.java)
which aids in building rule-based configuration.
An important special case in using the formatter is the smart indent performed when the user presses the `Enter` key in a source code file.
@ -64,7 +64,7 @@ Code formatting can be suppressed per region via [special comments](http://youtr
### Code Style Settings
To specify the default indent size for the language provided by your plugin, and to allow the user to configure the tab size and indent size you need to implement the
[FileTypeIndentOptionsProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/psi/codeStyle/FileTypeIndentOptionsProvider.java)
[FileTypeIndentOptionsProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/codeStyle/FileTypeIndentOptionsProvider.java)
interface and to register the implementation in the `fileTypeIndentOptionsProvider` extension point.
The return value of `createIndentOptions()` determines the default indent size.
@ -75,5 +75,5 @@ The return value of `createIndentOptions()` determines the default indent size.
Allows custom languages to provide user-configurable arrangement/grouping rules for element types supported by language plugin.
Rules can be refined via modifiers and name, ordering can be applied additionally.
Please see
[Rearranger](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java)
[Rearranger](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java)
and related for JavaDoc.

16
reference_guide/custom_language_support/code_inspections_and_intentions.md
View File

@ -3,33 +3,33 @@ title: Code Inspections and Intentions
---
The code inspections for custom languages use the same API as all other code inspections, based on the
[LocalInspectionTool](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
[LocalInspectionTool](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
class.
The functionality of
[LocalInspectionTool](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
[LocalInspectionTool](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
partially duplicates that of
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java).
[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java).
The main differences are that
[LocalInspectionTool](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
[LocalInspectionTool](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java)
supports batch analysis of code (through the **Analyze \| Inspect Code...** action), the possibility to turn off the inspection (globally or by suppressing them on various levels) and to configure the inspection options.
If none of that is required and the analysis only needs to run in the active editor,
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
provides better performance (because of its support for incremental analysis) and more flexibility for highlighting errors.
**Example**:
A
[simple inspection](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/codeInspection/TrailingSpacesInPropertyInspection.java)
[simple inspection](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/codeInspection/TrailingSpacesInPropertyInspection.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)
The code intentions for custom languages also use the regular API for intentions.
The intention classes need to implement the
[IntentionAction](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java)
[IntentionAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java)
interface and to be registered using the `<intentionAction>` bean in your *plugin.xml*.
**Example:**
A
[simple intention action](https://github.com/JetBrains/intellij-community/blob/master/plugins/groovy/src/org/jetbrains/plugins/groovy/intentions/control/SplitIfIntention.java)
[simple intention action](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/groovy/src/org/jetbrains/plugins/groovy/intentions/control/SplitIfIntention.java)
for Groovy

6
reference_guide/custom_language_support/documentation.md
View File

@ -3,13 +3,13 @@ title: Documentation
---
To provide different kinds of documentation support (tooltips on **Ctrl-hover**, quick documentation popup etc.), the plugin needs to provide an implementation of the
[DocumentationProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/documentation/DocumentationProvider.java)
[DocumentationProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/documentation/DocumentationProvider.java)
interface and register it in the `lang.documentationProvider` extension point.
A standard base class for such implementations is available in the class
[AbstractDocumentationProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/documentation/AbstractDocumentationProvider.java).
[AbstractDocumentationProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/documentation/AbstractDocumentationProvider.java).
**Example**:
[DocumentationProvider](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java)
[DocumentationProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)

46
reference_guide/custom_language_support/find_usages.md
View File

@ -4,16 +4,16 @@ title: Find Usages
The `Find Usages` action is a multi-step process, and each step of the process requires involvement from the custom language plugin.
The language plugin participates in the Find Usages process by registering an implementation of
[FindUsagesProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
[FindUsagesProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
in the `com.intellij.lang.findUsagesProvider` extension point, and through the PSI implementation using
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
and
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
interfaces.
**Example**:
Implementation of
[FindUsagesProvider](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/findUsages/PropertiesFindUsagesProvider.java)
[FindUsagesProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/findUsages/PropertiesFindUsagesProvider.java)
in
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)
@ -22,65 +22,65 @@ The steps of the `Find Usages` action are the following:
* Before the `Find Usages` action can be invoked, the IDE builds an index of words present in every file in the custom language.
Using the
[WordsScanner](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/cacheBuilder/WordsScanner.java)
[WordsScanner](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/WordsScanner.java)
implementation returned from
[FindUsagesProvider.getWordsScanner()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java),
[FindUsagesProvider.getWordsScanner()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java),
the contents of every file are loaded and passes it to the words scanner, along with the words consumer.
The words scanner breaks the text into words, defines the context for each word (code, comments or literals) and passes the word to the consumer.
The simplest way to implement the words scanner is to use the
[DefaultWordsScanner](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java)
[DefaultWordsScanner](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java)
implementation, passing to it the sets of lexer token types which are treated as identifiers, literals and comments.
The default words scanner will use the lexer to break the text into tokens, and will handle breaking the text of comment and literal tokens into individual words.
* When the user invokes the Find Usages action, the IDE locates the PSI element the references to which will be searched.
The PSI element at the cursor (the direct tree parent of the token at the cursor position) must be either a
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
or a
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
which resolves to a
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java).
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java).
The word cache will be used to search for the text returned from the
[PsiNamedElement.getName()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement.getName()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
method.
Also, if the text range of the
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
includes some other text besides the identifier returned from `getName()` (for example, if the
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
represents a JavaScript function and its text range includes the "`function`" keyword in addition to the name of the function), the method `getTextOffset()` must be overridden for the
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java),
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java),
and must return the start offset of the name identifier within the text range of the element.
* Once the element is located, the IDE calls
[FindUsagesProvider.canFindUsagesFor()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
[FindUsagesProvider.canFindUsagesFor()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
to ask the plugin if the Find Usages action is applicable to the specific element.
* When showing the Find Usages dialog to the user,
[FindUsagesProvider.getType()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
[FindUsagesProvider.getType()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
and
[FindUsagesProvider.getDescriptiveName()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
[FindUsagesProvider.getDescriptiveName()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
are called to determine how the element should be presented to the user.
* For every file containing the searched words, the IDE builds the PSI tree and recursively descends that tree.
The text of each element is broken into words and then scanned.
If the element was indexed as an identifier, every word is checked to be a
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
resolving to the element the usages of which are searched.
If the element was indexed as a comment or literal and the search in comments or literals is enabled, it checks if the word is equal to the name of the searched element.
* After the usages are collected, results are shown in the usages pane.
The text shown for each found element is taken from the
[FindUsagesProvider.getNodeText()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
[FindUsagesProvider.getNodeText()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java)
method.
To have the title of the found element be correctly displayed in the title of the Find Usages toolwindow, you need to provide an implementation of the
[ElementDescriptionProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/ElementDescriptionProvider.java)
[ElementDescriptionProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/ElementDescriptionProvider.java)
interface.
The
[ElementDescriptionLocation](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/ElementDescriptionLocation.java)
[ElementDescriptionLocation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/ElementDescriptionLocation.java)
passed to the provider in this case will be an instance of
[UsageViewLongNameLocation](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-impl/src/com/intellij/usageView/UsageViewLongNameLocation.java).
[UsageViewLongNameLocation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/usageView/UsageViewLongNameLocation.java).
**Example:**
[ElementDescriptionProvider](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/PropertiesDescriptionProvider.java)
[ElementDescriptionProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesDescriptionProvider.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)

6
reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md
View File

@ -4,12 +4,12 @@ title: Go to Class and Go to Symbol
A custom language plugin can provide its own items to be included in the lists shown when the user chooses the `Go to | Class...` or `Go to | Symbol...` action.
In order to do so, the plugin must provide implementations for the
[ChooseByNameContributor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/navigation/ChooseByNameContributor.java)
[ChooseByNameContributor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/navigation/ChooseByNameContributor.java)
interface (separate implementations need to be provided for `Go to Class` and `Go to Symbol`), and register them in the `com.intellij.gotoClassContributor` and `com.intellij.gotoSymbolContributor` extension points.
Each contributor needs to be able to return a complete list of names to show in the list for a specified project, which will then be filtered by the IDE according to the text typed by the user in the dialog.
For each name in that list, the contributor needs to provide a list of
[NavigationItem](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/navigation/NavigationItem.java)
[NavigationItem](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/navigation/NavigationItem.java)
instances (typically
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
), which specify the destinations to jump to when a specific name is selected from the list.

36
reference_guide/custom_language_support/implementing_lexer.md
View File

@ -7,48 +7,48 @@ The lexer, or
defines how the contents of a file is broken into tokens.
The lexer serves as a foundation for nearly all of the features of custom language plugins, from basic syntax highlighting to advanced code analysis features.
The API for the lexer is defined by the
[Lexer](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/Lexer.java) interface.
[Lexer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java) interface.
The IDE invokes the lexer in three main contexts, and the plugin can provide different lexer implementations for these contexts:
* Syntax highlighting: The lexer is returned from the implementation of the
[SyntaxHighlighterFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterFactory.java)
[SyntaxHighlighterFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterFactory.java)
interface which is registered in the `com.intellij.lang.syntaxHighlighterFactory` extension point.
* Building the syntax tree of a file: the lexer is expected to be returned from
[ParserDefinition.createLexer()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java),
[ParserDefinition.createLexer()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java),
and the
[ParserDefinition](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
[ParserDefinition](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
interface is registered in the `com.intellij.lang.parserDefinition` extension point.
* Building the index of the words contained in the file:
if the lexer-based words scanner implementation is used, the lexer is passed to the
[DefaultWordsScanner](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java)
[DefaultWordsScanner](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java)
constructor.
The lexer used for syntax highlighting can be invoked incrementally to process only the changed part of a file, whereas lexers used in other contexts are always called to process an entire file, or a complete language construction embedded in a file in a different language.
A lexer that can be used incrementally may need to return its *state*, which means the context corresponding to each position in a file.
For example, a
[Java lexer](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-impl/src/com/intellij/lang/java/lexer/JavaLexer.java)
[Java lexer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-impl/src/com/intellij/lang/java/lexer/JavaLexer.java)
could have separate states for top level context, comment context and string literal context.
An important requirement for a syntax highlighting lexer is that its state must be represented by a single integer number returned from
[Lexer.getState()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/Lexer.java).
[Lexer.getState()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java).
That state will be passed to the
[Lexer.start()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/Lexer.java)
[Lexer.start()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java)
method, along with the start offset of the fragment to process, when lexing is resumed from the middle of a file.
Lexers used in other contexts can always return `0` from the `getState()` method.
The easiest way to create a lexer for a custom language plugin is to use [JFlex](http://jflex.de).
Adapter classes,
[FlexLexer](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/FlexLexer.java)
[FlexLexer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexLexer.java)
and
[FlexAdapter](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/FlexAdapter.java)
[FlexAdapter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexAdapter.java)
adapt JFlex lexers to the IntelliJ Platform Lexer API.
The source code of
[IntelliJ IDEA Community Edition](https://github.com/JetBrains/intellij-community)
includes a patched version of JFlex 1.4 located in *tools/lexer/jflex-1.4* and lexer skeleton file *tools/lexer/idea-flex.skeleton* which can be used for creating lexers compatible with
[FlexAdapter](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lexer/FlexAdapter.java).
[FlexAdapter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexAdapter.java).
The patched version of JFlex provides a new command line option `--charat` which changes the JFlex generated code so that it works with the IntelliJ Platform skeleton.
Enabling `--charat` option passes the source data for lexing as a
[CharSequence](https://docs.oracle.com/javase/8/docs/api/java/lang/CharSequence.html)
@ -73,28 +73,28 @@ definition for
Types of tokens for lexers are defined by instances of
[IElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/IElementType.java).
[IElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java).
A number of token types common for all languages are defined in the
[TokenType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/TokenType.java)
[TokenType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/TokenType.java)
interface.
Custom language plugins should reuse these token types wherever applicable.
For all other token types, the plugin needs to create new
[IElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
[IElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
instances and associate with the language in which the token type is used.
The same
[IElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
[IElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
instance should be returned every time a particular token type is encountered by the lexer.
**Example:**
[Token types](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/parsing/PropertiesTokenTypes.java)
[Token types](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/parsing/PropertiesTokenTypes.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/)
An important feature which can be implemented at lexer level is mixing languages within a file, for example, embedding fragments of Java code in some template language.
If a language supports embedding its fragments in another language, it needs to define the chameleon token types for different types of fragments which can be embedded, and these token types need to implement the
[ILazyParseableElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java)
[ILazyParseableElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java)
interface.
The lexer of the enclosing language needs to return the entire fragment of the embedded language as a single chameleon token, of the type defined by the embedded language.
To parse the contents of the chameleon token, the IDE will call the parser of the embedded language through a call to
[ILazyParseableElementType.parseContents()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java).
[ILazyParseableElementType.parseContents()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java).

56
reference_guide/custom_language_support/implementing_parser_and_psi.md
View File

@ -5,13 +5,13 @@ title: Implementing a Parser and PSI
Parsing files in IntelliJ Platform is a two-step process.
First, an abstract syntax tree (AST) is built, defining the structure of the program.
AST nodes are created internally by the IDE and are represented by instances of the
[ASTNode](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ASTNode.java)
[ASTNode](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ASTNode.java)
class.
Each AST node has an associated element type
[IElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
[IElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java)
instance, and the element types are defined by the language plugin.
The top-level node of the AST tree for a file needs to have a special element type, implementing the
[IFileElementType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/tree/IFileElementType.java)
[IFileElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IFileElementType.java)
interface.
The AST nodes have a direct mapping to text ranges in the underlying document.
@ -20,18 +20,18 @@ Operations performed on nodes of the AST tree, such as inserting, removing, reor
Second, a PSI, or Program Structure Interface, tree is built on top of the AST, adding semantics and methods for manipulating specific language constructs.
Nodes of the PSI tree are represented by classes implementing the
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
interface and are created by the language plugin in the
[ParserDefinition.createElement()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
[ParserDefinition.createElement()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
method.
The top-level node of the PSI tree for a file needs to implement the
[PsiFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFile.java)
[PsiFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFile.java)
interface, and is created in the
[ParserDefinition.createFile()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
[ParserDefinition.createFile()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
method.
**Example**:
[ParserDefinition](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParserDefinition.java)
[ParserDefinition](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParserDefinition.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/)
@ -40,13 +40,13 @@ The lifecycle of the PSI is described in more detail in
[Architectural Overview](/basics/architectural_overview.md).
The base classes for the PSI implementation, including
[PsiFileBase](https://github.com/JetBrains/intellij-community/blob/master/platform/core-impl/src/com/intellij/extapi/psi/PsiFileBase.java),
[PsiFileBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-impl/src/com/intellij/extapi/psi/PsiFileBase.java),
the base implementation of
[PsiFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFile.java),
[PsiFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFile.java),
and
[ASTWrapperPsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java),
[ASTWrapperPsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java),
the base implementation of
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java),
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java),
are provided by *IntelliJ Platform*.
There is currently no ready way to reuse existing language grammars, for example, from ANTLR, for creating custom language parsers.
@ -59,53 +59,53 @@ The Grammar-Kit plugin is built using its own engine and its source code can be
[GitHub](https://github.com/JetBrains/Grammar-Kit).
The language plugin provides the parser implementation as an implementation of the
[PsiParser](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiParser.java)
[PsiParser](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiParser.java)
interface, returned from
[ParserDefinition.createParser()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java).
[ParserDefinition.createParser()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java).
The parser receives an instance of the
[PsiBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
class, which is used to get the stream of tokens from the lexer and to hold the intermediate state of the AST being built.
The parser must process all tokens returned by the lexer up to the end of stream, in other words until
[PsiBuilder.getTokenType()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder.getTokenType()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
returns `null`, even if the tokens are not valid according to the language syntax.
**Example**:
[PsiParser](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParser.java)
[PsiParser](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParser.java)
implementation for
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/).
The parser works by setting pairs of markers (
[PsiBuilder.Marker](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder.Marker](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
instances) within the stream of tokens received from the lexer.
Each pair of markers defines the range of lexer tokens for a single node in the AST tree.
If a pair of markers is nested in another pair (starts after its start and ends before its end), it becomes the child node of the outer pair.
The element type for the marker pair and for the AST node created from it is specified when the end marker is set, which is done by making call to
[PsiBuilder.Marker.done()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java).
[PsiBuilder.Marker.done()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java).
Also, it is possible to drop a start marker before its end marker has been set.
The `drop()` method drops only a single start marker without affecting any markers added after it, and the `rollbackTo()` method drops the start marker and all markers added after it and reverts the lexer position to the start marker.
These methods can be used to implement lookahead when parsing.
The method
[PsiBuilder.Marker.precede()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder.Marker.precede()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
is useful for right-to-left parsing when you don't know how many markers you need at a certain position until you read more input.
For example, a binary expression `a+b+c` needs to be parsed as `( (a+b) + c )`.
Thus, two start markers are needed at the position of the token 'a', but that is not known until the token 'c' is read.
When the parser reaches the '+' token following 'b', it can call `precede()` to duplicate the start marker at 'a' position, and then put its matching end marker after 'c'.
An important feature of
[PsiBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
is its handling of whitespace and comments.
The types of tokens which are treated as whitespace or comments are defined by the methods `getWhitespaceTokens()` and `getCommentTokens()` in the
[ParserDefinition](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
[ParserDefinition](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
class.
[PsiBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
automatically omits whitespace and comment tokens from the stream of tokens it passes to
[PsiParser](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiParser.java),
[PsiParser](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiParser.java),
and adjusts the token ranges of AST nodes so that leading and trailing whitespace tokens are not included in the node.
The token set returned from
[ParserDefinition.getCommentTokens()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
[ParserDefinition.getCommentTokens()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java)
is also used to search for TODO items.
In order to better understand the process of building a PSI tree for a simple expression, you can refer to the following diagram:
@ -115,13 +115,13 @@ In order to better understand the process of building a PSI tree for a simple ex
In general, there is no single right way to implement a PSI for a custom language, and the plugin author can choose the PSI structure and set of methods which are the most convenient for the code which uses the PSI (error analysis, refactorings and so on).
However, there is one base interface which needs to be used by a custom language PSI implementation in order to support features like rename and find usages.
Every element which can be renamed or referenced (a class definition, a method definition and so on) needs to implement the
[PsiNamedElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
interface, with methods `getName()` and `setName()`.
A number of functions which can be used for implementing and using the PSI can be found in the `com.intellij.psi.util` package, and in particular in the
[PsiUtil](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-api/src/com/intellij/psi/util/PsiUtil.java)
[PsiUtil](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-api/src/com/intellij/psi/util/PsiUtil.java)
and
[PsiTreeUtil](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/util/PsiTreeUtil.java)
[PsiTreeUtil](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/util/PsiTreeUtil.java)
classes.
A very helpful tool for debugging the PSI implementation is the

38
reference_guide/custom_language_support/references_and_resolve.md
View File

@ -7,33 +7,33 @@ Resolving references means the ability to go from the usage of an element (acces
This is obviously needed in order to support `Go to Declaration` action invoked by **Ctrl-B** and **Ctrl-Click**, and it is also a prerequisite for the `Find Usages` action, the `Rename` refactoring and the code completion.
All PSI elements which work as references (for which the `Go to Declaration` action applies) need to implement the
[PsiElement.getReference()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement.getReference()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
method and to return a
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
implementation from that method.
The
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
interface can be implemented by the same class as
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java),
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java),
or by a different class. An element can also contain multiple references (for example, a string literal can contain multiple substrings which are valid full-qualified class names), in which case it can implement
[PsiElement.getReferences()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement.getReferences()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
and return the references as an array.
The main method of the
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
interface is `resolve()`, which returns the element to which the reference points, or `null` if it was not possible to resolve the reference to a valid element (for example, it points to an undefined class).
A counterpart to this method is `isReferenceTo()`, which checks if the reference resolves to the specified element.
The latter method can be implemented by calling `resolve()` and comparing the result with the passed PSI element, but additional optimizations (for example, performing the tree walk only if the text of the element is equal to the text of the reference) are possible.
**Example**:
[Reference](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java)
[Reference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java)
to a ResourceBundle in the
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties)
There's a set of interfaces which can be used as a base for implementing resolve support, namely the
[PsiScopeProcessor interface](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) and the
[PsiElement.processDeclarations()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiScopeProcessor interface](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) and the
[PsiElement.processDeclarations()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
method.
These interfaces have a number of extra complexities which are not necessary for most custom languages (like support for substituting Java generics types), but they are required if the custom language can have references to Java code.
If Java interoperability is not required, the plugin can forgo the standard interfaces and provide its own, different implementation of resolve.
@ -41,39 +41,39 @@ If Java interoperability is not required, the plugin can forgo the standard inte
The implementation of resolve based on the standard helper classes contains of the following components:
* A class implementing the
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
interface which gathers the possible declarations for the reference and stops the resolve process when it has successfully completed.
The main method which needs to be implemented is `execute()`, which is called to process every declaration encountered during the resolve, and returns `true` if the resolve needs to be continued or `false` if the declaration has been found.
The methods `getHint()` and `handleEvent()` are used for internal optimizations and can be left empty in the
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
implementations for custom languages.
* A function which walks the PSI tree up from the reference location until the resolve has successfully completed or until the end of the resolve scope has been reached.
If the target of the reference is located in a different file, the file can be located, for example, using
[FilenameIndex.getFilesByName()](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java)
[FilenameIndex.getFilesByName()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java)
(if the file name is known) or by iterating through all custom language files in the project (`iterateContent()` in the
[FileIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java)
[FileIndex](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java)
interface obtained from
[ProjectRootManager.getFileIndex()](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
[ProjectRootManager.getFileIndex()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
).
* The individual PSI elements, on which the `processDeclarations()` method is called during the PSI tree walk.
If a PSI element is a declaration, it passes itself to the `execute()` method of the
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
passed to it.
Also, if necessary according to the language scoping rules, a PSI element can pass the
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java)
to its child elements.
An extension of the
[PsiReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
interface, which allows a reference to resolve to multiple targets, is the
[PsiPolyVariantReference](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java)
[PsiPolyVariantReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java)
interface.
The targets to which the reference resolves are returned from the `multiResolve()` method.
The `Go to Declaration` action for such references allows the user to choose the target to navigate to.
The implementation of `multiResolve()` can be also based on
[PsiScopeProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java),
[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java),
and can collect all valid targets for the reference instead of stopping when the first valid target is found.
The `Quick Definition Lookup` action is based on the same mechanism as `Go to Declaration`, so it becomes automatically available for all references which can be resolved by the language plugin.

14
reference_guide/custom_language_support/registering_file_type.md
View File

@ -6,20 +6,20 @@ The first step in developing a custom language plugin is registering a file type
The IDE normally determines the type of a file by looking at its file name.
A custom language file type is a class derived from
[LanguageFileType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java),
[LanguageFileType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java),
which passes a
[Language](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Language.java)
[Language](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Language.java)
implementation class to its base class constructor.
To register a file type, the plugin developer provides an implementation of the
[FileTypeFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java)
[FileTypeFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java)
interface, which is registered via the `com.intellij.fileTypeFactory`
[platform extension point](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml).
[platform extension point](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml).
**Example**:
[LanguageFileType](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java)
[LanguageFileType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java)
implementation in
[Properties language plugin](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesFileType.java)
[Properties language plugin](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesFileType.java)
To verify that the file type is registered correctly, you can implement the
[LanguageFileType.getIcon()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java)
[LanguageFileType.getIcon()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java)
method and verify that the correct icon is displayed for files which have the extension(s) associated with your file type.

20
reference_guide/custom_language_support/rename_refactoring.md
View File

@ -7,9 +7,9 @@ The operation of the Rename refactoring is quite similar to that of Find Usages.
It uses the same rules for locating the element to be renamed, and the same index of words for locating the files which may have references to the element being renamed.
When the rename refactoring is performed, the method
[PsiNamedElement.setName()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
[PsiNamedElement.setName()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java)
is called for the renamed element, and
[PsiReference.handleElementRename()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiReference.java)
[PsiReference.handleElementRename()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java)
is called for all references to the renamed element.
Both of these methods perform basically the same action: replace the underlying AST node of the PSI element with the node containing the new text entered by the user.
Creating a fully correct AST node from scratch is quite difficult.
@ -22,33 +22,33 @@ implementation for a
Another interface related to the Rename refactoring is
[NamesValidator](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java).
[NamesValidator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java).
This interface allows a plugin to check if the name entered by the user in the `Rename` dialog is a valid identifier (and not a keyword) according to the custom language rules.
If an implementation of this interface is not provided by the plugin, Java rules for validating identifiers are used.
Implementations of
[NamesValidator](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java)
[NamesValidator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java)
are registered in the `com.intellij.lang.namesValidator` extension point.
**Example**:
[NamesValidator](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/PropertiesNamesValidator.java)
[NamesValidator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesNamesValidator.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties)
Further customization of the Rename refactoring processing is possible on multiple levels.
Providing a custom implementation of the
[RenameHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/refactoring/rename/RenameHandler.java)
[RenameHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/refactoring/rename/RenameHandler.java)
interface allows you to entirely replace the UI and workflow of the rename refactoring, and also to support renaming something which is not a
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
at all.
**Example**:
[RenameHandler](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/ResourceBundleFromEditorRenameHandler.java)
[RenameHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/ResourceBundleFromEditorRenameHandler.java)
for renaming a resource bundle
If you're fine with the standard UI but need to extend the default logic of renaming, you can provide an implementation of the
[RenamePsiElementProcessor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-impl/src/com/intellij/refactoring/rename/RenamePsiElementProcessor.java)
[RenamePsiElementProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/refactoring/rename/RenamePsiElementProcessor.java)
interface.
This allows you to:
@ -63,6 +63,6 @@ This allows you to:
* etc.
**Example**:
[RenamePsiElementProcessor](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/RenamePropertyProcessor.java)
[RenamePsiElementProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/RenamePropertyProcessor.java)
for renaming a property in
[Properties plugin language](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties)

6
reference_guide/custom_language_support/safe_delete_refactoring.md
View File

@ -7,13 +7,13 @@ The `Safe Delete` refactoring also builds on the same `Find Usages` framework as
In addition to that, in order to support `Safe Delete`, a plugin needs to implement two things:
* The
[RefactoringSupportProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/refactoring/RefactoringSupportProvider.java)
[RefactoringSupportProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/RefactoringSupportProvider.java)
interface, registered in the `com.intellij.lang.refactoringSupport` extension point, and the `isSafeDeleteAvailable()` method, which checks if the `Safe Delete` refactoring is available for a specific PSI element
* The
[PsiElement.delete()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java#L371)
method for the
[PsiElement](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiElement.java)
[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java)
subclasses for which `Safe Delete` is available.
Deleting PSI elements is implemented by deleting the underlying AST nodes from the AST tree (which, in turn, causes the text ranges corresponding to the AST nodes to be deleted from the document).
@ -29,5 +29,5 @@ This is done by implementing the `SafeDeleteProcessorDelegate` interface.
**Example**:
[SafeDeleteProcessorDelegate](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java)
[SafeDeleteProcessorDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java)
implementation for a .properties file

20
reference_guide/custom_language_support/structure_view.md
View File

@ -4,39 +4,39 @@ title: Structure View
The Structure View implementation used for a specific file type can be customized on many levels.
If a custom language plugin provides an implementation of the
[StructureView](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java)
[StructureView](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java)
interface, it can completely replace the standard structure view implementation with a custom user interface component.
However, for most languages this is not necessary, and the standard
[StructureView](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java)
[StructureView](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java)
implementation provided by *IntelliJ Platform* can be reused.
The starting point for the structure view is the
[PsiStructureViewFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/lang/PsiStructureViewFactory.java)
[PsiStructureViewFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/lang/PsiStructureViewFactory.java)
interface, which is registered in the `com.intellij.lang.psiStructureViewFactory` extension point.
**Example:**
[PsiStructureViewFactory](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/lang/properties/structureView/PropertiesStructureViewBuilderFactory.java)
[PsiStructureViewFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/structureView/PropertiesStructureViewBuilderFactory.java)
for .properties files
To reuse the *IntelliJ Platform* implementation of the
[StructureView](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java),
[StructureView](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java),
the plugin returns a
[TreeBasedStructureViewBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java)
[TreeBasedStructureViewBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java)
from its
[PsiStructureViewFactory.getStructureViewBuilder()](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/lang/PsiStructureViewFactory.java#L35)
method.
As the model for the builder, the plugin can specify a subclass of
[TextEditorBasedStructureViewModel](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/TextEditorBasedStructureViewModel.java),
[TextEditorBasedStructureViewModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TextEditorBasedStructureViewModel.java),
and by overriding methods of this subclass it customizes the structure view for a specific language.
**Example**:
[StructureViewModel](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesFileStructureViewModel.java)
[StructureViewModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesFileStructureViewModel.java)
for .properties files
The main method to override is `getRoot()`, which returns the instance of a class implementing the
[StructureViewTreeElement](https://github.com/JetBrains/intellij-community/blob/master/platform/structure-view-api/src/com/intellij/ide/structureView/StructureViewTreeElement.java)
[StructureViewTreeElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureViewTreeElement.java)
interface.
There exists no standard implementation of this interface, so a plugin will need to implement it completely.
@ -50,6 +50,6 @@ The implementation of `StructureViewTreeElement.getChildren()` needs to be match
The latter method returns an array of `PsiElement`\-derived classes which can be shown as structure view elements, and is used to select the Structure View item matching the cursor position when the structure view is first opened or when the `Autoscroll from source` option is used.
**Example:**
[StructureViewElement](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesStructureViewElement.java)
[StructureViewElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesStructureViewElement.java)
for a
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)

4
reference_guide/custom_language_support/surround_with.md
View File

@ -3,11 +3,11 @@ title: Surround With
---
In order to support the `Code | Surround With...` action, the plugin needs to register one or more implementations of the
[SurroundDescriptor](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/surroundWith/SurroundDescriptor.java)
[SurroundDescriptor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/surroundWith/SurroundDescriptor.java)
interface in the `com.intellij.lang.surroundDescriptor` extension point.
Each of the surround descriptors defines a possible type of code fragment which can be surrounded - for example, one surround descriptor can handle surrounding expressions, and another can handle statements.
Each surround descriptor, in turn, contains an array of
[Surrounder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/lang/surroundWith/Surrounder.java)
[Surrounder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/surroundWith/Surrounder.java)
objects, defining specific templates which can be used for surrounding the selected code fragment (for example, `Surround With if`, `Surround With for` and so on).
When the `Surround With...` action is invoked, the IDE queries all surround descriptors for the language until it finds one that returns a non-empty array from its `getElementsToSurround()` method.

44
reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md
View File

@ -3,18 +3,18 @@ title: Syntax Highlighting and Error Highlighting
---
The class used to specify how a particular range of text should be highlighted is called
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java).
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java).
An instance of this class is created for every distinct type of item which should be highlighted (keyword, number, string and so on).
The
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
defines the default attributes which are applied to items of the corresponding type (for example, keywords are bold, numbers are blue, strings are bold and green).
The mapping of the
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
to specific attributes used in an editor is defined by the
[EditorColorsScheme](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/colors/EditorColorsScheme.java)
[EditorColorsScheme](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/colors/EditorColorsScheme.java)
class, and can be configured by the user if the plugin provides an appropriate configuration interface.
Highlighting from multiple
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
items can be layered - for example, one key may define an item's boldness and another its color.
**Note:**
@ -26,19 +26,19 @@ New functionality about Language Defaults and support for additional color schem
The syntax and error highlighting is performed on multiple levels.
The first level of syntax highlighting is based on the lexer output, and is provided through the
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java)
[SyntaxHighlighter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java)
interface.
The syntax highlighter returns the
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
instances for each token type which needs special highlighting.
For highlighting lexer errors, the standard
[TextAttributesKey](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java)
for bad characters
[HighlighterColors.BAD_CHARACTER](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java)
[HighlighterColors.BAD_CHARACTER](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java)
can be used.
**Example:**
[SyntaxHighlighter](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java)
[SyntaxHighlighter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java)
implementation for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)
@ -47,13 +47,13 @@ implementation for
The second level of error highlighting happens during parsing.
If a particular sequence of tokens is invalid according to the grammar of the language, the
[PsiBuilder.error()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
[PsiBuilder.error()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java)
method can be used to highlight the invalid tokens and display an error message showing why they are not valid.
### Annotator
The third level of highlighting is performed through the
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java)
interface.
A plugin can register one or more annotators in the `com.intellij.annotator` extension point, and these annotators are called during the background highlighting pass to process the elements in the PSI tree of the custom language.
Annotators can analyze not only the syntax, but also the semantics using PSI, and thus can provide much more complex syntax and error highlighting logic.
@ -62,18 +62,18 @@ The annotator can also provide quick fixes to problems it detects.
When the file is changed, the annotator is called incrementally to process only changed elements in the PSI tree.
To highlight a region of text as a warning or error, the annotator calls `createErrorAnnotation()` or `createWarningAnnotation()` on the
[AnnotationHolder](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
[AnnotationHolder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
object passed to it, and optionally calls `registerFix()` on the returned
[Annotation](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
[Annotation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
object to add a quick fix for the error or warning.
To apply additional syntax highlighting, the annotator can call
[AnnotationHolder.createInfoAnnotation()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
[AnnotationHolder.createInfoAnnotation()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
with an empty message and then call
[Annotation.setTextAttributes()](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
[Annotation.setTextAttributes()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java)
to specify the text attributes key for the highlighting.
**Example:**
[Annotator](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java)
[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)
@ -81,24 +81,24 @@ for
### External tool
Finally, if the custom language employs external tools for validating files in the language (for example, uses the Xerces library for XML schema validation), it can provide an implementation of the
[ExternalAnnotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
[ExternalAnnotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
interface and register it in `com.intellij.externalAnnotator` extension point.
The
[ExternalAnnotator](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
[ExternalAnnotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java)
highlighting has the lowest priority and is invoked only after all other background processing has completed.
It uses the same
[AnnotationHolder](https://github.com/JetBrains/intellij-community/blob/master/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
[AnnotationHolder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java)
interface for converting the output of the external tool into editor highlighting.
### Color settings
The plugin can also provide a configuration interface to allow the user to configure the colors used for highlighting specific items.
In order to do that, it should provide an implementation of
[ColorSettingPage](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java)
[ColorSettingPage](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java)
and register it in the `com.intellij.colorSettingsPage` extension point.
**Example**:
[ColorSettingsPage](https://github.com/JetBrains/intellij-community/blob/master/plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java)
[ColorSettingsPage](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java)
for
[Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/)

10
reference_guide/messaging_infrastructure.md
View File

@ -49,7 +49,7 @@ Connection will use that *default handler* when storing *(topic-handler)* mappin
* it's possible to explicitly release acquired resources (*disconnect()* method).
Also it can be plugged to standard semi-automatic disposing
(
[Disposable](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/Disposable.java)
[Disposable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/Disposable.java)
);
## Putting altogether
@ -107,12 +107,12 @@ public void doChange(Context context) {
* *MessageBus* instances are available via
[ComponentManager.getMessageBus()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ComponentManager.java#L85)
(many standard interfaces implement it, e.g.
[Application](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/application/Application.java),
[Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java);
[Application](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java),
[Project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java);
* number of public topics are used by *IntelliJ IDEA*, e.g.
[AppTopics](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/AppTopics.java),
[ProjectTopics](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/ProjectTopics.java)
[AppTopics](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/AppTopics.java),
[ProjectTopics](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/ProjectTopics.java)
etc.
So, it's possible to subscribe to them in order to receive information about the processing;

24
reference_guide/multiple_carets.md
View File

@ -15,9 +15,9 @@ Currently, the most recent caret is considered the primary one.
## Core functionality
Core logic related to multi-caret implementation such as accessing currently existing carets adding and removing carets is available via
[CaretModel](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java)
[CaretModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java)
interface, some changes also have been made in
[SelectionModel](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java)
[SelectionModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java)
interface.
Check Javadoc of those interfaces for details.
@ -35,7 +35,7 @@ _getBlockSelectionStarts()_ and _getBlockSelectionEnds()_ methods work in multi-
### EditorAction and EditorActionHandler
When
[EditorActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) is invoked, additional parameter will be passed to it - caret instance on which it should operate, or null, if it's invoked without any caret context.
[EditorActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) is invoked, additional parameter will be passed to it - caret instance on which it should operate, or null, if it's invoked without any caret context.
If the handler invokes another handler (delegate handler for the same actionId, or a completely unrelated handler), that parameter should normally be passed to the delegate unchanged (unless no context caret has been provided to the handler, but it needs to invoke another handler on a specific caret).
Of course, handler can just ignore the caret parameter if its functionality is not related to caret/selection position.
@ -60,26 +60,26 @@ At the moment there's no need to make any changes in the handlers to support mul
### TypedActionHandler, TypedHandlerDelegate
[TypedActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
[TypedActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
and
[TypedHandlerDelegate](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java)
[TypedHandlerDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java)
implementations are invoked only once for each typed character.
If those handlers need to support multiple carets, they will need to implement that explicitly.
[EditorModificationUtil](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/EditorModificationUtil.java).
[EditorModificationUtil](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/EditorModificationUtil.java).
_typeInStringAtCaretHonorMultipleCarets_ utility method is available to do the most common task in this case - inserting the same text into all caret positions and/or moving all carets relatively to their current position.
Examples of its usage:
* [TypedAction](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java).
* [TypedAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java).
* [XmlGtTypedHandler](https://github.com/JetBrains/intellij-community/blob/master/xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java).
* [XmlGtTypedHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java).
-----------
**Note**:
Starting from IDEA 14,
[TypedHandlerDelegate](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java)
[TypedHandlerDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java)
implementations are invoked automatically for each caret. If one wants to implement custom multicaret behaviour on typing,
[TypedActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
[TypedActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
needs to be provided instead.
-----------
@ -87,9 +87,9 @@ needs to be provided instead.
## Code insight actions
Existing actions inheriting from
[CodeInsightAction](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/codeInsight/actions/CodeInsightAction.java) will work for primary caret only.
[CodeInsightAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/actions/CodeInsightAction.java) will work for primary caret only.
To support in multiple carets one should inherit
[MultiCaretCodeInsightAction](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-impl/src/com/intellij/codeInsight/actions/MultiCaretCodeInsightAction.java)
[MultiCaretCodeInsightAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/codeInsight/actions/MultiCaretCodeInsightAction.java)
instead (each caret might have a different editor and PSI instance, so using old API is not possible).
It is available since IDEA 14.

6
reference_guide/project_model/module.md
View File

@ -17,11 +17,11 @@ Module module = ProjectRootManager.getInstance(project).getFileIndex().getModule
## Accessing Module Roots
Information about model roots can be accessed via the class
[ModuleRootManager.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java),
[ModuleRootManager.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java),
for example, an instance of
[ModuleFileIndex.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java)
[ModuleFileIndex.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java)
can be obtained, which is analogical to the
[ProjectFileIndex.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
[ProjectFileIndex.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
but in the scope of a module
```java

14
reference_guide/project_model/project.md
View File

@ -24,11 +24,11 @@ As for the file-based format projects, .IML files describe modules.
Main classes providing work with the project model are located in the package
[projectModel-api.openapi](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi).
Basic API classes and interfaces for the concepts of
[project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java),
[module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java),
[application](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/application/Application.java),
[project](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/project/Project.java),
[module](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java),
[application](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/application/Application.java),
and
[component](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
[component](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java)
are placed in the
[core-api.openapi](https://github.com/JetBrains/intellij-community/tree/master/platform/core-api/src/com/intellij/openapi)
package.
@ -49,7 +49,7 @@ VirtualFile[] vFiles = ProjectRootManager.getInstance(project).getContentSourceR
### Checking if File Belongs to a Project
Use
[ProjectFileIndex.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
[ProjectFileIndex.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java)
to get this information.
### Getting an Instance of the ProjectFileIndex Interface
@ -74,9 +74,9 @@ Utility classes which can be used for modifying a project structure can be found
It's
[roots](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-impl/src/com/intellij/openapi/roots/)
subpackage contains instances and utilities meant to work with project and module source roots, including
[ModuleRootModificationUtil.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java)
[ModuleRootModificationUtil.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java)
and
[ProjectRootUtil.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java)
[ProjectRootUtil.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java)
Refer to the
[basic example](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/project_model/src/com/intellij/tutorials/project/model/ModificationAction.java)

2
reference_guide/project_model/sdk.md
View File

@ -15,7 +15,7 @@ in IntelliJ IDEA Web Help.
### Getting Project Sdk Information
Main information about the project Sdk can be accessed via
[ProjectRootManager.java](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
[ProjectRootManager.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java)
like the following example shows
```java

18
reference_guide/project_wizard.md
View File

@ -11,7 +11,7 @@ Working with the project wizard can be illustrated with the
Additional support for specific tools and technologies is usually done via implementing some certain module type which is attached to the project.
New module type should be derived from the class
[ModuleType](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java).
[ModuleType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java).
## Project Wizard
@ -36,9 +36,9 @@ To create a new module type and an extension
to the
[plugin.xml](https://github.com/bulenkov/RedlineSmalltalk/blob/master/resources/META-INF/plugin.xml).
A custom module type should extend the
[ModuleType](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java)
[ModuleType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java)
generic from
[ModuleBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java).
[ModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java).
The following
[module type implementation](https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleType.java)
of a custom module type show how this instance can be registered and implemented.
@ -46,7 +46,7 @@ of a custom module type show how this instance can be registered and implemented
### Implementing Module Builder
To set up a new module environment
[ModuleBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java)
[ModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java)
class should be extended and registered as an extension point like the following snippet shows:
```xml
@ -71,17 +71,17 @@ Functionality which is mandatory to implement consists of:
```
See
[JavaModuleBuilder](https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
[JavaModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
to understand better how to implement a module builder.
If your module type is based on the java module and meant to support Java as well, extending
[JavaModuleBuilder](https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
[JavaModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
is enough.
No extension point needs no be registered.
Refer to
[SmallTalk module type](https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleType.java)
to see how
[JavaModuleBuilder](https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
[JavaModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)
can be derived.
### Implementing Module Builder Listener
@ -89,7 +89,7 @@ can be derived.
Module builder listener reacts on a new module creation, which could be done either as a part of the project creation process,
or as adding a new module to the already existing project.
To provide a certain behavior right after a module has been created, module builder should implement
[ModuleBuilderListener](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java)
[ModuleBuilderListener](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java)
Method
```java
@ -117,7 +117,7 @@ for the SmallTalk project type illustrates how a custom wizard step can be creat
The
[RsModuleWizardStep](https://github.com/bulenkov/RedlineSmalltalk/blob/master/src/st/redline/smalltalk/module/RsModuleWizardStep.java)
class is derived from
[ModuleWizardStep](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java),
[ModuleWizardStep](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java),
which has two methods to be overridden:
* ```java

64
reference_guide/vcs_integration_for_plugins.md
View File

@ -12,48 +12,48 @@ The VCS API was significantly refactored in version 6.0, and this document does
### FilePath
A [FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
A [FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
represents a path to a file or directory on disk or in the VCS repository.
Unlike a
[VirtualFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java),
[VirtualFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java),
a
[FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
can represent a path to a file which doesn't exist on disk.
The main difference between a
[FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
and a
[java.io.File](http://docs.oracle.com/javase/8/docs/api/java/io/File.html)
is that a
[FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
caches the
[VirtualFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java)
[VirtualFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java)
corresponding to the path, so it can be retrieved without doing a VFS search.
To create instances of
[FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java),
[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java),
the
[VcsContextFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/actions/VcsContextFactory.java)
[VcsContextFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/actions/VcsContextFactory.java)
API is used.
It can be accessed as`PeerFactory.getInstance().getVcsContextFactory()`
[FilePath](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java)
representing paths in a VCS repository, rather than local paths, are created using
`VcsContextFactory.createFilePathOnNonLocal()`. `FilePath.isNonLocal()` returns true for such files.
### Revision Number
A
[VcsRevisionNumber](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java)
[VcsRevisionNumber](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java)
represents a revision number of the file.
If the VCS stores revision numbers as simple integers, the standard
[VcsRevisionNumber](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java).
[VcsRevisionNumber](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java).
Int implementation can be used.
If the VCS has a more complex format of revision numbers (like CVS, which uses a series of numbers delimited with dots), the plugin can provide a custom implementation.
### ContentRevision
A
[ContentRevision](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/ContentRevision.java)
[ContentRevision](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/ContentRevision.java)
represents a particular revision of a file, which exists either locally or in a VCS repository.
It has three main attributes:
@ -69,24 +69,24 @@ Revisions of binary files can also be represented as BinaryContentRevision, whic
For binary revisions, the result of getContent() is undefined, and getBinaryContent() can be used to retrieve the contents as a byte array.
A useful class which can be used to represent the current on-disk version of a particular file is
[CurrentContentRevision](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/CurrentContentRevision.java).
[CurrentContentRevision](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/CurrentContentRevision.java).
### FileStatus
A
[FileStatus](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/vcs/FileStatus.java)
[FileStatus](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/vcs/FileStatus.java)
represents a status of a file in regard to VCS (unversioned, not changed, added, modified and so on).
It determines the color used to render the name of the file in the UI.
### Change
A
[Change](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
[Change](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
represents a single file operation (creation, modification, move/rename or deletion) from a VCS point of view.
A Change can represent either a modification which the user has performed locally and not yet committed, a committed modification, or some other type of modification (for example, a shelved change or a difference between two arbitrary revisions).
A
[Change](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
[Change](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
essentially consists of two content revisions:
* before revision (`null` if the *Change* represents file creation)
@ -95,26 +95,26 @@ essentially consists of two content revisions:
A move or rename is represented by a Change where the before revision and the after revision have different file paths.
A custom file status can be specified for a
[Change](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
[Change](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java)
if it represents a non-standard modification of the file (for example, a file which has been merged with conflicts).
If a custom file status has not been specified, the status is calculated automatically from the change type.
### ChangeList
A
[ChangeList](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeList.java)
[ChangeList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeList.java)
represents a named group of related changes.
There are two main kinds of changelists:
* [LocalChangeList](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/LocalChangeList.java) represents a group of modifications done by a user locally.
* [LocalChangeList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/LocalChangeList.java) represents a group of modifications done by a user locally.
If the VCS also supports the concept of changelists (like Perforce does), the VCS plugin can synchronize IDEA's local changelist structure with that of the VCS.
Otherwise, a local changelist is simply a subset of the files checked out or modified by the user.
* [CommittedChangeList](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java)
* [CommittedChangeList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java)
represents a set of modifications checked in to the VCS repository.
For VCSes which support atomic commit, every committed revision is represented by a CommittedChangeList.
For VCSes which use per-file commit (like CVS), the plugin can use heuristics to group a sequence of individual file commits into a
[CommittedChangeList](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java)
[CommittedChangeList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java)
**Note**:
@ -147,36 +147,36 @@ Here `name` is the unique name of the VCS (this must match the string returned b
This component is responsible for keeping track of the local changes done by the user in his working copy, and reporting these changes to the IntelliJ IDEA core.
An implementation of this class is returned from
[AbstractVcs.getChangeProvider()](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/AbstractVcs.java).
[AbstractVcs.getChangeProvider()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/AbstractVcs.java).
The ChangeProvider works in tandem with
[VcsDirtyScopeManager](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java),
[VcsDirtyScopeManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java),
which is a component in IntelliJ IDEA core.
[VcsDirtyScopeManager](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java)
[VcsDirtyScopeManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java)
keeps track of the 'dirty scope' - the set of files for which the VCS file status may be out of date.
Files are added to the dirty scope either when they are modified on disk, or when their VCS status is invalidated by an explicit call to
[VcsDirtyScopeManager.fileDirty()](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java)
[VcsDirtyScopeManager.fileDirty()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java)
or
[VcsDirtyScopeManager.dirDirtyRecursively()](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java).
[VcsDirtyScopeManager.dirDirtyRecursively()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java).
After some files have been added to the dirty scope, the dirty scope is passed to
[ChangeProvider.getChanges()](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java),
[ChangeProvider.getChanges()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java),
along with a
[ChangelistBuilder](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangelistBuilder.java)
[ChangelistBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangelistBuilder.java)
instance, which serves as a sink to which the
[ChangeProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
[ChangeProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
feeds the data about the changed files.
This processing happens asynchronously in a background thread.
The
[ChangeProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
[ChangeProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
can either iterate all files under the dirty scope using
[VcsDirtyScope.iterate()](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScope.java),
[VcsDirtyScope.iterate()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScope.java),
or retrieve information about its contents using the `getDirtyFiles()` and `getDirtyDirectoriesRecursively()` methods.
If it is possible to retrieve the information about the local changes from the VCS in batch, it's strongly preferable to use the second method, as it scales much better for large working copies.
The
[ChangeProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
[ChangeProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java)
reports data to ChangelistBuilder using the following methods:
* `processChange()` is called for files which have been checked out (or modified if the VCS doesn't use an explicit checkout model), scheduled for addition or deletion, moved or renamed.

22
tutorials/action_system/grouping_action.md
View File

@ -36,7 +36,7 @@ The following sample shows how to place a custom action group on top of the edit
#### 2.1.3. Adding actions to the group
To create an action we need to extend
[AnAction.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class:
```java
@ -78,14 +78,14 @@ In our case the condition is: an instance of the editor is available.
#### 2.2.1. Extending DefaultActionGroup
[DefaultActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
[DefaultActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
is a default implementations of
[ActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java)
[ActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java)
and used to add children actions and separators between them to a group.
This class is used if a set of actions belonging to the group is fixed, which is the majority of all the cases.
Firstly,
[DefaultActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
[DefaultActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
should be derived:
```java
@ -99,7 +99,7 @@ public class CustomDefaultActionGroup extends DefaultActionGroup {
#### 2.2.2. Registering action group
As in case with the simple action group, the inheritor of
[DefaultActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
[DefaultActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
should be declared in
[plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/register_actions/META-INF/plugin.xml)
file:
@ -115,7 +115,7 @@ file:
#### 2.2.3. Creating an action
[AnAction.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
needs to be extended:
```java
@ -169,13 +169,13 @@ After compiling and running the code sample above, *Tools* menu item should cont
If a set of actions belonging to a custom actions group may vary dependently on the context,
we need to work with
[ActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java).
[ActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java).
In this case set of actions to be grouped can be dynamically defined.
#### 2.3.1. Creating variable action group
To create a group of actions with a variable actions set we extend
[ActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java)
[ActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java)
first:
```java
public class BaseActionGroup extends ActionGroup {
@ -199,7 +199,7 @@ To register the group `<group>` attribute needs to be placed in the *`<actions>`
[plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/register_actions/META-INF/plugin.xml).
If `<group>` attribute contains any static action definition an exception will be thrown.
For statically defined group of action use
[DefaultActionGroup.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
[DefaultActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
#### 2.3.3. Accessing children actions
@ -218,7 +218,7 @@ public class BaseActionGroup extends ActionGroup {
#### 2.3.4. Adding children actions to the group
To make the group contain actions a non-empty array of
[AnAction.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
elements should be returned:
```java
@ -240,7 +240,7 @@ public class BaseActionGroup extends ActionGroup {
```
After providing an implementation of
[AnAction.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
and making it return a non-empty array of action Tools Menu should contain an extra group of action:
![Dynamic Action Group](img/dynamic_action_group.png)

8
tutorials/action_system/working_with_custom_actions.md
View File

@ -4,7 +4,7 @@ title: 1. Working With Custom Actions
An action is technically a class, derived from the
[AnAction](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class.
To update the state of the action, the method AnAction.update() is periodically called by IDEA.
The object of type
@ -16,7 +16,7 @@ and in particular, the specific presentation which needs to be updated.
### 1.1. Creating actions
To create a new we need to extend
[AnAction](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class:
```java
@ -27,7 +27,7 @@ public class SimpleAction extends AnAction {
### 1.2. Overriding actionPerformed()
The only method of an inheritor of
[AnAction](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
which needs to be overridden is `public void actionPerformed(AnActionEvent anActionEvent);`, and it should contain a part of code to be executed after the action has been invoked.
In this case the action does nothing.
@ -178,7 +178,7 @@ Parameter anActionEvent carries information on the invocation place and data ava
This means that this method is supposed to work really fast, no real work should be done at this phase.
For example, checking selection in a tree or a list, is considered valid, but working with a file system is not.
If you cannot understand the state of the action fast you should do it in the
[AnActionEvent](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java)
[AnActionEvent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java)
method and notify the user that action cannot be executed if it's the case.

10
tutorials/editor_basics.md
View File

@ -21,12 +21,12 @@ section.
**See also:**
[editor-ui-api package](https://github.com/JetBrains/intellij-community/tree/master/platform/editor-ui-api),
[Editor.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java),
[EditorImpl.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/openapi/editor/impl/EditorImpl.java).
[CommonDataKeys.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/CommonDataKeys.java),
[DataKey.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataKey.java),
[Editor.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java),
[EditorImpl.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/openapi/editor/impl/EditorImpl.java).
[CommonDataKeys.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/CommonDataKeys.java),
[DataKey.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataKey.java),
[AnActionEvent](https://github.com/JetBrains/intellij-community/blob/ff16ce78a1e0ddb6e67fd1dbc6e6a597e20d483a/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java),
[DataContext](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
[DataContext](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
**Related topics:**
[Action System](/tutorials/action_system/action_system.md)

8
tutorials/editor_basics/coordinates_system.md
View File

@ -5,7 +5,7 @@ title: 2. Editor coordinates system. Positions and offsets
Every caret in the editor has a set of properties describing it's coordinates.
These properties can be accessed by obtaining a
[caret model instance](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java).
[caret model instance](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java).
Working with caret positions and it's logical and visual properties will be explained in the sample below.
## 2.1. Pre-requirements
@ -31,7 +31,7 @@ public class EditorAreaIllustration extends AnAction {
## 2.3. Logical position
[LogicalPosition.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java)
[LogicalPosition.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java)
represents a line and a column of the current logical position of the caret. Logical positions ignore folding -
for example, if the top 10 lines of the document are folded, the 10th line in the document will have the line number 10 in its logical position.
@ -51,14 +51,14 @@ public class EditorAreaIllustration extends AnAction {
```
Logical position may store additional parameters that define its mapping to
[VisualPosition.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java).
[VisualPosition.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java).
Rationale is that single logical pair matches soft wrap-introduced virtual space, i.e. different visual positions
correspond to the same logical position. It's convenient to store exact visual location details within the logical
position in order to relief further 'logical position' -> 'visual position' mapping.
## 2.4. Visual position
[VisualPosition.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java)
[VisualPosition.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java)
represent a visual position and may very from the corresponding logical position.
Visual positions take folding into account - for example,
if the top 10 lines of the document are folded, the 10th line in the document will have the line number 1 in its visual position.

12
tutorials/editor_basics/editor_events.md
View File

@ -11,14 +11,14 @@ IntelliJ IDEA SDK provides a set of embedded mechanisms for handling events rela
## 3.1. Handling keystrokes in the Editor
To handle keystrokes and provide custom reactions interface
[TypedActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
[TypedActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java)
may be used.
Series of steps below shows how to change standard behaviour of the editor and make it react on typing differently instead of simply displaying a typed character in the editor area.
### 3.1.2 Implementing *TypedActionHandler*
First we need to implement an instance of
[TypedActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java):
[TypedActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java):
```java
public class MyTypedHandler implements TypedActionHandler {
@ -56,7 +56,7 @@ public class MyTypedHandler implements TypedActionHandler {
To enable a custom implementation of *TypedActionHandler* in the plugin we need to create a new instance of it and pass to
`public TypedActionHandler setupHandler(TypedActionHandler handler);` method of the
[TypedAction](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java)
[TypedAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java)
class. By doing it we replace the typing handler with the specified handler.
```java
@ -74,7 +74,7 @@ After compiling and running the code snippet above typing in the editor will be
## 3.2. Working with EditorActionHandler
Class
[EditorActionHandler.java](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java)
[EditorActionHandler.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java)
stays for actions activated by keystrokes in the editor.
Series of steps below show how access *EditorActionManager* and pass it actions to be executed.
In this example we will use *EditorActionHandler* to insert one extra caret above the current caret if available.
@ -129,9 +129,9 @@ public class EditorHandlerIllustration extends AnAction {
To manipulate with standard Editor's actions first we need to obtain
an instance of
[EditorActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java)
[EditorActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java)
for the action we'd like to work with. Ih this case it will be an instance of
[CloneCaretActionHandler](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/openapi/editor/actions/CloneCaretActionHandler.java).
[CloneCaretActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/openapi/editor/actions/CloneCaretActionHandler.java).
```java
public class EditorHandlerIllustration extends AnAction {

22
tutorials/editor_basics/working_with_text.md
View File

@ -11,7 +11,7 @@ The following set of steps will show how to access a text selection and change i
In this example access to the Editor is made through an action as a plug-in point.
To create an action we need derive
[AnAction.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
[AnAction.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
class.
@ -83,10 +83,10 @@ public class EditorIllustration extends AnAction {
To access an Editor instance also can be used other ways:
* If [DataContext](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
* If [DataContext](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
object is available `final Editor editor = CommonDataKeys.EDITOR.getData(context);`
* If [ActionEvent](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java)
* If [ActionEvent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java)
object is available `final Editor editor = actionEvent.getData(CommonDataKeys.EDITOR);`
@ -94,7 +94,7 @@ To access an Editor instance also can be used other ways:
## 1.3. Obtaining a caret model and selection
After making sure we have a project open and an instance of the Editor we need to check if any selection is available and set action's visibility accordingly to these conditions.
[SelectionModel](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java)
[SelectionModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java)
got from the Editor allows to do it by calling it's `hasSelection()` method.
Here's how our `update(final AnActionEvent e)` method should look like at the end:
@ -121,12 +121,12 @@ subpackage of the
[editor-ui-api](https://github.com/JetBrains/intellij-community/tree/master/platform/editor-ui-api)
package and include:
* [CaretModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java),
* [FoldingModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/FoldingModel.java),
* [IndentsModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/IndentsModel.java),
* [ScrollingModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java),
* [ScrollingModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java),
* [SoftWrapModel.java](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/editor/SoftWrapModel.java)
* [CaretModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java),
* [FoldingModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/FoldingModel.java),
* [IndentsModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/IndentsModel.java),
* [ScrollingModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java),
* [ScrollingModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java),
* [SoftWrapModel.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/SoftWrapModel.java)
## 1.4. Obtaining a Document
@ -149,7 +149,7 @@ public class EditorIllustration extends AnAction {
```
To modify the text an instance of the
[Document](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/editor/Document.java)
[Document](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/Document.java)
needs to be accessed. Document represents the contents of a text file loaded into memory, and possibly opened in an IDEA text editor.
The instance of a Document will be use later when a text replacement is performed.
We also need to figure out where the selected part of the text is located.

2
tutorials/framework.md
View File

@ -7,7 +7,7 @@ The following tutorial meant to show how to support a custom framework type for
## 1. Creating a new framework
In oder to make a custom framework available and configurable for a project
[FrameworkTypeEx](https://github.com/JetBrains/intellij-community/blob/master/java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java)
[FrameworkTypeEx](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java)
class needs to be extended:

8
tutorials/run_configurations.md
View File

@ -31,7 +31,7 @@ Add new *configurationType* extension to the
## 2. Implement ConfigurationType
Implement
[ConfigurationType](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
[ConfigurationType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java)
interface registered in the Step 1.
```java
@ -67,7 +67,7 @@ public class DemoRunConfigurationType implements ConfigurationType {
## 3. Implement a Configuration Factory
Implement a new
[ConfigurationFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java)
[ConfigurationFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java)
through which custom run configurations will be created.
```java
@ -96,10 +96,10 @@ public class DemoConfigurationFactory extends ConfigurationFactory {
To make your changes visible from the UI, implement a new Run Configuration.
**Note:** In most of the cases you can derive a custom Run Configuration class from the
[RunConfigurationBase](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RunConfigurationBase.java).
[RunConfigurationBase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfigurationBase.java).
If you need to implement specific settings externalization rules and I/O behaviour,
use
[RunConfiguration](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
[RunConfiguration](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java)
interface.
```java

4
tutorials/writing_tests_for_plugins/tests_prerequisites.md
View File

@ -16,7 +16,7 @@ In our tests we will use test data, so we need one more folder *"testData"* to s
Since some of our tests will use Java files as test data, we need to mock up the project SDK.
IntelliJ IDEA does everything automatically when we use special utility class
[LightCodeInsightFixtureTestCase](https://github.com/JetBrains/intellij-community/blob/master/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java).
[LightCodeInsightFixtureTestCase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java).
All we need to do is to point the working directory of the run configuration to the root of IntelliJ IDEA Community Edition sources and enable the following VM options:
@ -27,7 +27,7 @@ All we need to do is to point the working directory of the run configuration to
**Note**:
> Keep in mind that we have changed the _working directory_, so all the paths in tests extended from
> [LightCodeInsightFixtureTestCase](https://github.com/JetBrains/intellij-community/blob/master/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java)
> [LightCodeInsightFixtureTestCase](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java)
> will use relative path to the _source root_ of IntelliJ IDEA Community Edition.
-----

12
user_interface_components/dialog_wrapper.md
View File

@ -6,7 +6,7 @@ title: DialogWrapper
## DialogWrapper
The
[DialogWrapper](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
[DialogWrapper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
is the base class which is supposed to be used for all modal dialogs (and some non-modal dialogs) shown in *IntelliJ IDEA* plugins.
It provides the following features:
@ -30,7 +30,7 @@ It provides the following features:
When using the
[DialogWrapper](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
[DialogWrapper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
class for your own dialog, you need to follow these steps:
* Call the base class constructor and provide either a project in the frame of which the dialog will be displayed, or a parent component for the dialog.
@ -48,10 +48,10 @@ class for your own dialog, you need to follow these steps:
* *Optional*: Override the `getHelpId()` method to return the context help topic associated with the dialog.
The
[DialogWrapper](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
[DialogWrapper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java)
class is often used together with UI Designer forms.
In this case, you bind a UI Designer form to your class extending
[DialogWrapper](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java),
[DialogWrapper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java),
bind the top-level panel of the form to a field and return that field from the `createCenterPanel()` method.
To display the dialog, you call the `show()` method and then use the `getExitCode()` method to check how the dialog was closed.
@ -59,14 +59,14 @@ To display the dialog, you call the `show()` method and then use the `getExitCod
To customize the buttons displayed in the dialog (replacing the standard `OK/Cancel/Help` set of buttons), you can override either the `createActions()` or `createLeftActions()` methods.
Both of these methods return an array of Swing Action objects.
If the button that you're adding closes the dialog, you can use
[DialogWrapperExitAction](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java),
[DialogWrapperExitAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java),
as the base class for your action.
To validate the data entered into the dialog, you can override the `doValidate()` method.
The method will be called automatically by timer.
If the currently entered data is valid, you need to return null from your implementation.
Otherwise, you need to return a
[ValidationInfo](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/ValidationInfo.java)
[ValidationInfo](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/ValidationInfo.java)
class, which encapsulates an error message and an optional component associated with the invalid data.
If you specify a component, an error icon will be displayed next to it, and it will be focused when the user tries to invoke the `OK` action.

12
user_interface_components/editor_components.md
View File

@ -9,11 +9,11 @@ Compared to
*IntelliJ IDEA's* editor component has a ton of advantages: syntax highlighting support, code completion, code folding and much more.
*IntelliJ IDEA's* editors are normally displayed in editor tabs, but they can be embedded in dialogs or toolwindows, too.
This is enabled by the
[EditorTextField](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
[EditorTextField](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
component.
When creating an
[EditorTextField](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/EditorTextField.java),
[EditorTextField](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java),
you can specify the following attributes:
* The file type according to which the text in the text field is parsed;
@ -23,19 +23,19 @@ you can specify the following attributes:
* Whether the text field is single-line or multiline.
A common use case for
[EditorTextField](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
[EditorTextField](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
is entering the name of a Java class or package.
This can be accomplished with the following steps:
* Use
[JavaCodeFragmentFactory.getInstance().createReferenceCodeFragment()](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-api/src/com/intellij/psi/JavaCodeFragmentFactory.java)
[JavaCodeFragmentFactory.getInstance().createReferenceCodeFragment()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-api/src/com/intellij/psi/JavaCodeFragmentFactory.java)
to create a code fragment representing the class or package name;
* Call
[PsiDocumentManager.getInstance().getDocument()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java)
[PsiDocumentManager.getInstance().getDocument()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java)
to get the document corresponding to the code fragment;
* Pass the returned document to the
[EditorTextField](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
[EditorTextField](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java)
constructor or its `setDocument()` method.

14
user_interface_components/file_and_class_choosers.md
View File

@ -5,29 +5,29 @@ title: File and Class Choosers
## File Choosers
To let a user choose a file, directory or multiple files, use the
[FileChooser.chooseFiles()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooser.java)
[FileChooser.chooseFiles()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooser.java)
method.
This method has multiple overloads.
The best method to use is the one which returns void and takes a callback receiving the list of selected files as a parameter.
This is the only overload which will display a native file open dialog on Mac OS X.
The
[FileChooserDescriptor](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java)
[FileChooserDescriptor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java)
class allows you to control which files can be selected.
The constructor parameters specify whether files and/or directories can be selected, and whether multiple selection is allowed.
For more fine-grained control over the allowed selection, you can overload the `isFileSelectable()` method.
You can also customize the presentation of files by overloading `getIcon()`, `getName()` and `getComment()` methods on
[FileChooserDescriptor](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java).
[FileChooserDescriptor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java).
Note that the native Mac OS X file chooser does not support most of the customizations, so if you rely on them, you need to use an overload of `chooseFiles()` which displays the standard *IntelliJ IDEA* dialog.
A very common way of using file choosers is to use a text field for entering the path with an ellipsis button ("...") for showing the file chooser.
To create such a control, use the
[TextFieldWithBrowseButton](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java)
[TextFieldWithBrowseButton](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java)
component and call the `addBrowseFolderListener()` method on it to set up the file chooser.
As an added bonus, this will enable filename completion when entering paths in the text box.
An alternative UI for selecting files, which works best when the most common way of selecting a file is by typing its name, is available through the
[TreeFileChooserFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/ide/util/TreeFileChooserFactory.java) class.
[TreeFileChooserFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/TreeFileChooserFactory.java) class.
The dialog shown by this API has two tabs:
@ -40,11 +40,11 @@ To show the dialog, call `showDialog()` on the chooser returned from `createFile
## Class and Package Choosers
If you want to offer the user a possibility to select a Java class, you can use the
[TreeClassChooserFactory](https://github.com/JetBrains/intellij-community/blob/master/java/openapi/src/com/intellij/ide/util/TreeClassChooserFactory.java)
[TreeClassChooserFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/TreeClassChooserFactory.java)
class.
Its different methods allow you to specify the scope from which the classes are taken, to restrict the choice to descendants of a specific class or implementations of an interface, and to include or exclude inner classes from the list.
For choosing a Java package, you can use the
[PackageChooserDialog](https://github.com/JetBrains/intellij-community/blob/master/java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java)
[PackageChooserDialog](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java)
class.

28
user_interface_components/lists_and_trees.md
View File

@ -8,9 +8,9 @@ title: List and Tree Controls
Whenever you would normally use a standard
[Swing JList](http://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html)
component, it's recommended to use the
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java)
[JBList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java)
class as drop-in replacement.
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java)
[JBList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java)
supports the following additional features on top of
[JList](http://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html):
@ -23,20 +23,20 @@ supports the following additional features on top of
This can be enabled by calling `setPaintBusy()`.
Similarly, the
[Tree](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/treeStructure/Tree.java)
[Tree](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/treeStructure/Tree.java)
class provides a replacement for the standard
[JTree](http://docs.oracle.com/javase/8/docs/api/javax/swing/JTree.html)
class.
In addition to the features of
[JBList](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/components/JBList.java),
[JBList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java),
it supports wide selection painting (Mac style) and auto-scroll on drag & drop.
### ColoredListCellRenderer and ColoredTreeCellRenderer
When you need to customize the presentation of items in a list box or a tree, it's recommended to use the
[ColoredListCellRenderer](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ColoredListCellRenderer.java)
[ColoredListCellRenderer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ColoredListCellRenderer.java)
or
[ColoredTreeCellRenderer](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ColoredTreeCellRenderer.java)
[ColoredTreeCellRenderer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ColoredTreeCellRenderer.java)
classes as the cell renderer.
These classes allow you to compose the presentation out of multiple text fragments with different attributes by calling `append()` and to set an optional icon for the item by calling `setIcon`.
The renderer automatically takes care of setting the correct text color for selected items and of many other platform-specific rendering details.
@ -44,23 +44,23 @@ The renderer automatically takes care of setting the correct text color for sele
### ListSpeedSearch and TreeSpeedSearch
To facilitate keyboard-based selection of items in a list box or a tree, you can install a speed search handler on it using the
[ListSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
[ListSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
and
[TreeSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java).
[TreeSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java).
This can be done simply by calling `new ListSpeedSeach(list)` or `new TreeSpeedSearch(tree)`.
If you need to customize the text which is used to locate the element, you can override the `getElementText()` method.
Alternatively, you can pass a function to convert items to strings.
A function needs to be passed as `elementTextDelegate` to the
[ListSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
[ListSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java)
constructor or as `toString` to the
[TreeSpeedSearch](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java)
[TreeSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java)
constructor.
### ToolbarDecorator
A very common task in plugin development is showing a list or a tree where the user is allowed to add, remove, edit or reorder the items.
The implementation of this task is greatly facilitated by the
[ToolbarDecorator](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
[ToolbarDecorator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
class.
This class provides a toolbar with actions on items and automatically enables drag & drop reordering of items in list boxes if supported by the underlying list model.
The position of the toolbar above or below the list depends on the platform under which *IntelliJ IDEA* is running.
@ -68,13 +68,13 @@ The position of the toolbar above or below the list depends on the platform unde
To use a toolbar decorator:
* If you need to support removing and reordering of items in a list box, make sure the model of your list implements the
[EditableModel](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/util/ui/EditableModel.java)
[EditableModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/util/ui/EditableModel.java)
interface.
[CollectionListModel](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/CollectionListModel.java)
[CollectionListModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/CollectionListModel.java)
is a handy model class that implements this interface.
* Call
[ToolbarDecorator.createDecorator](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
[ToolbarDecorator.createDecorator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java)
to create a decorator instance.
* If you need to support adding and/or removing items, call `setAddAction()` and/or `setRemoveAction()`.

12
user_interface_components/misc_swing_components.md
View File

@ -6,11 +6,11 @@ title: Miscellaneous Swing Components
### Messages
The
[Messages](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/Messages.java)
[Messages](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/Messages.java)
class provides a way to show simple message boxes, input dialogs (modal dialogs with a text field) and chooser dialogs (modal dialogs with a combo box).
The function of different methods of the class should be clear from their names.
When running on Mac OS X, the message boxes shown by the
[Messages](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/Messages.java)
[Messages](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/Messages.java)
class use native UI.
The `showCheckboxMessageDialog()` function provides an easy way to implement a `Do not show this again` checkbox on messages.
@ -21,27 +21,27 @@ Please refer to the [Notifications](notifications.md) topic for more information
### JBSplitter
The
[JBSplitter](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
[JBSplitter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
class is JetBrains' replacement for the standard
[JSplitPane](http://docs.oracle.com/javase/8/docs/api/javax/swing/JSplitPane.html)
class.
Unlike some other JetBrains-enhanced Swing components, it's not a drop-in replacement and has a different API.
However, to achieve a consistent user experience, it's recommended to use
[JBSplitter](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
[JBSplitter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
instead of the standard
[JSplitPane](http://docs.oracle.com/javase/8/docs/api/javax/swing/JSplitPane.html)
in your plugins.
To add your components to the splitter, call the `setFirstComponent()` and `setSecondComponent()` methods.
[JBSplitter](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
[JBSplitter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java)
supports automatic remembering of the split proportion.
In order to enable it, call the `setSplitterProportionKey()` method and pass the ID under which the proportion will be stored.
### JBTabs
The
[JBTabs](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/tabs/JBTabs.java)
[JBTabs](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/tabs/JBTabs.java)
class is JetBrains' implementation of the tab control, used for editor tabs and a few other components.
It has a significantly different look & feel compared to the standard Swing tabs, and looks less native on the Mac OS X platform, so it's up to you to choose which tab control would be more appropriate for your plugin.

18
user_interface_components/notifications.md
View File

@ -11,23 +11,23 @@ As a replacement, *IntelliJ IDEA* provides multiple non-modal notification UI op
### Dialogs
When working in a modal dialog, instead of checking the validity of the input when the `OK` button is pressed and notifying the user about invalid data with a modal dialog, the recommended approach is to use
[DialogBuilder.doValidate()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/DialogBuilder.java),
[DialogBuilder.doValidate()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogBuilder.java),
which was described previously.
### Editor Hints
For actions invoked from the editor (such as refactorings, navigation actions and different code insight features), the best way to notify the user about the inability to perform an action is to use the
[HintManager](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java)
[HintManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java)
class.
Its method `showErrorHint()` displays a floating popup above the editor which is automatically hidden when the user starts performing another action in the editor.
Other
[HintManager](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java)
[HintManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java)
methods can be used for displaying other kinds of non-modal notification hints over an editor.
### Top-Level Notifications
The most general way to display non-modal notifications is to use the
[Notifications](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/Notification.java)
[Notifications](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java)
class.
It has two main advantages:
@ -37,19 +37,19 @@ It has two main advantages:
* All displayed notifications are gathered in the Event Log toolwindow and can be reviewed later
The specific method used to display a notification is
[Notifications.Bus.notify()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/Notification.java).
[Notifications.Bus.notify()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java).
The text of the notification can include HTML tags.
You can allow the user to interact with the notification by including hyperlink tags in the notification text and passing a
[NotificationListener](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/NotificationListener.java)
[NotificationListener](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/NotificationListener.java)
instance to the constructor of the
[Notification](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/Notification.java)
[Notification](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java)
class.
The `groupDisplayId` parameter of the
[Notification](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/Notification.java)
[Notification](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java)
constructor specifies a notification type.
The user can choose the display type corresponding to each notification type under `Settings | Notifications`.
To specify the preferred display type, you need to call
[Notifications.Bus.register()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/notification/Notification.java)
[Notifications.Bus.register()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java)
before displaying any notifications.

12
user_interface_components/popups.md
View File

@ -11,7 +11,7 @@ Making use of these controls in your plugin ensures a consistent user experience
Popups can optionally display a title, are optionally movable and resizable (and support remembering their size), and can be nested (show another popup when an item is selected).
The
[JBPopupFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
[JBPopupFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
interface allows you to create popups that display different kinds of components, depending on your specific needs.
The most commonly used methods are:
@ -28,7 +28,7 @@ component in the popup.
Action group popups support different ways of choosing an action from the keyboard, in additional to the normal arrow keys.
By passing one of the constants in the
[ActionSelectionAid](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
[ActionSelectionAid](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
enumeration, you can choose whether an action can be selected by pressing a key corresponding to its sequential number, typing part of its text (speed search) or pressing a mnemonic character.
For popups with a fixed set of items, the recommended selection method is sequential numbering;
for popups with a variable and potentially large number of items, speed search typically works best.
@ -36,12 +36,12 @@ for popups with a variable and potentially large number of items, speed search t
If you need to create a list-like popup which is more flexible than a simple
[JList](http://docs.oracle.com/javase/8/docs/api/javax/swing/JList.html)
but don't want to represent the possible choices as actions in an action group, you can work directly with the
[ListPopupStep](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/ListPopupStep.java)
[ListPopupStep](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/ListPopupStep.java)
interface and the
[JBPopupFactory.createListPopup()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
[JBPopupFactory.createListPopup()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java)
method.
Normally you don't need to implement the entire interface; instead, you can derive from the
[BaseListPopupStep](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/util/BaseListPopupStep.java)
[BaseListPopupStep](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/util/BaseListPopupStep.java)
class.
The key methods to override are `getTextFor()` (returning the text to display for an item) and `onChosen()` (called when an item is selected).
By returning a new popup step from the `onChosen()` method, you can implement hierarchical (nested) popups.
@ -55,6 +55,6 @@ You can let *IntelliJ IDEA* automatically choose the position based on the conte
> The `show()` methods return immediately and do not wait for the popup to be closed.
If you need to perform some action when the popup is closed, you can either attach a listener to it using the `addListener()` method, override a method of the popup contents such as
[PopupStep.onChosen()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/ui/popup/PopupStep.java),
[PopupStep.onChosen()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/PopupStep.java),
or attach an event handler to your own component within the popup.

14
user_interface_components/tool_windows.md
View File

@ -27,20 +27,20 @@ The extension point attributes specify all the data which is necessary to displa
* The icon to display on the toolwindow button (13x13 pixels)
In addition to that, you specify the *factory class* - the name of a class implementing the
[ToolWindowFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java)
[ToolWindowFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java)
interface.
When the user clicks on the toolwindow button, the `createToolWindowContent()` method of the factory class is called, and initializes the UI of the toolwindow.
This procedure ensures that unused toolwindows don't cause any overhead in startup time or memory usage: if a user does not interact with the toolwindow of your plugin, no plugin code will be loaded or executed.
If the toolwindow of your plugin doesn't need to be displayed for all projects, you can also specify the *conditionClass* attribute - the qualified name of a class implementing the
[Condition\<Project\>](https://github.com/JetBrains/intellij-community/blob/master/platform/util-rt/src/com/intellij/openapi/util/Condition.java)
[Condition\<Project\>](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util-rt/src/com/intellij/openapi/util/Condition.java)
interface (this can be the same class as the toolwindow factory implementation).
If the condition returns false, the toolwindow will not be displayed.
Note that the condition is evaluated only once when the project is loaded;
if you'd like to show your and hide toolwindow dynamically while the user is working with the project, you need to use the second method for toolwindow registration.
The second method involves simply calling
[ToolWindowManager.registerToolWindow()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.java)
[ToolWindowManager.registerToolWindow()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.java)
from your plugin code.
The method has multiple overloads that can be used depending on your task.
If you use an overload that takes a component, the component becomes the first content (tab) displayed in the toolwindow.
@ -50,15 +50,15 @@ Because of that, toolwindows are normally disabled while building indices, unles
As mentioned previously, toolwindows can contain multiple tabs, or contents.
To manage the contents of a toolwindow, you can call
[ToolWindow.getContentManager()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/wm/ToolWindow.java).
[ToolWindow.getContentManager()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindow.java).
To add a tab (content), you first need to create it by calling
[ContentManager.getFactory().createContent()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/content/ContentManager.java),
[ContentManager.getFactory().createContent()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/ContentManager.java),
and then to add it to the toolwindow using
[ContentManager.addContent()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/content/ContentManager.java).
[ContentManager.addContent()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/ContentManager.java).
You can control whether the user is allowed to close tabs either globally or on a per-tab basis.
The former is done by passing the `canCloseContents` parameter to the `registerToolWindow()` function, or by specifying
`canCloseContents="true"` in *plugin.xml*.
If closing tabs is enabled in general, you can disable closing of specific tabs by calling
[Content.setCloseable(false)](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/ui/content/Content.java).
[Content.setCloseable(false)](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/Content.java).