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

Tool Window Factory IJSDK-753

Browse Source
This commit is contained in:
JohnHake 2020-03-19 01:13:57 -07:00
parent cd8c680d53
commit d80dfef823
1 changed files with 25 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
user_interface_components/tool_windows.md
View File

@ -27,52 +27,53 @@ The extension point attributes specify all the data which is necessary to displa
* The `icon` to display on the tool window button (13x13 pixels)
In addition to that, you specify the *factory class* - the name of a class implementing the
In addition to that, specify the *factory class* - the name of a class implementing the
[`ToolWindowFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java)
interface.
When the user clicks on the tool window button, the `createToolWindowContent()` method of the factory class is called, and initializes the UI of the tool window.
This procedure ensures that unused tool windows don't cause any overhead in startup time or memory usage: if a user does not interact with the tool window of your plugin, no plugin code will be loaded or executed.
This procedure ensures that unused tool windows don't cause any overhead in startup time or memory usage: if a user does not interact with the tool window of a plugin, no plugin code will be loaded or executed.
If the tool window of your plugin doesn't need to be displayed for all projects, you can also specify the *conditionClass* attribute - the qualified name of a class implementing the
[`Condition<Project>`](upsource:///platform/util-rt/src/com/intellij/openapi/util/Condition.java)
interface (this can be the same class as the tool window factory implementation).
If the condition returns `false`, the tool window 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 tool window dynamically while the user is working with the project, you need to use the second method for tool window registration.
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 `<ToolWindow>` element: the FQN of a class implementing [`Condition<Project>`](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 `<ToolWindow>` element and `conditionClass` attribute.
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.
The second method involves simply calling
[`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 tool window.
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 indexes.
Because of that, tool windows are normally disabled while building indices, unless you pass true as the value of `canWorkInDumbMode` to the `registerToolWindow()` function.
Displaying the contents of many tool windows requires access to the indicies.
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.
To manage the contents of a tool window, you can call
To manage the contents of a tool window, call
[`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
To add a tab (content), first create it by calling
[`ContentManager.getFactory().createContent()`](upsource:///platform/platform-api/src/com/intellij/ui/content/ContentManager.java),
and then to add it to the tool window using
[`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.
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.
If closing tabs is enabled in general, you can disable closing of specific tabs by calling
`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).
## How to Create a Tool Window?
The IntelliJ Platform provides the `com.intellij.toolWindow` [extension point](/basics/plugin_structure/plugin_extensions.md) that you can use to create and configure your custom tool windows. This extension point is declared using the [`ToolWindowEP`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowEP.java) bean class.
The IntelliJ Platform provides the `com.intellij.toolWindow` [extension point](/basics/plugin_structure/plugin_extensions.md) to create and configure custom tool windows. This extension point is declared using the [`ToolWindowEP`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowEP.java) bean class.
### Creation of Plugin
To create a plugin that displays a custom tool window, perform the following steps:
1. In your plugin project, create a Java class that implements the [`ToolWindowFactory`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.java)interface.
2. In this class, override the `createToolWindowContent` method. This method specifies the content for your tool window.
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.
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 `<extensions defaultExtensionNs="com.intellij">...</extensions>` section.
4. To this section, add the `<toolWindow>` element, and for this element, set the following attributes declared in the ToolWindowEP bean class:
- **id** (required): specifies the tool window caption.
@ -80,7 +81,7 @@ To create a plugin that displays a custom tool window, perform the following ste
- **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).
- **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, you can define conditions to be met to display tool window button. In the Condition class, you should override the value method: if this method returns false, the tool window button is not displayed on tool window bar.
- **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.
To clarify the above procedure, consider the following fragment of the `plugin.xml` file:
@ -97,8 +98,8 @@ To clarify how to develop plugins that create tool windows, consider the **tool
**To run the toolWindow plugin**
1. Start **IntelliJ IDEA** and open the **tool_window** project saved into the [code_samples/tool_window](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/tool_window) directory.
2. Ensure that the project settings are valid for your environment. If necessary, modify the project settings.
To view or modify the project settings, you can open the [Project Structure](https://www.jetbrains.com/help/idea/project-structure-dialog.html) dialog.
2. Ensure that the project settings are valid for the environment. If necessary, modify the project settings.
To view or modify the project settings, open the [Project Structure](https://www.jetbrains.com/help/idea/project-structure-dialog.html) dialog.
3. Run the plugin by choosing the **Run | Run** on the main menu.
If necessary, change the [Run/Debug Configurations](https://www.jetbrains.com/help/idea/run-debug-configuration-plugin.html).