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

actualized 'Project Structure' section

Browse Source 
fixed broken URLs
some absolute URLs replaced with relative ones
fixed style issues
This commit is contained in:
Artem Khvastunov 2015-08-05 19:04:33 +02:00
parent 9be49205f4
commit 159e87b561
5 changed files with 42 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
basics/action_system.md
View File

@ -6,7 +6,7 @@ title: Action System
The system of actions allows plugins to add their own items to IDEA menus and toolbars. The system of actions allows plugins to add their own items to IDEA menus and toolbars.
An action is a class, derived from the An action is a class, derived from the
[AnAction](https://github.com/JetBrains/intellij-community/tree/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) [AnAction](https://github.com/JetBrains/intellij-community/blob/master/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. 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. For example, one of the action classes is responsible for the "File \| Open File..." menu item and for the "Open File" toolbar button.
@ -15,12 +15,12 @@ Subgroups of the group can form submenus of the menu.
Every action and action group has an unique identifier. Every action and action group has an unique identifier.
Identifiers of many of the standard IDEA actions are defined in the Identifiers of many of the standard IDEA actions are defined in the
[IdeActions](https://github.com/JetBrains/intellij-community/tree/master/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java) [IdeActions](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/IdeActions.java)
class. class.
Every action can be included in multiple groups, and thus appear in multiple places within the IDEA user interface. 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 Different places where actions can appear are defined by constants in the
[ActionPlaces](https://github.com/JetBrains/intellij-community/tree/master/platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java) [ActionPlaces](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/ActionPlaces.java)
interface. For every place where the action appears, a new ```Presentation``` is created. 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. 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. Different presentations for the action are created by copying the presentation returned by the ```AnAction.getTemplatePresentation()``` method.
@ -101,20 +101,20 @@ Registering actions in plugin.xml is demonstrated in the following example. The
To register an action from code, two steps are required. 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 First, an instance of the class derived from ```AnAction``` must be passed to the ```registerAction``` method of the
[ActionManager](https://github.com/JetBrains/intellij-community/tree/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionManager.java) [ActionManager](https://github.com/JetBrains/intellij-community/blob/master/platform/editor-ui-api/src/com/intellij/openapi/actionSystem/ActionManager.java)
class, to associate the action with an ID. class, to associate the action with an ID.
Second, the action needs to be added to one or more groups. 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 To get an instance of an action group by ID, it is necessary to call ```ActionManager.getAction()``` and cast the returned value to the
[DefaultActionGroup](https://github.com/JetBrains/intellij-community/tree/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java) [DefaultActionGroup](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/actionSystem/DefaultActionGroup.java)
class. class.
You can create a plugin that registers actions on IDEA startup using the following procedure. You can create a plugin that registers actions on IDEA startup using the following procedure.
*To register an action on IDEA startup* *To register an action on IDEA startup:*
# Create a new class that implements the ```ApplicationComponent``` interface.
# In this class, override the ```getComponentName```, ```initComponent```, and ```disposeComponent``` methods.
# Register this class in the `<application-components>` section of the plugin.xml file.
* Create a new class that implements the ```ApplicationComponent``` interface.
* In this class, override the ```getComponentName```, ```initComponent```, and ```disposeComponent``` methods.
* Register this class in the `<application-components>` section of the plugin.xml file.
To clarify the above procedure, consider the following sample Java class ```MyPluginRegistration``` that registers an action defined in a custom ```TextBoxes``` class and adds a new menu command to the *Window* menu group on the main menu: To clarify the above procedure, consider the following sample Java class ```MyPluginRegistration``` that registers an action defined in a custom ```TextBoxes``` class and adds a new menu command to the *Window* menu group on the main menu:

2
basics/architectural_overview.md
View File

@ -5,7 +5,7 @@ title: Architectural Overview
This topic describes the architecture of IntelliJ Platform from a plugin developer's point of view. It is organized in a task-based manner to answer specific questions like "what can I do with this object?", "how do I get to this object?" and so on. This topic describes the architecture of IntelliJ Platform from a plugin developer's point of view. It is organized in a task-based manner to answer specific questions like "what can I do with this object?", "how do I get to this object?" and so on.
Before proceeding please make sure you're familiar with the basic concepts of IntelliJ Platform plugin development. If not, consider starting with the live demo and tutorials at Before proceeding please make sure you're familiar with the basic concepts of IntelliJ Platform plugin development. If not, consider starting with the live demo and tutorials at
[http://www.jetbrains.com/idea/plugins/index.html](http://www.jetbrains.com/idea/plugins/index.html) [www.jetbrains.com/idea/plugins/](http://www.jetbrains.com/idea/plugins/)
and then returning to this document. and then returning to this document.
The following subjects are covered: The following subjects are covered:

2
basics/persisting_state_of_components.md
View File

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

43
basics/project_structure.md
View File

@ -95,14 +95,14 @@ 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: To work with projects and project files, you can use the following classes and interfaces:
* [Project](https://github.com/JetBrains/intellij-community/tree/master/platform/core-api/src/com/intellij/openapi/project/Project.java) interface. * [Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java) interface.
* [ProjectRootManager](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class. * [ProjectRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class.
* [ProjectManager](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class. * [ProjectManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class.
* [ProjectFileIndex](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) interface. * [ProjectFileIndex](https://github.com/JetBrains/intellij-community/blob/master/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. Note that you don't need to access project files directly to load or save settings.
See See
[Persisting State of Components](http://www.jetbrains.org/intellij/sdk/docs/basics/persisting_state_of_components.html) [Persisting State of Components](/basics/persisting_state_of_components.html)
for more information. for more information.
Note that hereafter, the ```project``` variable is of the ```Project``` type. Note that hereafter, the ```project``` variable is of the ```Project``` type.
@ -139,10 +139,10 @@ Use the ```ProjectRootManager.getFileIndex()``` method. For example:
##### How do I get a module to which a file belongs? ##### How do I get a module to which a file belongs?
To determine a module in the project in question to which the specified To determine a module in the project in question to which the specified
[virtual file](http://www.jetbrains.org/intellij/sdk/docs/basics/architectural_overview/virtual_file.html) [virtual file](/basics/architectural_overview/virtual_file.html)
belongs, use the ```ProjectFileIndex.getModuleForFile(virtualFile)``` method: belongs, use the ```ProjectFileIndex.getModuleForFile(virtualFile)``` method:
``` ```java
Module module = ProjectRootManager.getInstance(project).getFileIndex().getModuleForFile(virtualFile); Module module = ProjectRootManager.getInstance(project).getFileIndex().getModuleForFile(virtualFile);
``` ```
@ -150,15 +150,18 @@ Note that this method returns ```null``` if the file does not belong to any modu
You can also use the ```ProjectFileIndex.getContentRootForFile``` method to get the module content root to which the specified file or directory belongs: You can also use the ```ProjectFileIndex.getContentRootForFile``` method to get the module content root to which the specified file or directory belongs:
```VirtualFile moduleContentRoot = ProjectRootManager.getInstance(project).getFileIndex().getContentRootForFile(virtualFileorDirectory);``` ```java
VirtualFile moduleContentRoot = ProjectRootManager.getInstance(project).getFileIndex().getContentRootForFile(virtualFileorDirectory);
```
##### How do I get the module source root or library source root to which the specified file or directory belongs? ##### How do I get the module source root or library source root to which the specified file or directory belongs?
Use the ```ProjectFileIndex.getSourceRootForFile``` method. For example: Use the ```ProjectFileIndex.getSourceRootForFile``` method. For example:
```VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project).getFileIndex().getSourceRootForFile(virtualFileorDirectory); ```java
VirtualFile moduleSourceRoot = ProjectRootManager.getInstance(project).getFileIndex().getSourceRootForFile(virtualFileorDirectory);
``` ```
Note that this method returns ```null``` if the file or directory does not belong to any source root of modules in the project. Note that this method returns ```null``` if the file or directory does not belong to any source root of modules in the project.
##### How do I check whether a file or directory is related to the project libraries? ##### How do I check whether a file or directory is related to the project libraries?
@ -194,13 +197,13 @@ Note that by default, the project modules use the project SDK. Optionally, you c
*IntelliJ Platform* provides a number of Java classes and interfaces you can use to work with modules: *IntelliJ Platform* provides a number of Java classes and interfaces you can use to work with modules:
* [ModuleManager](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class. * [ModuleManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class.
* [Module](https://github.com/JetBrains/intellij-community/tree/master/platform/core-api/src/com/intellij/openapi/module/Module.java) interface. * [Module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java) interface.
* [ModuleRootManager](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class. * [ModuleRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class.
* [ModuleRootModel](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface. * [ModuleRootModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface.
* [ModuleUtil](https://github.com/JetBrains/intellij-community/tree/master/platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class. * [ModuleUtil](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class.
* [ModifiableModuleModel](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface. * [ModifiableModuleModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface.
* [ModifiableRootModel](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModifiableRootModel.java) interface. * [ModifiableRootModel](https://github.com/JetBrains/intellij-community/blob/master/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. This section discusses how to complete some common tasks related to management of modules.
@ -217,7 +220,7 @@ tab of the *Project Structure* dialog box.
To explore the To explore the
[module dependencies](http://www.jetbrains.com/idea/webhelp/dependencies-tab.html), [module dependencies](http://www.jetbrains.com/idea/webhelp/dependencies-tab.html),
use the use the
[OrderEnumerator](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/OrderEnumerator.java) [OrderEnumerator](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/OrderEnumerator.java)
class. class.
The following code snippet illustrates how you can get classpath (classes root of all dependencies) for a module: The following code snippet illustrates how you can get classpath (classes root of all dependencies) for a module:
@ -230,7 +233,7 @@ VirtualFile[] roots = ModuleRootManager.getInstance(module).orderEntries().class
Use the ```ModuleRootManager.getSdk()``` method. Use the ```ModuleRootManager.getSdk()``` method.
This method returns a value of the This method returns a value of the
[Sdk](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/projectRoots/Sdk.java) [Sdk](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/projectRoots/Sdk.java)
type. type.
The following code snippet illustrates how you can get detailed information on SDK the specified module uses: The following code snippet illustrates how you can get detailed information on SDK the specified module uses:
@ -271,7 +274,7 @@ String moduleName = module == null ? "Module not found" : module.getName();
``` ```
* To get the project module to which the specified * To get the project module to which the specified
[PSI element](http://www.jetbrains.org/intellij/sdk/docs/basics/architectural_overview/psi_elements.html) [PSI element](/basics/architectural_overview/psi_elements.html)
belongs, use the ```ModuleUtil.findModuleForPsiElement(psiElement)``` method. belongs, use the ```ModuleUtil.findModuleForPsiElement(psiElement)``` method.
#### How do I work with libraries available within a module? #### How do I work with libraries available within a module?

17
basics/virtual_file_system.md
View File

@ -37,7 +37,7 @@ Refresh operations are explicitly invoked from the IntelliJ IDEA or plugin code
The VFS will be updated during the next refresh operation which includes the file in its scope. The VFS will be updated during the next refresh operation which includes the file in its scope.
IntelliJ Platform refreshes the entire project contents asynchronously on startup. IntelliJ Platform refreshes the entire project contents asynchronously on startup.
By default, it performs a refresh operation when the user switches to it from another app, but users can turn this off via **Settings \| Synchronize** files on frame activation. By default, it performs a refresh operation when the user switches to it from another app, but users can turn this off via **Settings \| Appearance & Behavior \| System Settings \| Synchronize files on frame activation**.
On Windows, Mac and Linux IntelliJ Platform starts a native file watcher process that receives file change notifications from the file system and reports them to IntelliJ Platform. On Windows, Mac and Linux IntelliJ Platform starts a native file watcher process that receives file change notifications from the file system and reports them to IntelliJ Platform.
If a file watcher is available, a refresh operation looks only at the files that have been reported as changed by the file watcher. If a file watcher is available, a refresh operation looks only at the files that have been reported as changed by the file watcher.
@ -63,7 +63,7 @@ In fact, the refresh operations are executed according to their own threading po
Both synchronous and asynchronous refreshes can be initiated from any thread. 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. If a refresh is initiated from a background thread, the calling thread must not hold a read action, because otherwise a deadlock would occur.
See [IntelliJ Platform Architectural Overview] for more details on the threading model and read/write actions. 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 The same threading requirements also apply to functions like
[LocalFileSystem.refreshAndFindFileByPath()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/vfs/LocalFileSystem.java), [LocalFileSystem.refreshAndFindFileByPath()](https://github.com/JetBrains/intellij-community/blob/master/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. which perform a partial refresh if the file with the specified path is not found in the snapshot.
@ -71,9 +71,8 @@ which perform a partial refresh if the file with the specified path is not found
In nearly all cases, using asynchronous refreshes is strongly preferred. 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: 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:
* [RefreshQueue.createSession()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/vfs/newvfs/RefreshQueue.java#L36) * [RefreshQueue.createSession()](https://github.com/JetBrains/intellij-community/blob/master/platform/platform-api/src/com/intellij/openapi/vfs/newvfs/RefreshQueue.java)
* [VirtualFile.refresh()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java)
* [VirtualFile.refresh()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java#L681)
Synchronous refreshes can cause deadlocks in some cases, depending on which locks are held by the thread invoking the refresh operation. Synchronous refreshes can cause deadlocks in some cases, depending on which locks are held by the thread invoking the refresh operation.
@ -83,12 +82,12 @@ All changes happening in the virtual file system, either as a result of refresh
VFS events are always fired in the event dispatch thread, and in a write action. VFS events are always fired in the event dispatch thread, and in a write action.
The most efficient way to listen to VFS events is to implement the BulkFileListener interface and to subscribe with it to the The most efficient way to listen to VFS events is to implement the BulkFileListener interface and to subscribe with it to the
[VirtualFileManager.VFS_CHANGES](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L34) [VirtualFileManager.VFS_CHANGES](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java)
topic. topic.
This API gives you all the changes detected during the refresh operation in one list, and lets you process them in batch. This API gives you all the changes detected during the refresh operation in one list, and lets you process them in batch.
Alternatively, you can implement the VirtualFileListener interface and register it using Alternatively, you can implement the VirtualFileListener interface and register it using
[VirtualFileManager.addVirtualFileListener()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java#L113). [VirtualFileManager.addVirtualFileListener()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java).
This will let you process the events one by one. This will let you process the events one by one.
Note that the VFS listeners are application-level, and will receive events for changes happening in all the projects opened by the user. Note that the VFS listeners are application-level, and will receive events for changes happening in all the projects opened by the user.
@ -100,7 +99,7 @@ However, it is still present in the VFS snapshot, and you can access its last co
Note that a refresh operation fires events only for changes in files that have been loaded in the snapshot. Note that a refresh operation fires events only for changes in files that have been loaded in the snapshot.
For example, if you accessed a VirtualFile for a directory but never loaded its contents using For example, if you accessed a VirtualFile for a directory but never loaded its contents using
[VirtualFile.getChildren()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java#L315), [VirtualFile.getChildren()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java),
you may not get fileCreated notifications when files are created in that directory. you may not get fileCreated notifications when files are created in that directory.
If you loaded only a single file in a directory using VirtualFile.findChild(), you will get notifications for changes to that file, but you may not get created/deleted notifications for other files in the same directory. If you loaded only a single file in a directory using VirtualFile.findChild(), you will get notifications for changes to that file, but you may not get created/deleted notifications for other files in the same directory.