From 159e87b561c8818586ca56bf1ccafd6fc38ba02c Mon Sep 17 00:00:00 2001 From: Artem Khvastunov Date: Wed, 5 Aug 2015 19:04:33 +0200 Subject: [PATCH] actualized 'Project Structure' section fixed broken URLs some absolute URLs replaced with relative ones fixed style issues --- basics/action_system.md | 18 +++++----- basics/architectural_overview.md | 2 +- basics/persisting_state_of_components.md | 2 +- basics/project_structure.md | 43 +++++++++++++----------- basics/virtual_file_system.md | 17 +++++----- 5 files changed, 42 insertions(+), 40 deletions(-) diff --git a/basics/action_system.md b/basics/action_system.md index c9aea4552..8a546cb3c 100644 --- a/basics/action_system.md +++ b/basics/action_system.md @@ -6,7 +6,7 @@ title: Action System The system of actions allows plugins to add their own items to IDEA menus and toolbars. An action is a class, derived from the -[AnAction](https://github.com/JetBrains/intellij-community/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. For example, one of the action classes is responsible for the "File \| Open File..." menu item and for the "Open File" toolbar button. @@ -15,12 +15,12 @@ Subgroups of the group can form submenus of the menu. Every action and action group has an unique identifier. Identifiers of many of the standard IDEA actions are defined in the -[IdeActions](https://github.com/JetBrains/intellij-community/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. Every action can be included in multiple groups, and thus appear in multiple places within the IDEA user interface. Different places where actions can appear are defined by constants in the -[ActionPlaces](https://github.com/JetBrains/intellij-community/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. Thus, the same action can have different text or icons when it appears in different places of the user interface. Different presentations for the action are created by copying the presentation returned by the ```AnAction.getTemplatePresentation()``` method. @@ -101,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. 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. Second, the action needs to be added to one or more groups. To get an instance of an action group by ID, it is necessary to call ```ActionManager.getAction()``` and cast the returned value to the -[DefaultActionGroup](https://github.com/JetBrains/intellij-community/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. You can create a plugin that registers actions on IDEA startup using the following procedure. -*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 `` section of the plugin.xml file. +*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 `` 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: diff --git a/basics/architectural_overview.md b/basics/architectural_overview.md index d909e3164..a219d7b2b 100644 --- a/basics/architectural_overview.md +++ b/basics/architectural_overview.md @@ -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. 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. The following subjects are covered: diff --git a/basics/persisting_state_of_components.md b/basics/persisting_state_of_components.md index 2835b8007..b38edaf25 100644 --- a/basics/persisting_state_of_components.md +++ b/basics/persisting_state_of_components.md @@ -5,7 +5,7 @@ title: Persisting State of Components The IntelliJ Platform provides an API that allows components or services to persist their state between restarts of the IDE. You can use either a simple API to persist a few values, or persist the state of more complicated components using the -[PersistentStateComponent](https://github.com/JetBrains/intellij-community/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. ## Using PropertiesComponent for Simple non-roamable Persistence diff --git a/basics/project_structure.md b/basics/project_structure.md index eef833f86..9ce130970 100644 --- a/basics/project_structure.md +++ b/basics/project_structure.md @@ -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: -* [Project](https://github.com/JetBrains/intellij-community/tree/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. -* [ProjectManager](https://github.com/JetBrains/intellij-community/tree/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. +* [Project](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/project/Project.java) interface. +* [ProjectRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectRootManager.java) abstract class. +* [ProjectManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/project/ProjectManager.java) abstract class. +* [ProjectFileIndex](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ProjectFileIndex.java) interface. Note that you don't need to access project files directly to load or save settings. 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. 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? 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: -``` +```java 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: -```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? 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. ##### 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: -* [ModuleManager](https://github.com/JetBrains/intellij-community/tree/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. -* [ModuleRootManager](https://github.com/JetBrains/intellij-community/tree/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. -* [ModuleUtil](https://github.com/JetBrains/intellij-community/tree/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. -* [ModifiableRootModel](https://github.com/JetBrains/intellij-community/tree/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModifiableRootModel.java) interface. +* [ModuleManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModuleManager.java) abstract class. +* [Module](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/module/Module.java) interface. +* [ModuleRootManager](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootManager.java) abstract class. +* [ModuleRootModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModuleRootModel.java) interface. +* [ModuleUtil](https://github.com/JetBrains/intellij-community/blob/master/platform/lang-api/src/com/intellij/openapi/module/ModuleUtil.java) class. +* [ModifiableModuleModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/module/ModifiableModuleModel.java) interface. +* [ModifiableRootModel](https://github.com/JetBrains/intellij-community/blob/master/platform/projectModel-api/src/com/intellij/openapi/roots/ModifiableRootModel.java) interface. 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 [module dependencies](http://www.jetbrains.com/idea/webhelp/dependencies-tab.html), 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. 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. 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. 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 -[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. #### How do I work with libraries available within a module? diff --git a/basics/virtual_file_system.md b/basics/virtual_file_system.md index d1b47959a..f716b929c 100644 --- a/basics/virtual_file_system.md +++ b/basics/virtual_file_system.md @@ -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. 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. 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. 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 [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. @@ -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. 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) - -* [VirtualFile.refresh()](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java#L681) +* [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) 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. 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. 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 -[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. 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. 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), -you may not get fileCreated notifications when files are created in that directory. +[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. 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.