diff --git a/_config.yml b/_config.yml index 80e1e0c9aca..e0d950745c1 100644 --- a/_config.yml +++ b/_config.yml @@ -4,3 +4,11 @@ product_version: product_type: DevGuide baseurl: /intellij/sdk/docs/ + +# This is tag 143.381.42 +upsource: + server: upsource.jetbrains.com + repo: idea-ce + # This is the SHA for the 143.381.42 release, but it's not indexed on Upsource + # commit: db70c2b4bdc79eb5f551632aade418c0de50e840 + commit: 1731d054af4ca27aa827c03929e27eeb0e6a8366 diff --git a/basics/action_system.md b/basics/action_system.md index 5f0f170d7b6..e5244ef048b 100644 --- a/basics/action_system.md +++ b/basics/action_system.md @@ -4,15 +4,15 @@ title: Action System ## Executing and updating actions -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://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. An action is a class, derived from the [`AnAction`](upsource:///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. Actions are organized into groups, which, in turn, can contain other groups. A group of actions can form a toolbar or a menu. 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java) class. +Every action and action group has an unique identifier. Identifiers of many of the standard IDEA actions are defined in the [IdeActions](upsource:///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://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. +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`](upsource:///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. To update the state of the action, the method `AnAction.update()` is periodically called by IDEA. The `AnActionEvent` object passed to this method carries the information about the current context for the action, and in particular, the specific presentation which needs to be updated. @@ -115,8 +115,8 @@ Registering actions in `plugin.xml` is demonstrated in the following example. Th 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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) class. +* First, an instance of the class derived from `AnAction` must be passed to the `registerAction` method of the [ActionManager](upsource:///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](upsource:///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. diff --git a/basics/architectural_overview/file_view_providers.md b/basics/architectural_overview/file_view_providers.md index 63cc9cb89f7..d8ada684998 100644 --- a/basics/architectural_overview/file_view_providers.md +++ b/basics/architectural_overview/file_view_providers.md @@ -2,9 +2,9 @@ title: File View Providers --- -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. +A file view provider (see the [FileViewProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/jsp-openapi/src/com/intellij/psi/jsp/JspFile.java)). +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](upsource:///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. @@ -18,17 +18,17 @@ A `FileViewProvider` instance corresponds to a single `VirtualFile`, a single `D ## What can I do with an FVP? * 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Language.java) type defined in [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 get the PSI tree for a particular language: `fileViewProvider.getPsi(language)`, where the `language` parameter can take values of the [Language](upsource:///platform/core-api/src/com/intellij/lang/Language.java) type defined in [StdLanguages](upsource:///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)` ## How do I extend the FileViewProvider? To create a file type that has multiple interspersing trees for different languages, your plugin must contain an extension to the `fileType.fileViewProviderFactory` [extension point](/basics/plugin_structure/plugin_extensions_and_extension_points.html) available in the *IntelliJ Platform* core. -This extension point is declared using the [FileTypeExtensionPoint](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/FileTypeExtensionPoint.java) +This extension point is declared using the [FileTypeExtensionPoint](upsource:///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://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 access this extension point, create a Java class that implements the [FileViewProviderFactory](upsource:///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 `` section of the plugin.xml file, add the following syntax: diff --git a/basics/architectural_overview/psi_elements.md b/basics/architectural_overview/psi_elements.md index b7cbf5bf216..d67f950ee3f 100644 --- a/basics/architectural_overview/psi_elements.md +++ b/basics/architectural_overview/psi_elements.md @@ -6,7 +6,7 @@ A PSI (Program Structure Interface) file represents a hierarchy of PSI elements PSI elements and operations on the level of individual PSI elements are used to explore the internal structure of source code as it is interpreted by **IntelliJ IDEA**. For example, you can use PSI elements to perform code analysis, such as [code inspections](http://www.jetbrains.com/idea/help/code-inspection.html) or [intention actions](http://www.jetbrains.com/idea/help/intention-actions.html). -The [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. +The [PsiElement](upsource:///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? diff --git a/basics/architectural_overview/psi_files.md b/basics/architectural_overview/psi_files.md index 66be79af97e..aaeca33418b 100644 --- a/basics/architectural_overview/psi_files.md +++ b/basics/architectural_overview/psi_files.md @@ -4,7 +4,7 @@ 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://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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/xml-psi-api/src/com/intellij/psi/xml/XmlFile.java) class represents an XML file. +The [PsiFile](upsource:///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](upsource:///java/java-psi-api/src/com/intellij/psi/PsiJavaFile.java) class represents a Java file, and the [XmlFile](upsource:///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). @@ -24,7 +24,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://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. +As PSI is language-dependent, PSI files are created through the [Language](upsource:///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. @@ -34,9 +34,9 @@ Like documents, PSI files are weakly referenced from the corresponding `VirtualF ## How do I create a PSI file? -The [`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. +The [`PsiFileFactory`](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiDirectory.java)`.add()` method. +To save the PSI file to disk, use the [`PsiDirectory`](upsource:///platform/core-api/src/com/intellij/psi/PsiDirectory.java)`.add()` method. ## How do I get notified when PSI files change? diff --git a/basics/architectural_overview/virtual_file.md b/basics/architectural_overview/virtual_file.md index 933276a6128..420ee0bb4e1 100644 --- a/basics/architectural_overview/virtual_file.md +++ b/basics/architectural_overview/virtual_file.md @@ -2,7 +2,7 @@ title: Virtual Files --- -A virtual file [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 a version control repository, and so on. +A virtual file [com.intellij.openapi.vfs.VirtualFile](upsource:///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 a version control 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. @@ -39,9 +39,9 @@ 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://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](/basics/plugin_structure/plugin_components.md). +To provide an alternative file system implementation (for example, an FTP file system), implement the [VirtualFileSystem](upsource:///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](/basics/plugin_structure/plugin_components.md). -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://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. +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](upsource:///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? diff --git a/basics/checkout_and_build_community.md b/basics/checkout_and_build_community.md index e034bafee23..4595a75a514 100644 --- a/basics/checkout_and_build_community.md +++ b/basics/checkout_and_build_community.md @@ -81,7 +81,7 @@ To develop IntelliJ IDEA, you can use either [IntelliJ IDEA Community Edition](h ## Building and Running from the Command Line -To build the distribution archive of *IntelliJ IDEA Community Edition*, execute the [build.xml](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/build.xml) Ant build script in the root directory of the source code. +To build the distribution archive of *IntelliJ IDEA Community Edition*, execute the [build.xml](upsource:///build.xml) Ant build script in the root directory of the source code. ![Execute Ant Build Script](img/ant_build_xml.png) diff --git a/basics/getting_started/creating_an_action.md b/basics/getting_started/creating_an_action.md index 746caa6b130..373117564a4 100644 --- a/basics/getting_started/creating_an_action.md +++ b/basics/getting_started/creating_an_action.md @@ -2,7 +2,7 @@ title: Creating an action --- -Your plugins can customize the Intellij IDEA UI by adding new items to the menus and toolbars. Intellij IDEA provides the [AnAction.java](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 each time you select a menu item or click a toolbar button. +Your plugins can customize the Intellij IDEA UI by adding new items to the menus and toolbars. Intellij IDEA provides the [AnAction.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) class whose `actionPerformed` method is called each time you select a menu item or click a toolbar button. To customize *IntelliJ IDEA*, you should perform two basic steps: diff --git a/basics/indexing_and_psi_stubs/file_based_indexes.md b/basics/indexing_and_psi_stubs/file_based_indexes.md index 187e1fd0ecf..ac44ccf92f5 100644 --- a/basics/indexing_and_psi_stubs/file_based_indexes.md +++ b/basics/indexing_and_psi_stubs/file_based_indexes.md @@ -20,9 +20,9 @@ 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://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. +A fairly simple file-based index implementation is the [UI Designer bound forms index](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndexExtension.java). A file based index should be registered in the `` extension point. +Each specific index implementation is a class extending [FileBasedIndexExtension](upsource:///platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndexExtension.java). A file based index should be registered in the `` extension point. The implementation of a file based contains of the following main parts: @@ -34,13 +34,13 @@ The implementation of a file based contains of the following main parts: * `getInputFilter()` allows to restrict the indexing only to a certain set of files. * `getVersion()` returns the version of the index implementation. 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/util/indexing/ScalarIndexExtension.java) as the base class. +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](upsource:///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. Otherwise your index will not be correctly updated when the external data changes, and you will have stale data in your index. ## Accessing a file based index -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. +Access to file based indexes is performed through the [FileBasedIndex](upsource:///platform/indexing-api/src/com/intellij/util/indexing/FileBasedIndex.java) class. The following primary operations are supported: @@ -59,6 +59,6 @@ The *IntelliJ Platform* contains a number of the standard file-based indexes. Th * Word index * File name index -Generally, the word index should be accessed indirectly, but using the helper methods in the [`PsiSearchHelper`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/psi/search/PsiSearchHelper.java) class. +Generally, the word index should be accessed indirectly, but using the helper methods in the [`PsiSearchHelper`](upsource:///platform/indexing-api/src/com/intellij/psi/search/PsiSearchHelper.java) class. -The second index is [`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://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. +The second index is [`FilenameIndex`](upsource:///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`](upsource:///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. diff --git a/basics/indexing_and_psi_stubs/stub_indexes.md b/basics/indexing_and_psi_stubs/stub_indexes.md index 44e66f5c153..fd9fb4153dc 100644 --- a/basics/indexing_and_psi_stubs/stub_indexes.md +++ b/basics/indexing_and_psi_stubs/stub_indexes.md @@ -14,12 +14,12 @@ To support stubs for your custom language, you first need to decide which of the 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://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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/Property.java)). +* Define an interface for the stub, derived from the `StubElement` interface ([example](upsource:///plugins/properties/properties-psi-api/src/com/intellij/lang/properties/psi/PropertyStub.java)). +* Provide an implementation for the interface ([example](upsource:///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](upsource:///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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesElementTypes.java)). +* Create a class which implements `IStubElementType` and is parameterized with the stub interface and the actual PSI element interface ([example](upsource:///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](upsource:///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)). The following steps need to be performed only once for each language that supports stubs: @@ -41,7 +41,7 @@ It's essential to make sure that all information stored in the stub tree depends 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://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 `` extension point. +A stub index is a class which extends [`AbstractStubIndex`](upsource:///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](upsource:///platform/indexing-api/src/com/intellij/psi/stubs/StringStubIndexExtension.java). Stub index implementation classes are registered in the `` 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. diff --git a/basics/persisting_state_of_components.md b/basics/persisting_state_of_components.md index a83ac7cc349..ff531871ed4 100644 --- a/basics/persisting_state_of_components.md +++ b/basics/persisting_state_of_components.md @@ -2,7 +2,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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface. +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](upsource:///platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface. ## Using PropertiesComponent for simple non-roamable persistence diff --git a/basics/plugin_structure/plugin_actions.md b/basics/plugin_structure/plugin_actions.md index 456091fd880..94360586100 100644 --- a/basics/plugin_structure/plugin_actions.md +++ b/basics/plugin_structure/plugin_actions.md @@ -2,6 +2,6 @@ title: Plugin Actions --- -*Intellij IDEA* provides the concept of _actions_. An action is a class, derived from the [`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. +*Intellij IDEA* provides the concept of _actions_. An action is a class, derived from the [`AnAction`](upsource:///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. A group of actions can form a toolbar or a menu. Subgroups of the group can form submenus of a menu. You can find detailed information on how to create and register your actions in [IntelliJ IDEA Action System](/basics/action_system.md). diff --git a/basics/plugin_structure/plugin_components.md b/basics/plugin_structure/plugin_components.md index ed82d10a2ba..296eadaf92e 100644 --- a/basics/plugin_structure/plugin_components.md +++ b/basics/plugin_structure/plugin_components.md @@ -4,14 +4,14 @@ title: Plugin Components Components are the fundamental concept of plugin integration. 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://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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java) in every project loaded in *IntelliJ IDEA*. +* **Application level components** are created and initialized when *IntelliJ IDEA* starts up. They can be acquired from the [Application](upsource:///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`](upsource:///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](upsource:///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 `getComponent(Class)` 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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/Module.java)) cannot have the same interface class. The same class may be specified for both interface and Implementation. +Note that two components of the same level ([Application](upsource:///platform/core-api/src/com/intellij/openapi/application/Application.java), [Project](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java) or [Module](upsource:///platform/core-api/src/com/intellij/openapi/module/Module.java)) cannot have the same interface class. The same class may be specified for both interface and Implementation. Each component has a unique name which is used for its externalization and other internal needs. The name of a component is returned by its `getComponentName()` method. @@ -21,7 +21,7 @@ It is recommended to name components in the form `. ## Application level components -Optionally, an application level component's implementation class may implement the [ApplicationComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java) interface. +Optionally, an application level component's implementation class may implement the [ApplicationComponent](upsource:///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. @@ -39,13 +39,13 @@ The IntelliJ interface will help you declare the application component's impleme 2. In the *New* menu, click *Application Component*. 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://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. +*IntelliJ IDEA* will generate a new Java class that implements the [ApplicationComponent](upsource:///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 -A project level component's implementation class may implement the [ProjectComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java) interface. +A project level component's implementation class may implement the [ProjectComponent](upsource:///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://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. +The constructor of a project level component can have a parameter of the [Project](upsource:///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. Note that project level components must be registered in the `` section of the `plugin.xml` file (see [Plugin Configuration File](plugin_configuration_file.md)). @@ -62,11 +62,11 @@ The IDEA interface will help you declare the project component's implementation 2. In the *New* menu, click *Project Component*. 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://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. +*IntelliJ IDEA* will generate a new Java class that implements the [ProjectComponent](upsource:///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, a module level component's implementation class may implement the [ModuleComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/module/ModuleComponent.java) interface. +Optionally, a module level component's implementation class may implement the [ModuleComponent](upsource:///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. @@ -84,15 +84,15 @@ The IDEA interface will help you declare the module component's implementation c 2. In the *New* menu, click *Module Component*. 3. 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://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. +*IntelliJ IDEA* will generate a new Java class that implements the [ModuleComponent](upsource:///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 the state of components -The state of every component will be automatically saved and loaded if the component's class implements the [JDOMExternalizable](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java) (deprecated) or [PersistentStateComponent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface. +The state of every component will be automatically saved and loaded if the component's class implements the [JDOMExternalizable](upsource:///platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java) (deprecated) or [PersistentStateComponent](upsource:///platform/core-api/src/com/intellij/openapi/components/PersistentStateComponent.java) interface. -When the component's class implements the [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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/components/State.java) and [@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 [PersistentStateComponent](upsource:///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](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/State.java) and [@Storage](upsource:///platform/projectModel-api/src/com/intellij/openapi/components/Storage.java) annotations in your Java code. -When the component's class implements the [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: +When the component's class implements the [JDOMExternalizable](upsource:///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. @@ -116,14 +116,14 @@ If a component has defaults, the `readExternal()` method is called twice: 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://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://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://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://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://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. +* Initialization - the `initComponent` method is invoked (if the component implements the [ApplicationComponent](upsource:///platform/core-api/src/com/intellij/openapi/components/ApplicationComponent.java) interface). +* Configuration - the `readExternal` method is invoked (if the component implements [JDOMExternalizable](upsource:///platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java) interface), or the `loadState` method is invoked (if the component implements [PersistentStateComponent](upsource:///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](upsource:///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](upsource:///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://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). +* Saving configuration - the `writeExternal` method is invoked (if the component implements the [JDOMExternalizable](upsource:///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. Note that you should not request any other components using the `getComponent()` method in the constructor of your component, otherwise you'll get an assertion. If you need access to other components when initializing your component, you can specify them as constructor parameters or access them in the `initComponent` method. diff --git a/basics/plugin_structure/plugin_extensions_and_extension_points.md b/basics/plugin_structure/plugin_extensions_and_extension_points.md index 13f9065d3fc..472091fccb1 100644 --- a/basics/plugin_structure/plugin_extensions_and_extension_points.md +++ b/basics/plugin_structure/plugin_extensions_and_extension_points.md @@ -30,7 +30,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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java) annotation. +* The `beanClass` attribute sets a bean class that specifies one or several properties annotated with the [@Attribute](upsource:///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. @@ -64,7 +64,7 @@ Note that to declare an extension designed to access the `MyExtensionPoint1` ext 2. Add a new child element to the `` element. The child element name must match the name of the extension point you want the extension to access. 3. Depending on the type of the extension point, do one of the following: * 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java) annotations in the specified bean class. + * If the extension point was declared using the `beanClass` attribute, for newly added child element, set all attributes annotated with the [@Attribute](upsource:///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 *IntelliJ Platform* and one extension to access the `MyExtensionPoint1` extension point in a test plugin: @@ -89,9 +89,9 @@ To clarify this procedure, consider the following sample section of the `plugin. To get a list of extension points available in the *IntelliJ Platform* core, consult the `` section of the following XML configuration files: -* [`LangExtensionPoints.xml`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/LangExtensionPoints.xml) -* [`PlatformExtensionPoints.xml`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml) -* [`VcsExtensionPoints.xml`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/VcsExtensionPoints.xml) +* [`LangExtensionPoints.xml`](upsource:///platform/platform-resources/src/META-INF/LangExtensionPoints.xml) +* [`PlatformExtensionPoints.xml`](upsource:///platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml) +* [`VcsExtensionPoints.xml`](upsource:///platform/platform-resources/src/META-INF/VcsExtensionPoints.xml) ## Additional Information and Samples diff --git a/basics/plugin_structure/plugin_services.md b/basics/plugin_structure/plugin_services.md index 82b50aec497..7da063fce3d 100644 --- a/basics/plugin_structure/plugin_services.md +++ b/basics/plugin_structure/plugin_services.md @@ -4,7 +4,7 @@ title: Plugin Services The *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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ServiceManager.java) class. +A _service_ is a plugin component loaded on demand, when your plugin calls the `getService` method of the [ServiceManager](upsource:///platform/core-api/src/com/intellij/openapi/components/ServiceManager.java) class. The *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. The service implementation class is used for service instantiation. diff --git a/basics/project_structure.md b/basics/project_structure.md index 92e87198c24..7e42439432c 100644 --- a/basics/project_structure.md +++ b/basics/project_structure.md @@ -73,10 +73,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://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. +* [`Project`](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java) interface. +* [`ProjectRootManager`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class. +* [`ProjectManager`](upsource:///platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class. +* [`ProjectFileIndex`](upsource:///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 [Persisting State of Components](persisting_state_of_components.md) for more information. @@ -158,13 +158,13 @@ Note that by default, the project modules use the project SDK. Optionally, you c The *IntelliJ Platform* provides a number of Java classes and interfaces you can use to work with modules: -* [`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. +* [`ModuleManager`](upsource:///platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class. +* [`Module`](upsource:///platform/core-api/src/com/intellij/openapi/module/Module.java) interface. +* [`ModuleRootManager`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class. +* [`ModuleRootModel`](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface. +* [`ModuleUtil`](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class. +* [`ModifiableModuleModel`](upsource:///platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface. +* [`ModifiableRootModel`](upsource:///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. @@ -176,7 +176,7 @@ Use the `ModuleManager.getModules()` method. _Order entries_ include SDK, libraries and other modules the module uses. With the *IntelliJ IDEA* UI, you can view order entries for a module on the [Dependencies](http://www.jetbrains.com/idea/help/dependencies-tab.html) 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/OrderEnumerator.java) class. +To explore the [module dependencies](http://www.jetbrains.com/idea/help/dependencies-tab.html), use the [OrderEnumerator](upsource:///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: @@ -186,7 +186,7 @@ VirtualFile[] roots = ModuleRootManager.getInstance(module).orderEntries().class ### How do I get the SDK the module uses? -Use the `ModuleRootManager.getSdk()` method. This method returns a value of the [Sdk](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/projectRoots/Sdk.java) type. +Use the `ModuleRootManager.getSdk()` method. This method returns a value of the [Sdk](upsource:///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: @@ -270,8 +270,8 @@ for (String each : lib.getUrls(OrderRootType.CLASSES)) { Messages.showInfoMessage(roots.toString(), "Library Info"); ``` -In this sample code, `lib` is of the [Library](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/libraries/Library.java) type. +In this sample code, `lib` is of the [Library](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/facet/FacetManager.java) and [Facet](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/facet/Facet.java) classes. +Use the [FacetManager](upsource:///platform/lang-api/src/com/intellij/facet/FacetManager.java) and [Facet](upsource:///platform/lang-api/src/com/intellij/facet/Facet.java) classes. diff --git a/basics/run_configurations/run_configuration_execution.md b/basics/run_configurations/run_configuration_execution.md index d3c76d89e11..c1c77e74fea 100644 --- a/basics/run_configurations/run_configuration_execution.md +++ b/basics/run_configurations/run_configuration_execution.md @@ -17,7 +17,7 @@ Implementations of `ProgramRunner.execute()` go through the following steps to e ## Executor -The [`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 [`Executor`](upsource:///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 _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. @@ -27,24 +27,24 @@ As a plugin developer, you normally don't need to implement the `Executor` inter The `RunProfileState` interface comes up in every run configuration implementation as the return value `RunProfile.getState()`. It describes a process which is ready to be started and holds the information like the command line, current working directory, and environment variables for the process to be started. (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://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://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://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. +The standard base class used as implementation of `RunProfileState` is [`CommandLineState`](upsource:///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`](upsource:///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`](upsource:///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://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. +Alternatively, if the process you need to run is a JVM-based one, you can use the [`JavaCommandLineState`](upsource:///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://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://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. +To monitor the execution of a process and capture its output, the [`OSProcessHandler`](upsource:///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`](upsource:///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 If you're using `CommandLineState`, a console view will be automatically created and attached to the output of the process. Alternatively, you can arrange this yourself: -* `TextConsoleBuilderFactory.createBuilder(project).getConsole()` creates a [`ConsoleView`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/ui/ConsoleView.java) instance +* `TextConsoleBuilderFactory.createBuilder(project).getConsole()` creates a [`ConsoleView`](upsource:///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://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. +If the process you're running uses ANSI escape codes to color its output, the [`ColoredProcessHandler`](upsource:///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://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()`. +Console [filters](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/filters/RegexpFilter.java) and [`UrlFilter`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/filters/UrlFilter.java). +Two common filter implementations you may want to reuse are [`RegexpFilter`](upsource:///platform/lang-api/src/com/intellij/execution/filters/RegexpFilter.java) and [`UrlFilter`](upsource:///platform/lang-api/src/com/intellij/execution/filters/UrlFilter.java). ## Starting a run configuration from code diff --git a/basics/run_configurations/run_configuration_management.md b/basics/run_configurations/run_configuration_management.md index 0c55e82384d..0a9cca44b03 100644 --- a/basics/run_configurations/run_configuration_management.md +++ b/basics/run_configurations/run_configuration_management.md @@ -9,25 +9,25 @@ This document describes main classes to work with run configurations and common ## Configuration type -The starting point for implementing any run configuration type is the [`ConfigurationType`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) interface. The list of available configuration types is shown when a user opens the _'Edit run configurations'_ dialog and executes _'Add'_ action: +The starting point for implementing any run configuration type is the [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) interface. The list of available configuration types is shown when a user opens the _'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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) and registered like below: +Every type there is represented as an instance of [`ConfigurationType`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) and registered like below: ```xml ``` -The easiest way to implement this interface is to use 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. +The easiest way to implement this interface is to use the [`ConfigurationTypeBase`](upsource:///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. ## Configuration factory -All run configurations are created by the [`ConfigurationFactory`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) registered for a 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) `ConfigurationFactory`: +All run configurations are created by the [`ConfigurationFactory`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) registered for a 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) `ConfigurationFactory`: ![Configuration Factory](/basics/img/create-3.png) -The key API of [`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. This method is called once per project to create the template run configuration. +The key API of [`ConfigurationFactory`](upsource:///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. This method is called once per project to create the template run configuration. All real run configurations (loaded from the workspace or created by the user) are called by cloning the template through the [`ceateConfiguration`](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java#L39) method. @@ -35,7 +35,7 @@ You can customize additional aspects of your configuration factory by overriding ## Run configuration -The run configuration itself is represented by the [`RunConfiguration`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) interface. A _'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. +The run configuration itself is represented by the [`RunConfiguration`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) interface. A _'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: @@ -43,9 +43,9 @@ 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://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://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://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). +* [`RunConfigurationBase`](upsource:///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`](upsource:///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`](upsource:///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). ## Settings editor @@ -59,9 +59,9 @@ That common run configuration settings might be modified via: ## Persistence -That run configuration settings are persistent, i.e. they are stored at file system and loaded back on the IDE startup. That is performed via [`writeExternal()`](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java#L27) and [`readExternal()`](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java#L26) methods of [`RunConfiguration`](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) class correspondingly. +That run configuration settings are persistent, i.e. they are stored at file system and loaded back on the IDE startup. That is performed via [`writeExternal()`](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java#L27) and [`readExternal()`](https://github.com/JetBrains/intellij-community/blob/master/platform/util/src/com/intellij/openapi/util/JDOMExternalizable.java#L26) methods of [`RunConfiguration`](upsource:///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://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". +The actual configurations stored by the *IntelliJ Platform* are represented by instances of the [`RunnerAndConfigurationSettings`](upsource:///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: @@ -72,13 +72,13 @@ 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RefactoringListenerProvider.java) interface. +In order to support that, your run configuration needs to implement the [`RefactoringListenerProvider`](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/actions/RunConfigurationProducer.java) +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`](upsource:///platform/lang-api/src/com/intellij/execution/actions/RunConfigurationProducer.java) interface and to register it as `` in your `plugin.xml`. (Note that this API has been redesigned in IntelliJ IDEA 13; the old `RuntimeConfigurationProducer` is a much more confusing version of the same API). The two main methods that you need to implement are: @@ -87,4 +87,4 @@ The two main methods that you need to implement are: * `isConfigurationFromContext` checks if the specified configuration of your type was created from the specified context. 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java) as the base class. +[`LocatableConfigurationBase`](upsource:///platform/lang-api/src/com/intellij/execution/configurations/LocatableConfigurationBase.java) as the base class. diff --git a/basics/virtual_file_system.md b/basics/virtual_file_system.md index aef2a12b351..03729a48bbc 100644 --- a/basics/virtual_file_system.md +++ b/basics/virtual_file_system.md @@ -42,7 +42,7 @@ From the point of view of the caller, refresh operations can be either synchrono 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](/basics/architectural_overview/general_threading_rules.html) for more details on the threading model and read/write actions. -The same threading requirements also apply to functions like [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. +The same threading requirements also apply to functions like [LocalFileSystem.refreshAndFindFileByPath()](upsource:///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. If there is some code that needs to be executed after the refresh is complete, the code should be passed as a `postRunnable` parameter to one of the refresh methods: diff --git a/drafts/project_model.md b/drafts/project_model.md index a56e9d5cb22..c00d4bc7d87 100644 --- a/drafts/project_model.md +++ b/drafts/project_model.md @@ -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://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), +[project] (upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java), +[module] (upsource:///platform/core-api/src/com/intellij/openapi/module/Module.java), +[application] (upsource:///platform/core-api/src/com/intellij/openapi/application/Application.java), and -[component] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/components/ProjectComponent.java) +[component] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) +Use [ProjectFileIndex.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java), + [ModuleRootManager.java] (upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java), for example, an instance of -[ModuleFileIndex.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java) +[ModuleFileIndex.java] (upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java) can be obtained, which is analogical to the -[ProjectFileIndex.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) +[ProjectFileIndex.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-impl/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java) +[ModuleRootModificationUtil.java] (upsource:///platform/projectModel-impl/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java) and -[ProjectRootUtil.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-impl/src/com/intellij/openapi/projectRoots/impl/ProjectRootUtil.java) +[ProjectRootUtil.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) +[ProjectRootManager.java] (upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) like the following example shows `String projectSdk = ProjectRootManager.getInstance(project).getProjectSdk();` diff --git a/drafts/project_wizard/project_wizard.md b/drafts/project_wizard/project_wizard.md index b49e1ff2fa9..d7e41fd73df 100644 --- a/drafts/project_wizard/project_wizard.md +++ b/drafts/project_wizard/project_wizard.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java). +[ModuleType.java] (upsource:///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 `` 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) +[ModuleType.java] (upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) generic from -[ModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java). +[ModuleBuilder.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java) +[ModuleBuilder.java] (upsource:///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: @@ -51,22 +51,22 @@ Functionality which is mandatory to implement consists of: * Getting a module type `public abstract ModuleType getModuleType();` See -[JavaModuleBuilder.java] (https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java) +[JavaModuleBuilder.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java)) +[JavaModuleBuilder.java] ((upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java) +[JavaModuleBuilder.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java) +[ModuleBuilderListener.java] (upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java), +[ModuleWizardStep.java] (upsource:///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 diff --git a/reference_guide.md b/reference_guide.md index 430876ed8fb..b279d1fbc55 100644 --- a/reference_guide.md +++ b/reference_guide.md @@ -2,10 +2,7 @@ title: Architecture Reference Guide --- -This documentation section contains more in-depth explanation of different API components. -If you are not familiar with *IntelliJ Platform* API please refer to -[Basics](basics.md) -section. +This documentation section contains more in-depth explanation of different API components. If you are not familiar with the *IntelliJ Platform* API please refer to the [Basics](basics.md) section. * [Project Model](reference_guide/project_model.md) * [Project Wizard](reference_guide/project_wizard.md) @@ -16,4 +13,4 @@ section. * [Messaging Infrastructure](reference_guide/messaging_infrastructure.md) * [Multiple Carets](reference_guide/multiple_carets.md) * [Color Scheme Management](reference_guide/color_scheme_management.md) -* [User Interface Components](user_interface_components/user_interface_components.md) \ No newline at end of file +* [User Interface Components](user_interface_components/user_interface_components.md) diff --git a/reference_guide/custom_language_support/additional_minor_features.md b/reference_guide/custom_language_support/additional_minor_features.md index d35024d9c07..7b6261a04bf 100644 --- a/reference_guide/custom_language_support/additional_minor_features.md +++ b/reference_guide/custom_language_support/additional_minor_features.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/PairedBraceMatcher.java) +[PairedBraceMatcher](upsource:///platform/lang-api/src/com/intellij/lang/PairedBraceMatcher.java) interface and to return an array of brace pairs ( -[BracePair](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/BracePair.java) +[BracePair](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/folding/FoldingBuilder.java) +[FoldingBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/folding/FoldingDescriptor.java) +[FoldingDescriptor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Commenter.java) +[Commenter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesCommenter.java) +[Commenter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java). +[JoinLinesHandlerDelegate](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/JoinLinesHandlerDelegate.java). *Smart Enter* (e.g. autocomplete missing semicolon/parentheses) can be provided via -[SmartEnterProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java). +[SmartEnterProcessor](upsource:///platform/lang-api/src/com/intellij/codeInsight/editorActions/smartEnter/SmartEnterProcessor.java). *Naming suggestions* for Rename Refactoring can be provided via -[NameSuggestionProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/refactoring/rename/NameSuggestionProvider.java). +[NameSuggestionProvider](upsource:///platform/lang-api/src/com/intellij/refactoring/rename/NameSuggestionProvider.java). *Semantic highlight usages* (e.g. exit points) can be achieved using -[HighlightUsagesHandlerFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/codeInsight/highlighting/HighlightUsagesHandlerFactory.java). +[HighlightUsagesHandlerFactory](upsource:///platform/lang-impl/src/com/intellij/codeInsight/highlighting/HighlightUsagesHandlerFactory.java). *View \| Parameter Info* is provided via -[ParameterInfoHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/parameterInfo/ParameterInfoHandler.java) +[ParameterInfoHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java), +[TreeBasedStructureViewBuilder](upsource:///platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java), and additionally to provide an implementation of -[DeclarationRangeHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/hint/DeclarationRangeHandler.java) +[DeclarationRangeHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/spellchecker/src/com/intellij/spellchecker/tokenizer/SpellcheckingStrategy.java) +[SpellcheckingStrategy](upsource:///spellchecker/src/com/intellij/spellchecker/tokenizer/SpellcheckingStrategy.java) ) where you can return -[Tokenizer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/spellchecker/src/com/intellij/spellchecker/tokenizer/Tokenizer.java) +[Tokenizer](upsource:///spellchecker/src/com/intellij/spellchecker/tokenizer/Tokenizer.java) to use, possibly depending on the passed in -[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) (or `EMPTY_TOKENIZER` for no spellchecking). **New in IntelliJ IDEA 13**: user-configurable *reference injections* can be provided via `referenceInjector` extension point ( -[ReferenceInjector](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/injection/ReferenceInjector.java) +[ReferenceInjector](upsource:///platform/lang-api/src/com/intellij/psi/injection/ReferenceInjector.java) ) (IntelliLang plugin required). diff --git a/reference_guide/custom_language_support/code_completion.md b/reference_guide/custom_language_support/code_completion.md index 38f9a233952..cd2dac0ae4a 100644 --- a/reference_guide/custom_language_support/code_completion.md +++ b/reference_guide/custom_language_support/code_completion.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference.getVariants()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) instances or instances of the -[LookupElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java) +[LookupElement](upsource:///platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java) class. If a -[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java), +[PsiReference.resolve()](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java), and a different implementation of -[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) +[PsiScopeProcessor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java) +[CompletionContributor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/completion/CompletionContributor.java) +[CompletionContributor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java) +[LookupElement](upsource:///platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElement.java) interface. These instances are normally created through the -[LookupElementBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElementBuilder.java) +[LookupElementBuilder](upsource:///platform/lang-api/src/com/intellij/codeInsight/lookup/LookupElementBuilder.java) class. For every lookup element, you can specify the following attributes: diff --git a/reference_guide/custom_language_support/code_formatting.md b/reference_guide/custom_language_support/code_formatting.md index f45c813e1f7..6f2247f1b6b 100644 --- a/reference_guide/custom_language_support/code_formatting.md +++ b/reference_guide/custom_language_support/code_formatting.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/FormattingModelBuilder.java) + [FormattingModelBuilder](upsource:///platform/lang-api/src/com/intellij/formatting/FormattingModelBuilder.java) ), implemented by the plugin, provides a formatting model ( - [FormattingModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/FormattingModel.java) + [FormattingModel](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Block.java) + [Block](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Spacing.java) + [Spacing](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Wrap.java) + [Wrap](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/Alignment.java) + [Alignment](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/formatting/SpacingBuilder.java) +[SpacingBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/codeStyle/FileTypeIndentOptionsProvider.java) +[FileTypeIndentOptionsProvider](upsource:///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. @@ -74,5 +74,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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java) +[Rearranger](upsource:///platform/lang-api/src/com/intellij/psi/codeStyle/arrangement/Rearranger.java) and related for JavaDoc. diff --git a/reference_guide/custom_language_support/code_inspections_and_intentions.md b/reference_guide/custom_language_support/code_inspections_and_intentions.md index aeb46f953ab..31dcdf761e3 100644 --- a/reference_guide/custom_language_support/code_inspections_and_intentions.md +++ b/reference_guide/custom_language_support/code_inspections_and_intentions.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) +[LocalInspectionTool](upsource:///platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) class. The functionality of -[LocalInspectionTool](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) +[LocalInspectionTool](upsource:///platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) partially duplicates that of -[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java). +[Annotator](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java). The main differences are that -[LocalInspectionTool](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInspection/LocalInspectionTool.java) +[LocalInspectionTool](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java) +[Annotator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/codeInspection/TrailingSpacesInPropertyInspection.java) +[simple inspection](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java) +[IntentionAction](upsource:///platform/analysis-api/src/com/intellij/codeInsight/intention/IntentionAction.java) interface and to be registered using the `` bean in your *plugin.xml*. **Example:** A -[simple intention action](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/groovy/src/org/jetbrains/plugins/groovy/intentions/control/SplitIfIntention.java) +[simple intention action](upsource:///plugins/groovy/src/org/jetbrains/plugins/groovy/intentions/control/SplitIfIntention.java) for Groovy diff --git a/reference_guide/custom_language_support/documentation.md b/reference_guide/custom_language_support/documentation.md index 787922e58c1..e008a51cc8a 100644 --- a/reference_guide/custom_language_support/documentation.md +++ b/reference_guide/custom_language_support/documentation.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/documentation/DocumentationProvider.java) +[DocumentationProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/documentation/AbstractDocumentationProvider.java). +[AbstractDocumentationProvider](upsource:///platform/lang-api/src/com/intellij/lang/documentation/AbstractDocumentationProvider.java). **Example**: -[DocumentationProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java) +[DocumentationProvider](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesDocumentationProvider.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/) diff --git a/reference_guide/custom_language_support/find_usages.md b/reference_guide/custom_language_support/find_usages.md index 6498fdd107d..655a8f17c3c 100644 --- a/reference_guide/custom_language_support/find_usages.md +++ b/reference_guide/custom_language_support/find_usages.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) +[FindUsagesProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) +[PsiNamedElement](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) and -[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) interfaces. **Example**: Implementation of -[FindUsagesProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/findUsages/PropertiesFindUsagesProvider.java) +[FindUsagesProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/WordsScanner.java) + [WordsScanner](upsource:///platform/indexing-api/src/com/intellij/lang/cacheBuilder/WordsScanner.java) implementation returned from - [FindUsagesProvider.getWordsScanner()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java), + [FindUsagesProvider.getWordsScanner()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java) + [DefaultWordsScanner](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) + [PsiNamedElement](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) or a - [PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) + [PsiReference](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) which resolves to a - [PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java). + [PsiNamedElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) + [PsiNamedElement.getName()](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) method. Also, if the text range of the - [PsiNamedElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) + [PsiNamedElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) + [PsiNamedElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java), + [PsiNamedElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) + [FindUsagesProvider.canFindUsagesFor()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) + [FindUsagesProvider.getType()](upsource:///platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) and - [FindUsagesProvider.getDescriptiveName()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) + [FindUsagesProvider.getDescriptiveName()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) + [PsiReference](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/findUsages/FindUsagesProvider.java) +[FindUsagesProvider.getNodeText()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/ElementDescriptionProvider.java) +[ElementDescriptionProvider](upsource:///platform/core-api/src/com/intellij/psi/ElementDescriptionProvider.java) interface. The -[ElementDescriptionLocation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/ElementDescriptionLocation.java) +[ElementDescriptionLocation](upsource:///platform/core-api/src/com/intellij/psi/ElementDescriptionLocation.java) passed to the provider in this case will be an instance of -[UsageViewLongNameLocation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/usageView/UsageViewLongNameLocation.java). +[UsageViewLongNameLocation](upsource:///platform/lang-impl/src/com/intellij/usageView/UsageViewLongNameLocation.java). **Example:** -[ElementDescriptionProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesDescriptionProvider.java) +[ElementDescriptionProvider](upsource:///plugins/properties/src/com/intellij/lang/properties/PropertiesDescriptionProvider.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/) diff --git a/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md b/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md index 54582f9dbd9..c7e4cd65469 100644 --- a/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md +++ b/reference_guide/custom_language_support/go_to_class_and_go_to_symbol.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/navigation/ChooseByNameContributor.java) +[ChooseByNameContributor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/navigation/NavigationItem.java) +[NavigationItem](upsource:///platform/core-api/src/com/intellij/navigation/NavigationItem.java) instances (typically -[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///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. diff --git a/reference_guide/custom_language_support/implementing_lexer.md b/reference_guide/custom_language_support/implementing_lexer.md index 6559102f151..9e6098d47cb 100644 --- a/reference_guide/custom_language_support/implementing_lexer.md +++ b/reference_guide/custom_language_support/implementing_lexer.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java) interface. +[Lexer](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighterFactory.java) + [SyntaxHighlighterFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java), + [ParserDefinition.createLexer()](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java), and the - [ParserDefinition](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java) + [ParserDefinition](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-api/src/com/intellij/lang/cacheBuilder/DefaultWordsScanner.java) + [DefaultWordsScanner](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-impl/src/com/intellij/lang/java/lexer/JavaLexer.java) +[Java lexer](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java). +[Lexer.getState()](upsource:///platform/core-api/src/com/intellij/lexer/Lexer.java). That state will be passed to the -[Lexer.start()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/Lexer.java) +[Lexer.start()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexLexer.java) +[FlexLexer](upsource:///platform/core-api/src/com/intellij/lexer/FlexLexer.java) and -[FlexAdapter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexAdapter.java) +[FlexAdapter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lexer/FlexAdapter.java). +[FlexAdapter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java). +[IElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/TokenType.java) +[TokenType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java) +[IElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java) +[IElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/parsing/PropertiesTokenTypes.java) +[Token types](upsource:///plugins/properties/properties-psi-api/src/com/intellij/lang/properties/parsing/PropertiesTokenTypes.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java) +[ILazyParseableElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java). +[ILazyParseableElementType.parseContents()](upsource:///platform/core-api/src/com/intellij/psi/tree/ILazyParseableElementType.java). diff --git a/reference_guide/custom_language_support/implementing_parser_and_psi.md b/reference_guide/custom_language_support/implementing_parser_and_psi.md index 9fccb38b195..e99a034ae56 100644 --- a/reference_guide/custom_language_support/implementing_parser_and_psi.md +++ b/reference_guide/custom_language_support/implementing_parser_and_psi.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ASTNode.java) +[ASTNode](upsource:///platform/core-api/src/com/intellij/lang/ASTNode.java) class. Each AST node has an associated element type -[IElementType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IElementType.java) +[IElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/tree/IFileElementType.java) +[IFileElementType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) interface and are created by the language plugin in the -[ParserDefinition.createElement()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java) +[ParserDefinition.createElement()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFile.java) +[PsiFile](upsource:///platform/core-api/src/com/intellij/psi/PsiFile.java) interface, and is created in the -[ParserDefinition.createFile()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java) +[ParserDefinition.createFile()](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java) method. **Example**: -[ParserDefinition](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParserDefinition.java) +[ParserDefinition](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParserDefinition.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-impl/src/com/intellij/extapi/psi/PsiFileBase.java), +[PsiFileBase](upsource:///platform/core-impl/src/com/intellij/extapi/psi/PsiFileBase.java), the base implementation of -[PsiFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiFile.java), +[PsiFile](upsource:///platform/core-api/src/com/intellij/psi/PsiFile.java), and -[ASTWrapperPsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java), +[ASTWrapperPsiElement](upsource:///platform/core-impl/src/com/intellij/extapi/psi/ASTWrapperPsiElement.java), the base implementation of -[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java), +[PsiElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiParser.java) +[PsiParser](upsource:///platform/core-api/src/com/intellij/lang/PsiParser.java) interface, returned from -[ParserDefinition.createParser()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java). +[ParserDefinition.createParser()](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java). The parser receives an instance of the -[PsiBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder.getTokenType()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/parsing/PropertiesParser.java) +[PsiParser](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder.Marker](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java). +[PsiBuilder.Marker.done()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder.Marker.precede()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java) +[ParserDefinition](upsource:///platform/core-api/src/com/intellij/lang/ParserDefinition.java) class. -[PsiBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiParser.java), +[PsiParser](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/ParserDefinition.java) +[ParserDefinition.getCommentTokens()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) +[PsiNamedElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-api/src/com/intellij/psi/util/PsiUtil.java) +[PsiUtil](upsource:///java/java-psi-api/src/com/intellij/psi/util/PsiUtil.java) and -[PsiTreeUtil](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/util/PsiTreeUtil.java) +[PsiTreeUtil](upsource:///platform/core-api/src/com/intellij/psi/util/PsiTreeUtil.java) classes. A very helpful tool for debugging the PSI implementation is the diff --git a/reference_guide/custom_language_support/references_and_resolve.md b/reference_guide/custom_language_support/references_and_resolve.md index d3fd04011ff..2930094971c 100644 --- a/reference_guide/custom_language_support/references_and_resolve.md +++ b/reference_guide/custom_language_support/references_and_resolve.md @@ -7,33 +7,33 @@ Resolving references gives users the ability to navigate from a PSI element usag This feature is needed in order to support the `Go to Declaration` action invoked by **Ctrl-B** and **Ctrl-Click**, and it is a prerequisite for implementing the `Find Usages` action, the `Rename` refactoring and code completion. All PSI elements which work as references (for which the `Go to Declaration` action applies) need to implement the -[PsiElement.getReference()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement.getReference()](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) method and to return a -[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) implementation from that method. The -[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) interface can be implemented by the same class as -[PsiElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java), +[PsiElement](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement.getReferences()](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) and return the references as an array. The main method of the -[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference](upsource:///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, should it point 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 are possible (for example, performing the tree walk only if the element text is equal to the text of the reference). **Example**: -[Reference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/ResourceBundleReference.java) +[Reference](upsource:///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](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) interface and the -[PsiElement.processDeclarations()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiScopeProcessor](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) interface and the +[PsiElement.processDeclarations()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) + [PsiScopeProcessor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) + [PsiScopeProcessor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java) + [FilenameIndex.getFilesByName()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java) + [FileIndex](upsource:///platform/indexing-impl/src/com/intellij/psi/search/FilenameIndex.java) interface obtained from - [ProjectRootManager.getFileIndex()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) + [ProjectRootManager.getFileIndex()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) + [PsiScopeProcessor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) + [PsiScopeProcessor](upsource:///platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java) to its child elements. An extension of the -[PsiReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference](upsource:///platform/core-api/src/com/intellij/psi/PsiReference.java) interface, which allows a reference to resolve to multiple targets, is the -[PsiPolyVariantReference](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiPolyVariantReference.java) +[PsiPolyVariantReference](upsource:///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 a navigation target. The implementation of `multiResolve()` can be also based on -[PsiScopeProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/scope/PsiScopeProcessor.java), +[PsiScopeProcessor](upsource:///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 that can be resolved by the language plugin. diff --git a/reference_guide/custom_language_support/registering_file_type.md b/reference_guide/custom_language_support/registering_file_type.md index dda6bb51f8c..be5123ba342 100644 --- a/reference_guide/custom_language_support/registering_file_type.md +++ b/reference_guide/custom_language_support/registering_file_type.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java), +[LanguageFileType](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java), which passes a -[Language](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/Language.java) +[Language](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java) +[FileTypeFactory](upsource:///platform/platform-api/src/com/intellij/openapi/fileTypes/FileTypeFactory.java) interface, which is registered via the `com.intellij.fileTypeFactory` -[platform extension point](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml). +[platform extension point](upsource:///platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml). **Example**: -[LanguageFileType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) +[LanguageFileType](upsource:///platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) implementation in -[Properties language plugin](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesFileType.java) +[Properties language plugin](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/fileTypes/LanguageFileType.java) +[LanguageFileType.getIcon()](upsource:///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. diff --git a/reference_guide/custom_language_support/rename_refactoring.md b/reference_guide/custom_language_support/rename_refactoring.md index e682b1e01a0..12e2566de9c 100644 --- a/reference_guide/custom_language_support/rename_refactoring.md +++ b/reference_guide/custom_language_support/rename_refactoring.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiNamedElement.java) +[PsiNamedElement.setName()](upsource:///platform/core-api/src/com/intellij/psi/PsiNamedElement.java) is called for the renamed element, and -[PsiReference.handleElementRename()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiReference.java) +[PsiReference.handleElementRename()](upsource:///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,34 +22,34 @@ implementation for a Another interface related to the Rename refactoring is -[NamesValidator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java). +[NamesValidator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java) +[NamesValidator](upsource:///platform/lang-api/src/com/intellij/lang/refactoring/NamesValidator.java) are registered in the `com.intellij.lang.namesValidator` extension point. **Example**: -[NamesValidator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/PropertiesNamesValidator.java) +[NamesValidator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/refactoring/rename/RenameHandler.java) +[RenameHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) +[PsiElement](upsource:///platform/core-api/src/com/intellij/psi/PsiElement.java) at all. **Example**: -[RenameHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/ResourceBundleFromEditorRenameHandler.java) +[RenameHandler](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/rename/ResourceBundleFromEditorRenameHandler.java) for renaming a resource bundle in the [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties) 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/refactoring/rename/RenamePsiElementProcessor.java) +[RenamePsiElementProcessor](upsource:///platform/lang-impl/src/com/intellij/refactoring/rename/RenamePsiElementProcessor.java) interface. This allows you to: @@ -64,6 +64,6 @@ This allows you to: * etc. **Example**: -[RenamePsiElementProcessor](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/rename/RenamePropertyProcessor.java) +[RenamePsiElementProcessor](upsource:///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) diff --git a/reference_guide/custom_language_support/safe_delete_refactoring.md b/reference_guide/custom_language_support/safe_delete_refactoring.md index 15de4a3bb1d..110a5f01e5c 100644 --- a/reference_guide/custom_language_support/safe_delete_refactoring.md +++ b/reference_guide/custom_language_support/safe_delete_refactoring.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/refactoring/RefactoringSupportProvider.java) + [RefactoringSupportProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiElement.java) + [PsiElement](upsource:///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,6 +29,6 @@ This is done by implementing the `SafeDeleteProcessorDelegate` interface. **Example**: -[SafeDeleteProcessorDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java) +[SafeDeleteProcessorDelegate](upsource:///plugins/properties/src/com/intellij/lang/properties/refactoring/PropertiesFilesSafeDeleteProcessor.java) implementation for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties) diff --git a/reference_guide/custom_language_support/structure_view.md b/reference_guide/custom_language_support/structure_view.md index 173e8724620..19a11b94625 100644 --- a/reference_guide/custom_language_support/structure_view.md +++ b/reference_guide/custom_language_support/structure_view.md @@ -4,41 +4,41 @@ 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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java) +[StructureView](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java) +[StructureView](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/lang/PsiStructureViewFactory.java) +[PsiStructureViewFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/lang/properties/structureView/PropertiesStructureViewBuilderFactory.java) +[PsiStructureViewFactory](upsource:///plugins/properties/src/com/intellij/lang/properties/structureView/PropertiesStructureViewBuilderFactory.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties) To reuse the *IntelliJ Platform* implementation of the -[StructureView](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java), +[StructureView](upsource:///platform/structure-view-api/src/com/intellij/ide/structureView/StructureView.java), the plugin returns a -[TreeBasedStructureViewBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TreeBasedStructureViewBuilder.java) +[TreeBasedStructureViewBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/TextEditorBasedStructureViewModel.java), +[TextEditorBasedStructureViewModel](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesFileStructureViewModel.java) +[StructureViewModel](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesFileStructureViewModel.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties) The main method to override is `getRoot()`, which returns the instance of a class implementing the -[StructureViewTreeElement](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/structure-view-api/src/com/intellij/ide/structureView/StructureViewTreeElement.java) +[StructureViewTreeElement](upsource:///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. @@ -52,6 +52,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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesStructureViewElement.java) +[StructureViewElement](upsource:///plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/structureView/PropertiesStructureViewElement.java) for [Properties language plugin](https://github.com/JetBrains/intellij-community/tree/master/plugins/properties/) diff --git a/reference_guide/custom_language_support/surround_with.md b/reference_guide/custom_language_support/surround_with.md index a4168b23e9a..53405fb0905 100644 --- a/reference_guide/custom_language_support/surround_with.md +++ b/reference_guide/custom_language_support/surround_with.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/surroundWith/SurroundDescriptor.java) +[SurroundDescriptor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/lang/surroundWith/Surrounder.java) +[Surrounder](upsource:///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. diff --git a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md b/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md index 53edee9eec4..8f0c3d222cd 100644 --- a/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md +++ b/reference_guide/custom_language_support/syntax_highlighting_and_error_highlighting.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java). +[TextAttributesKey](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) +[TextAttributesKey](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) +[TextAttributesKey](upsource:///platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) to specific attributes used in an editor is defined by the -[EditorColorsScheme](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/colors/EditorColorsScheme.java) +[EditorColorsScheme](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) +[TextAttributesKey](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java) +[SyntaxHighlighter](upsource:///platform/editor-ui-api/src/com/intellij/openapi/fileTypes/SyntaxHighlighter.java) interface. The syntax highlighter returns the -[TextAttributesKey](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) +[TextAttributesKey](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) +[TextAttributesKey](upsource:///platform/core-api/src/com/intellij/openapi/editor/colors/TextAttributesKey.java) for bad characters -[HighlighterColors.BAD_CHARACTER](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java) +[HighlighterColors.BAD_CHARACTER](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/HighlighterColors.java) can be used. **Example:** -[SyntaxHighlighter](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-api/src/com/intellij/lang/properties/PropertiesHighlighter.java) +[SyntaxHighlighter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/lang/PsiBuilder.java) +[PsiBuilder.error()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotator.java) +[Annotator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) +[AnnotationHolder](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) object passed to it, and optionally calls `registerFix()` on the returned -[Annotation](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java) +[Annotation](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) +[AnnotationHolder.createInfoAnnotation()](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) with an empty message and then call -[Annotation.setTextAttributes()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java) +[Annotation.setTextAttributes()](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/Annotation.java) to specify the text attributes key for the highlighting. **Example:** -[Annotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/properties-psi-impl/src/com/intellij/lang/properties/PropertiesAnnotator.java) +[Annotator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java) +[ExternalAnnotator](upsource:///platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java) interface and register it in `com.intellij.externalAnnotator` extension point. The -[ExternalAnnotator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/ExternalAnnotator.java) +[ExternalAnnotator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/analysis-api/src/com/intellij/lang/annotation/AnnotationHolder.java) +[AnnotationHolder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java) +[ColorSettingPage](upsource:///platform/lang-api/src/com/intellij/openapi/options/colors/ColorSettingsPage.java) and register it in the `com.intellij.colorSettingsPage` extension point. **Example**: -[ColorSettingsPage](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/plugins/properties/src/com/intellij/openapi/options/colors/pages/PropertiesColorsPage.java) +[ColorSettingsPage](upsource:///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/) diff --git a/reference_guide/messaging_infrastructure.md b/reference_guide/messaging_infrastructure.md index aeac5c57d91..859b93014e8 100644 --- a/reference_guide/messaging_infrastructure.md +++ b/reference_guide/messaging_infrastructure.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/openapi/Disposable.java) +[Disposable](upsource:///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://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); +[Application](upsource:///platform/core-api/src/com/intellij/openapi/application/Application.java), +[Project](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java); * number of public topics are used by *IntelliJ IDEA*, e.g. -[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) +[AppTopics](upsource:///platform/platform-api/src/com/intellij/AppTopics.java), +[ProjectTopics](upsource:///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; diff --git a/reference_guide/multiple_carets.md b/reference_guide/multiple_carets.md index fe4837b8202..a29fe09a574 100644 --- a/reference_guide/multiple_carets.md +++ b/reference_guide/multiple_carets.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) +[CaretModel](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) interface, some changes also have been made in -[SelectionModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java) +[SelectionModel](upsource:///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://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. +[EditorActionHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) +[TypedActionHandler](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) and -[TypedHandlerDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) +[TypedHandlerDelegate](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/EditorModificationUtil.java). +[EditorModificationUtil](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java). +* [TypedAction](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java). -* [XmlGtTypedHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java). +* [XmlGtTypedHandler](upsource:///xml/impl/src/com/intellij/codeInsight/editorActions/XmlGtTypedHandler.java). ----------- **Note**: Starting from IDEA 14, -[TypedHandlerDelegate](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/editorActions/TypedHandlerDelegate.java) +[TypedHandlerDelegate](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) +[TypedActionHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/codeInsight/actions/CodeInsightAction.java) will work for primary caret only. +[CodeInsightAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-impl/src/com/intellij/codeInsight/actions/MultiCaretCodeInsightAction.java) +[MultiCaretCodeInsightAction](upsource:///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. diff --git a/reference_guide/project_model.md b/reference_guide/project_model.md index 09229be6d40..65cf6130e19 100644 --- a/reference_guide/project_model.md +++ b/reference_guide/project_model.md @@ -2,37 +2,18 @@ title: Project Model. Roots and Libraries. Configuring Project from Code. --- -This section considers internal architecture *IntelliJ Platform* projects -and gives overview for classes and packages of the API used to manipulate with projects and their components, such as modules, facets, libraries, SDK. -For general information about the concept of a projects and concepts related to it, refer to -[Project](http://www.jetbrains.com/idea/help/project.html), -[Module](http://www.jetbrains.com/idea/help/module.html), -[Library](http://www.jetbrains.com/idea/help/library.html), -and -[Facet](http://www.jetbrains.com/idea/help/facet.html) -in -[IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/intellij-idea.html). +This section considers the internal architecture of *IntelliJ Platform* projects and gives an overview for classes and packages of the API used to manipulate with projects and their components, such as modules, facets, libraries, SDK. +For general information about the concept of a projects and concepts related to it, refer to [Project](http://www.jetbrains.com/idea/help/project.html), [Module](http://www.jetbrains.com/idea/help/module.html), [Library](http://www.jetbrains.com/idea/help/library.html), and [Facet](http://www.jetbrains.com/idea/help/facet.html) in the [IntelliJ IDEA Web Help](https://www.jetbrains.com/idea/help/intellij-idea.html). ## Project Structure -A project consists of one or several modules. -Each module includes the plugin source code and so called order entries that refer to SDK and libraries the module uses. -By default, all modules uses the project SDK. -In addition, a module can optionally have a set of facets. -This document explains how you can explore and change the structure of projects using API. +A project consists of one or several modules. Each module includes source code and so called order entries that refer to SDK and libraries the module uses. By default, all modules use the project SDK. In addition, a module can optionally have a set of facets. This document explains how you can explore and change the structure of projects using API. Main project structure components are: -* [Project](/reference_guide/project_model/project.md) - itself - +* [Project](/reference_guide/project_model/project.md) * [Module](/reference_guide/project_model/module.md) - * [SDK](/reference_guide/project_model/sdk.md) - * [Library](/reference_guide/project_model/library.md) - * [Facet](/reference_guide/project_model/facet.md) - - diff --git a/reference_guide/project_model/module.md b/reference_guide/project_model/module.md index c100b4f2a96..0a127a78e9c 100644 --- a/reference_guide/project_model/module.md +++ b/reference_guide/project_model/module.md @@ -1,32 +1,24 @@ --- title: Module --- -A module is a discrete unit of functionality that can be run, tested, and debugged independently. -Modules includes such things as source code, build scripts, unit tests, deployment descriptors, etc. -In the project, each module can use a specific SDK or inherit SDK defined on the project level (see the [SDK](sdk.md) section later in this document). -A module can depend on other modules of the project. - -## Getting Current Module -To determine the module in the project in question to which the specified `VirtualFile` belongs use `ModuleUtilCore#findModuleForFile`. -Use `ModuleUtilCore#findModuleForPsiElement` to find the module for a given `PsiElement`. - -## Accessing Module Roots -Information about module roots can be accessed via the class -[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://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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) -but in the scope of a module + +A _module_ is a discrete unit of functionality that can be run, tested, and debugged independently. Modules includes such things as source code, build scripts, unit tests, deployment descriptors, etc. In the project, each module can use a specific SDK or inherit the SDK defined on the project level (see the [SDK](sdk.md) section later in this guide). A module can depend on other modules of the project. + +## Getting the current module + +To determine the module in the project in question to which the specified `VirtualFile` belongs use `ModuleUtilCore#findModuleForFile`. Use `ModuleUtilCore#findModuleForPsiElement` to find the module for a given `PsiElement`. + +## Accessing module roots + +Information about module roots can be accessed via the class [ModuleRootManager.java](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java), for example, an instance of [ModuleFileIndex.java](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleFileIndex.java) can be obtained, which is similar to the [ProjectFileIndex.java](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) but in the scope of a module. ```java ModuleRootManager.getInstance(currentModule).getFileIndex() ``` -### Checking Belonging to a Module Source Root +## Checking belonging to a module source root -To check if a virtual file or directory belongs to a module source root, use the `ProjectFileIndex.getSourceRootForFile` method. -This method returns null if the file or directory does not belong to any source root of modules in the project. +To check if a virtual file or directory belongs to a module source root, use the `ProjectFileIndex.getSourceRootForFile` method. This method returns null if the file or directory does not belong to any source root of modules in the project. ```java VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project).getFileIndex().getSourceRootForFile(virtualFileOrDirectory); diff --git a/reference_guide/project_model/project.md b/reference_guide/project_model/project.md index 281c2193fa4..6de24bde595 100644 --- a/reference_guide/project_model/project.md +++ b/reference_guide/project_model/project.md @@ -2,82 +2,46 @@ title: Project --- -In IntelliJ IDEA, a project encapsulates all your source code, libraries, build instructions into a single organizational unit. -Everything you do in IntelliJ IDEA, is done within the context of a project. -A project defines some collections referred to as modules and libraries. -Depending on the logical and functional requirements to the project, you can create a single-module or a multi-module project. +In *IntelliJ IDEA*, a project encapsulates all your source code, libraries, build instructions into a single organizational unit. Everything you do in *IntelliJ IDEA*, is done within the context of a project. A project defines some collections referred to as modules and libraries. Depending on the logical and functional requirements to the project, you can create a single-module or a multi-module project. -## Working with Projects +## Working with projects -*IntelliJ Platform* stores the project configuration data in XML files. -The list of those files depends on the plugin -[project](http://www.jetbrains.com/idea/help/project.html) -format. -For file-based format projects, the information core to the project itself (e.g. location of the component modules, compiler settings, etc.) is stored in the <%project name%>.IPR file. -The information about modules the project includes is stored in <%module name%>.IML files. -Module files are created for each module. +The *IntelliJ Platform* stores the project configuration data in XML files. The list of those files depends on the plugin [project](http://www.jetbrains.com/idea/help/project.html) format. -For directory-based format projects, the project and workspace settings are stored in a number of XML files under the <%Project home directory%>/.idea directory. -Each XML file is responsible for its own set of settings and can be recognized by its name: projectCodeStyle.xml, encodings.xml, vcs.xml etc. -As for the file-based format projects, .IML files describe modules. +For file based format projects, the information core to the project itself (e.g. location of the component modules, compiler settings, etc.) is stored in the `%project_name%.ipr` file. The information about modules the project includes is stored in `%module_name%.iml` files. Module files are created for each module. -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://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://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. +For directory based format projects, the project and workspace settings are stored in a number of XML files under the `%project_home_directory%/.idea` directory. Each XML file is responsible for its own set of settings and can be recognized by its name: `projectCodeStyle.xml`, `encodings.xml`, `vcs.xml` etc. 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](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java), [module](upsource:///platform/core-api/src/com/intellij/openapi/module/Module.java), [application](upsource:///platform/core-api/src/com/intellij/openapi/application/Application.java), and [component](upsource:///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. -### Finding Source Roots - -To get an array of all the source roots for a project use -`ProjectRootManager.getContentSourceRoots()` -method like this code snippet shows: +### Finding source roots +To get an array of all the source roots for a project use `ProjectRootManager.getContentSourceRoots()` method like this code snippet shows: ```java VirtualFile[] vFiles = ProjectRootManager.getInstance(project).getContentSourceRoots(); ``` +### Checking if a file belongs to a project -### Checking if File Belongs to a Project - -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. +Use [ProjectFileIndex.java](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) to get this information. ### Getting an Instance of the ProjectFileIndex Interface -Use the ProjectRootManager.getFileIndex() method. For example: +Use the `ProjectRootManager.getFileIndex()` method. For example: ```java ProjectFileIndex projectFileIndex = ProjectRootManager.getInstance(project).getFileIndex(); ``` -Note that this method returns `null` if the file does not belong to any module. -You can also use the `ProjectFileIndex.getContentRootForFile()` method to get the module content root to which the specified file or directory belongs: +Note that this method returns `null` if the file does not belong to any module. You can also use the `ProjectFileIndex.getContentRootForFile()` method to get the module content root to which the specified file or directory belongs: ```java VirtualFile moduleContentRoot = ProjectRootManager.getInstance(project).getFileIndex().getContentRootForFile(virtualFileOrDirectory); -``` +``` ## Changing the project structure -Utility classes which can be used for modifying a project structure can be found in the package -[projectModel-impl.openapi](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-impl/src/com/intellij/openapi). -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java) -and -[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) -of on-the-fly project structure modification to learn how it can be implemented. +Utility classes which can be used for modifying a project structure can be found in the package [projectModel-impl.openapi](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-impl/src/com/intellij/openapi). 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](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModificationUtil.java) and [ProjectRootUtil.java](upsource:///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) of on-the-fly project structure modification to learn how it can be implemented. diff --git a/reference_guide/project_model/sdk.md b/reference_guide/project_model/sdk.md index 12506b20753..c83dfe7b565 100644 --- a/reference_guide/project_model/sdk.md +++ b/reference_guide/project_model/sdk.md @@ -2,51 +2,40 @@ title: SDK --- -Every project uses a Software Development Kit (SDK). -For Java projects, SDK is referred to as JDK (Java Development Kit). -SDK determines which API library is used to build the project. If your project is multi-module, the project SDK by default is common for all modules within the project. -Optionally, you can configure individual SDK for each module. -For more information about SDKs, see -[SDK](https://www.jetbrains.com/idea/help/sdk.html) -and -[Configuring Global, Project and Module SDKs](https://www.jetbrains.com/idea/help/configuring-global-project-and-module-sdks.html) -in IntelliJ IDEA Web Help. - -### Getting Project SDK Information - -Main information about the project SDK can be accessed via -[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 +Every project uses a Software Development Kit (SDK). For Java projects, the SDK is referred to as the JDK (Java Development Kit). The SDK determines which API library is used to build the project. If your project is multi-module, the project SDK by default is common for all modules within the project. Optionally, you can configure individual SDKs for each module. For more information about SDKs, see [SDK](https://www.jetbrains.com/idea/help/sdk.html) and [Configuring Global, Project and Module SDKs](https://www.jetbrains.com/idea/help/configuring-global-project-and-module-sdks.html) in IntelliJ IDEA Web Help. + +## Getting project SDK information + +Main information about the project SDK can be accessed via [ProjectRootManager.java](upsource:///platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) like the following example shows ```java String projectSdk = ProjectRootManager.getInstance(project).getProjectSdk(); ``` -### Getting And Setting Project SDK Attributes +## Getting and setting project SDK attributes -* To get the project-level SDK +* To get the project level SDK ```java Sdk projectSDK = ProjectRootManager.getInstance(project).getProjectSdk(); ``` -* To get the project-level SDK name: +* To get the project level SDK name: ```java String projectSDKName = ProjectRootManager.getInstance(project).getProjectSdkName(); ``` -* To set the project-level SDK: +* To set the project level SDK: ```java ProjectRootManager.getInstance(project).setProjectSdk(Sdk jdk); ``` -* To set the project-level SDK name: +* To set the project level SDK name: ```java ProjectRootManager.getInstance(project).setProjectSdkName(String name); ``` -See the following [code sample](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/project_model/src/com/intellij/tutorials/project/model/ProjectSdkAction.java) -to get more familiar with SDK manipulation tool set. +See the following [code sample](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/project_model/src/com/intellij/tutorials/project/model/ProjectSdkAction.java) to get more familiar with SDK manipulation tool set. diff --git a/reference_guide/project_wizard.md b/reference_guide/project_wizard.md index b5aec87d6d0..2861360e030 100644 --- a/reference_guide/project_wizard.md +++ b/reference_guide/project_wizard.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java). +[ModuleType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) +[ModuleType](upsource:///platform/lang-api/src/com/intellij/openapi/module/ModuleType.java) generic from -[ModuleBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java). +[ModuleBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilder.java) +[ModuleBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java) +[JavaModuleBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java) +[JavaModuleBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/projectWizard/JavaModuleBuilder.java) +[JavaModuleBuilder](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleBuilderListener.java) +[ModuleBuilderListener](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java), +[ModuleWizardStep](upsource:///platform/lang-api/src/com/intellij/ide/util/projectWizard/ModuleWizardStep.java), which has two methods to be overridden: * ```java diff --git a/reference_guide/vcs_integration_for_plugins.md b/reference_guide/vcs_integration_for_plugins.md index 982ad8be6ee..d52e95784d3 100644 --- a/reference_guide/vcs_integration_for_plugins.md +++ b/reference_guide/vcs_integration_for_plugins.md @@ -12,48 +12,48 @@ The VCS API was significantly refactored in version 6.0, and this document does ### FilePath -A [FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) +A [FilePath](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java), +[VirtualFile](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java), a -[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) +[FilePath](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) +[FilePath](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) +[FilePath](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) caches the -[VirtualFile](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) +[VirtualFile](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java), +[FilePath](upsource:///platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java), the -[VcsContextFactory](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/actions/VcsContextFactory.java) +[VcsContextFactory](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/actions/VcsContextFactory.java) API is used. It can be accessed as`PeerFactory.getInstance().getVcsContextFactory()` -[FilePath](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/FilePath.java) +[FilePath](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java) +[VcsRevisionNumber](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/history/VcsRevisionNumber.java). +[VcsRevisionNumber](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/ContentRevision.java) +[ContentRevision](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/CurrentContentRevision.java). +[CurrentContentRevision](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/CurrentContentRevision.java). ### FileStatus A -[FileStatus](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/vcs/FileStatus.java) +[FileStatus](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) +[Change](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) +[Change](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/vcs-api-core/src/com/intellij/openapi/vcs/changes/Change.java) +[Change](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeList.java) +[ChangeList](upsource:///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://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. +* [LocalChangeList](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java) +* [CommittedChangeList](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/versionBrowser/CommittedChangeList.java) + [CommittedChangeList](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/AbstractVcs.java). +[AbstractVcs.getChangeProvider()](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/AbstractVcs.java). The ChangeProvider works in tandem with -[VcsDirtyScopeManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java), +[VcsDirtyScopeManager](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java), which is a component in IntelliJ IDEA core. -[VcsDirtyScopeManager](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) +[VcsDirtyScopeManager](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) +[VcsDirtyScopeManager.fileDirty()](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java) or -[VcsDirtyScopeManager.dirDirtyRecursively()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScopeManager.java). +[VcsDirtyScopeManager.dirDirtyRecursively()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java), +[ChangeProvider.getChanges()](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java), along with a -[ChangelistBuilder](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangelistBuilder.java) +[ChangelistBuilder](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangelistBuilder.java) instance, which serves as a sink to which the -[ChangeProvider](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) +[ChangeProvider](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) +[ChangeProvider](upsource:///platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) can either iterate all files under the dirty scope using -[VcsDirtyScope.iterate()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/VcsDirtyScope.java), +[VcsDirtyScope.iterate()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/vcs-api/src/com/intellij/openapi/vcs/changes/ChangeProvider.java) +[ChangeProvider](upsource:///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. diff --git a/sdkdocs-template b/sdkdocs-template index 01b7879d2f2..6ae65c12104 160000 --- a/sdkdocs-template +++ b/sdkdocs-template @@ -1 +1 @@ -Subproject commit 01b7879d2f218b68b06f001ce1a8533e433c5360 +Subproject commit 6ae65c12104583089a3b98c326666f3b8c1f8019 diff --git a/tutorials/action_system/grouping_action.md b/tutorials/action_system/grouping_action.md index 13e6a466d27..2ab4419410a 100644 --- a/tutorials/action_system/grouping_action.md +++ b/tutorials/action_system/grouping_action.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) +[DefaultActionGroup.java](upsource:///platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) is a default implementations of -[ActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java) +[ActionGroup.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) +[DefaultActionGroup.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) +[DefaultActionGroup.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java). +[ActionGroup.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionGroup.java) +[ActionGroup.java](upsource:///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 `` attribute needs to be placed in the *`` [plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/register_actions/META-INF/plugin.xml). If `` attribute contains any static action definition an exception will be thrown. For statically defined group of action use -[DefaultActionGroup.java](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) +[DefaultActionGroup.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction.java](upsource:///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) diff --git a/tutorials/action_system/working_with_custom_actions.md b/tutorials/action_system/working_with_custom_actions.md index 1c8e5a6a211..411210783bd 100644 --- a/tutorials/action_system/working_with_custom_actions.md +++ b/tutorials/action_system/working_with_custom_actions.md @@ -4,7 +4,7 @@ title: 1. Working With Custom Actions An action is technically a class, derived from the -[AnAction](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java) +[AnActionEvent](upsource:///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. diff --git a/tutorials/editor_basics.md b/tutorials/editor_basics.md index 690ec5485b5..07dcec66969 100644 --- a/tutorials/editor_basics.md +++ b/tutorials/editor_basics.md @@ -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://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), +[Editor.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java), +[EditorImpl.java](upsource:///platform/platform-impl/src/com/intellij/openapi/editor/impl/EditorImpl.java). +[CommonDataKeys.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/CommonDataKeys.java), +[DataKey.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java) +[DataContext](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java) **Related topics:** [Action System](/tutorials/action_system.md) diff --git a/tutorials/editor_basics/coordinates_system.md b/tutorials/editor_basics/coordinates_system.md index c398c3f69b4..b42c8096364 100644 --- a/tutorials/editor_basics/coordinates_system.md +++ b/tutorials/editor_basics/coordinates_system.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java). +[caret model instance](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java) +[LogicalPosition.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java). +[VisualPosition.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java) +[VisualPosition.java](upsource:///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. diff --git a/tutorials/editor_basics/editor_events.md b/tutorials/editor_basics/editor_events.md index 9b401ba5bc5..cc2b67f8c29 100644 --- a/tutorials/editor_basics/editor_events.md +++ b/tutorials/editor_basics/editor_events.md @@ -11,14 +11,14 @@ The IntelliJ Platform SDK provides a set of callbacks for handling events relate ## 3.1. Handling keystrokes in the Editor To handle keystrokes and provide custom reactions interface -[TypedActionHandler](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java) +[TypedActionHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java): +[TypedActionHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java) +[TypedAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) +[EditorActionHandler.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java) +[EditorActionHandler](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/openapi/editor/actions/CloneCaretActionHandler.java). +[CloneCaretActionHandler](upsource:///platform/platform-impl/src/com/intellij/openapi/editor/actions/CloneCaretActionHandler.java). ```java public class EditorHandlerIllustration extends AnAction { diff --git a/tutorials/editor_basics/working_with_text.md b/tutorials/editor_basics/working_with_text.md index 9aea2000d1b..4e9e94aea0e 100644 --- a/tutorials/editor_basics/working_with_text.md +++ b/tutorials/editor_basics/working_with_text.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) +[AnAction.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java) +* If [DataContext](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java) object is available `final Editor editor = CommonDataKeys.EDITOR.getData(context);` -* If [ActionEvent](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java) +* If [ActionEvent](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java) +[SelectionModel](upsource:///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://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) +* [CaretModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java), +* [FoldingModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/FoldingModel.java), +* [IndentsModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/IndentsModel.java), +* [ScrollingModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java), +* [ScrollingModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/ScrollingModel.java), +* [SoftWrapModel.java](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/openapi/editor/Document.java) +[Document](upsource:///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. diff --git a/tutorials/framework.md b/tutorials/framework.md index ab6acb0de61..03141395663 100644 --- a/tutorials/framework.md +++ b/tutorials/framework.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java) +[FrameworkTypeEx](upsource:///java/idea-ui/src/com/intellij/framework/FrameworkTypeEx.java) class needs to be extended: diff --git a/tutorials/run_configurations.md b/tutorials/run_configurations.md index a106d3000a7..ca90c1d054b 100644 --- a/tutorials/run_configurations.md +++ b/tutorials/run_configurations.md @@ -31,7 +31,7 @@ Add new *configurationType* extension to the ## 2. Implement ConfigurationType Implement -[ConfigurationType](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationType.java) +[ConfigurationType](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/ConfigurationFactory.java) +[ConfigurationFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfigurationBase.java). +[RunConfigurationBase](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) +[RunConfiguration](upsource:///platform/lang-api/src/com/intellij/execution/configurations/RunConfiguration.java) interface. ```java diff --git a/tutorials/writing_tests_for_plugins/tests_prerequisites.md b/tutorials/writing_tests_for_plugins/tests_prerequisites.md index 14df19f57a7..36f334c433a 100644 --- a/tutorials/writing_tests_for_plugins/tests_prerequisites.md +++ b/tutorials/writing_tests_for_plugins/tests_prerequisites.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java). +[LightCodeInsightFixtureTestCase](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java) + > [LightCodeInsightFixtureTestCase](upsource:///java/testFramework/src/com/intellij/testFramework/fixtures/LightCodeInsightFixtureTestCase.java) > will use relative path to the _source root_ of IntelliJ IDEA Community Edition. ----- diff --git a/user_interface_components/dialog_wrapper.md b/user_interface_components/dialog_wrapper.md index d5cd9ee1b6e..2c5aaad2d5a 100644 --- a/user_interface_components/dialog_wrapper.md +++ b/user_interface_components/dialog_wrapper.md @@ -6,7 +6,7 @@ title: DialogWrapper ## DialogWrapper The -[DialogWrapper](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) +[DialogWrapper](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) +[DialogWrapper](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java) +[DialogWrapper](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java), +[DialogWrapper](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogWrapper.java), +[DialogWrapperExitAction](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/ValidationInfo.java) +[ValidationInfo](upsource:///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. diff --git a/user_interface_components/editor_components.md b/user_interface_components/editor_components.md index b14ea1d9604..540494d9bc1 100644 --- a/user_interface_components/editor_components.md +++ b/user_interface_components/editor_components.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java) +[EditorTextField](upsource:///platform/platform-impl/src/com/intellij/ui/EditorTextField.java) component. When creating an -[EditorTextField](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java), +[EditorTextField](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java) +[EditorTextField](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-psi-api/src/com/intellij/psi/JavaCodeFragmentFactory.java) + [JavaCodeFragmentFactory.getInstance().createReferenceCodeFragment()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/core-api/src/com/intellij/psi/PsiDocumentManager.java) + [PsiDocumentManager.getInstance().getDocument()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/EditorTextField.java) + [EditorTextField](upsource:///platform/platform-impl/src/com/intellij/ui/EditorTextField.java) constructor or its `setDocument()` method. diff --git a/user_interface_components/file_and_class_choosers.md b/user_interface_components/file_and_class_choosers.md index d01c5958c4d..ef22d9a637f 100644 --- a/user_interface_components/file_and_class_choosers.md +++ b/user_interface_components/file_and_class_choosers.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooser.java) +[FileChooser.chooseFiles()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java) +[FileChooserDescriptor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/fileChooser/FileChooserDescriptor.java). +[FileChooserDescriptor](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/TextFieldWithBrowseButton.java) +[TextFieldWithBrowseButton](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/lang-api/src/com/intellij/ide/util/TreeFileChooserFactory.java) class. +[TreeFileChooserFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/openapi/src/com/intellij/ide/util/TreeClassChooserFactory.java) +[TreeClassChooserFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java) +[PackageChooserDialog](upsource:///java/java-impl/src/com/intellij/ide/util/PackageChooserDialog.java) class. diff --git a/user_interface_components/lists_and_trees.md b/user_interface_components/lists_and_trees.md index 96be631e7e5..54a30a437dd 100644 --- a/user_interface_components/lists_and_trees.md +++ b/user_interface_components/lists_and_trees.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java) +[JBList](upsource:///platform/platform-api/src/com/intellij/ui/components/JBList.java) class as drop-in replacement. -[JBList](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java) +[JBList](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/treeStructure/Tree.java) +[Tree](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/components/JBList.java), +[JBList](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ColoredListCellRenderer.java) +[ColoredListCellRenderer](upsource:///platform/platform-api/src/com/intellij/ui/ColoredListCellRenderer.java) or -[ColoredTreeCellRenderer](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ColoredTreeCellRenderer.java) +[ColoredTreeCellRenderer](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java) +[ListSpeedSearch](upsource:///platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java) and -[TreeSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java). +[TreeSpeedSearch](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java) +[ListSpeedSearch](upsource:///platform/platform-impl/src/com/intellij/ui/ListSpeedSearch.java) constructor or as `toString` to the -[TreeSpeedSearch](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-impl/src/com/intellij/ui/TreeSpeedSearch.java) +[TreeSpeedSearch](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java) +[ToolbarDecorator](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util/src/com/intellij/util/ui/EditableModel.java) + [EditableModel](upsource:///platform/util/src/com/intellij/util/ui/EditableModel.java) interface. - [CollectionListModel](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/CollectionListModel.java) + [CollectionListModel](upsource:///platform/platform-api/src/com/intellij/ui/CollectionListModel.java) is a handy model class that implements this interface. * Call - [ToolbarDecorator.createDecorator](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/ToolbarDecorator.java) + [ToolbarDecorator.createDecorator](upsource:///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()`. diff --git a/user_interface_components/misc_swing_components.md b/user_interface_components/misc_swing_components.md index adab829beaf..bacf54d5d66 100644 --- a/user_interface_components/misc_swing_components.md +++ b/user_interface_components/misc_swing_components.md @@ -6,11 +6,11 @@ title: Miscellaneous Swing Components ### Messages The -[Messages](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/Messages.java) +[Messages](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/Messages.java) +[Messages](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java) +[JBSplitter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java) +[JBSplitter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/JBSplitter.java) +[JBSplitter](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/tabs/JBTabs.java) +[JBTabs](upsource:///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. diff --git a/user_interface_components/notifications.md b/user_interface_components/notifications.md index 8a24a94760b..876a7d9dd1d 100644 --- a/user_interface_components/notifications.md +++ b/user_interface_components/notifications.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/DialogBuilder.java), +[DialogBuilder.doValidate()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java) +[HintManager](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/codeInsight/hint/HintManager.java) +[HintManager](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java) +[Notifications](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java). +[Notifications.Bus.notify()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/NotificationListener.java) +[NotificationListener](upsource:///platform/platform-api/src/com/intellij/notification/NotificationListener.java) instance to the constructor of the -[Notification](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java) +[Notification](upsource:///platform/platform-api/src/com/intellij/notification/Notification.java) class. The `groupDisplayId` parameter of the -[Notification](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java) +[Notification](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/notification/Notification.java) +[Notifications.Bus.register()](upsource:///platform/platform-api/src/com/intellij/notification/Notification.java) before displaying any notifications. diff --git a/user_interface_components/popups.md b/user_interface_components/popups.md index 7b94bb1325c..c6fca131688 100644 --- a/user_interface_components/popups.md +++ b/user_interface_components/popups.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) +[JBPopupFactory](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) +[ActionSelectionAid](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/ListPopupStep.java) +[ListPopupStep](upsource:///platform/platform-api/src/com/intellij/openapi/ui/popup/ListPopupStep.java) interface and the -[JBPopupFactory.createListPopup()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/JBPopupFactory.java) +[JBPopupFactory.createListPopup()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/util/BaseListPopupStep.java) +[BaseListPopupStep](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/ui/popup/PopupStep.java), +[PopupStep.onChosen()](upsource:///platform/platform-api/src/com/intellij/openapi/ui/popup/PopupStep.java), or attach an event handler to your own component within the popup. diff --git a/user_interface_components/tool_windows.md b/user_interface_components/tool_windows.md index 6f29df2d0f0..175b7035080 100644 --- a/user_interface_components/tool_windows.md +++ b/user_interface_components/tool_windows.md @@ -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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java) +[ToolWindowFactory](upsource:///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\](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/util-rt/src/com/intellij/openapi/util/Condition.java) +[Condition\](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.java) +[ToolWindowManager.registerToolWindow()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/openapi/wm/ToolWindow.java). +[ToolWindow.getContentManager()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/ContentManager.java), +[ContentManager.getFactory().createContent()](upsource:///platform/platform-api/src/com/intellij/ui/content/ContentManager.java), and then to add it to the toolwindow using -[ContentManager.addContent()](https://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/ContentManager.java). +[ContentManager.addContent()](upsource:///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://upsource.jetbrains.com/idea-community/file/1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-api/src/com/intellij/ui/content/Content.java). +[Content.setCloseable(false)](upsource:///platform/platform-api/src/com/intellij/ui/content/Content.java).