diff --git a/user_interface_components/tool_windows.md b/user_interface_components/tool_windows.md index 22ab1742c..1301e4141 100644 --- a/user_interface_components/tool_windows.md +++ b/user_interface_components/tool_windows.md @@ -10,13 +10,13 @@ _Tool windows_ are child windows of the IDE used to display information. Thes Each side contains two tool window groups, the primary and the secondary one, and only one tool window from each group can be active at a time. Each tool window can show multiple tabs (or "contents", as they are called in the API). -For example, the Run tool window displays a tab for each active run configuration, and the Changes tool window displays a fixed set of tabs depending on the version control system used in the project. +For example, the Run tool window displays a tab for each active run configuration, and the Changes/Version Control tool window displays a fixed set of tabs depending on the version control system used in the project. There are two main scenarios for the use of tool windows in a plugin. In the first scenario (used by the Ant and Commander plugins, for example), a tool window button is always visible, and the user can activate it and interact with the plugin functionality at any time. -In the second scenario (used by the `Analyze Dependencies` action, for example), the tool window is created to show the results of a specific operation, and can be closed by the user after the operation is completed. +In the second scenario (used by the _Analyze Dependencies_ action, for example), the tool window is created to show the results of a specific operation, and can be closed by the user after the operation is completed. -In the first scenario, the tool window is registered in *plugin.xml* using the `com.intellij.toolWindow` extension point. +In the first scenario, the tool window is registered in `plugin.xml` using the `com.intellij.toolWindow` extension point. The extension point attributes specify all the data which is necessary to display the tool window button: * The `id` of the tool window (corresponds to the text displayed on the tool window button) @@ -35,8 +35,8 @@ This procedure ensures that unused tool windows don't cause any overhead in star If the tool window of a plugin doesn't need to be displayed for all projects: * For versions 2020.1 and later, also implement the `isApplicable(Project)` method. -* For versions 2019.3 and earlier, also specify the `conditionClass` attribute for the `` element: the FQN of a class implementing [`Condition`](upsource:///platform/util-rt/src/com/intellij/openapi/util/Condition.java), which can be the same class as the tool window factory implementation. - See [Creation of Plugin](#creation-of-plugin) for more information about the the `` element and `conditionClass` attribute. +* For versions 2019.3 and earlier, also specify the `conditionClass` attribute for the `` element: the FQN of a class implementing [`Condition`](upsource:///platform/util-rt/src/com/intellij/openapi/util/Condition.java), which can be the same class as the tool window factory implementation. + See [Creation of Plugin](#creation-of-plugin) for more information. Note the condition is evaluated only once when the project is loaded; to show and hide a tool window dynamically while the user is working with the project use the second method for tool window registration. @@ -47,7 +47,7 @@ from the plugin code. The method has multiple overloads that can be used depending on the task. When using an overload that takes a component, the component becomes the first content (tab) displayed in the tool window. -Displaying the contents of many tool windows requires access to the indicies. +Displaying the contents of many tool windows requires access to the indices. Because of that, tool windows are normally disabled while building indices, unless `true` is passed as the value of `canWorkInDumbMode` to the `registerToolWindow()` function. As mentioned previously, tool windows can contain multiple tabs, or contents. @@ -60,7 +60,7 @@ and then to add it to the tool window using A plugin 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*. The default value is `false`; calling setClosable(true) on ContentManager content will be ignored unless `canCloseContents` is explicitly set. +`canCloseContents="true"` in `plugin.xml`. The default value is `false`; calling `setClosable(true)` on `ContentManager` content will be ignored unless `canCloseContents` is explicitly set. If closing tabs is enabled in general, a plugin can disable closing of specific tabs by calling [`Content.setCloseable(false)`](upsource:///platform/platform-api/src/com/intellij/ui/content/Content.java). @@ -72,16 +72,16 @@ The IntelliJ Platform provides the `com.intellij.toolWindow` [extension point] To create a plugin that displays a custom tool window, perform the following steps: -1. In a plugin project, create a Java class that implements the [`ToolWindowFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java)interface. +1. In a plugin project, create a class implementing [`ToolWindowFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java). 2. In this class, override the `createToolWindowContent` method. This method specifies the content for the tool window. -3. In the plugin configuration file plugin.xml, create the `...` section. -4. To this section, add the `` element, and for this element, set the following attributes declared in the ToolWindowEP bean class: +3. In the plugin configuration file `plugin.xml`, create the `...` section. +4. To this section, add the `` element, and for this element, set the following attributes declared in the `ToolWindowEP` bean class: - **id** (required): specifies the tool window caption. - - **anchor** (required): specifies the tool window bar where the tool window button will be displayed. Possible values: "left", "right", "top", "bottom." - - **secondary** (optional): when true, the tool window button will be shown on the lower part of the tool window bar. Default value is false. - - **factoryClass** (required): specifies the Java class implementing the ToolWindowFactory interface (see Step 1). + - **anchor** (required): specifies the tool window bar where the tool window button will be displayed. Possible values: "left", "right", or "bottom." + - **secondary** (optional): when `true`, the tool window button will be shown on the lower part of the tool window bar. Default value is `false`. + - **factoryClass** (required): specifies the class implementing the `ToolWindowFactory` interface (see Step 1). - **icon** (optional): specifies path to the icon that identifies the tool window, if any. - - **conditionClass** (optional): specifies a Java class that implements the [`Condition`](upsource:///platform/util-rt/src/com/intellij/openapi/util/Condition.java) interface. Using this class, define conditions to be met to display tool window button. In the Condition class, override the value method: if this method returns false, the tool window button is not displayed on tool window bar. + - **conditionClass** (optional): specifies a class that implements [`Condition`](upsource:///platform/util-rt/src/com/intellij/openapi/util/Condition.java). Using this class, define conditions to be met to display tool window button. When returning `false`, the tool window button is not displayed on tool window bar. To clarify the above procedure, consider the following fragment of the `plugin.xml` file: