mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 01:07:49 +08:00
125 lines
7.4 KiB
Markdown
125 lines
7.4 KiB
Markdown
<!-- Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
|
|
# Tool Windows
|
|
|
|
<link-summary>Displaying additional information and controls in child windows of the IDE.</link-summary>
|
|
|
|
<tldr>
|
|
|
|
**Product Help:** [Tool windows](https://www.jetbrains.com/help/idea/tool-windows.html)
|
|
|
|
**UI Guidelines:** [](tool_window.md)
|
|
|
|
</tldr>
|
|
|
|
_Tool windows_ are child windows of the IDE used to display information.
|
|
These windows generally have their own toolbars (referred to as _tool window bars_) along the outer edges of the main window containing one or more _tool window buttons_, which activate panels displayed on the left, bottom, and right sides of the main IDE window.
|
|
|
|
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 <control>Run</control> tool window displays a tab for each active run configuration, and the Version Control related tool windows display 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.
|
|
Using [declarative setup](#declarative-setup), a tool window button is always visible, and the user can activate it and interact with the plugin functionality at any time.
|
|
Alternatively, using [programmatic setup](#programmatic-setup), the tool window is created to show the results of a specific operation, and can then be closed after the operation is completed.
|
|
|
|
### Declarative Setup
|
|
|
|
The tool window is registered in <path>[plugin.xml](plugin_configuration_file.md)</path> 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` attribute (required) of the tool window which corresponds to the text displayed on the tool window button.
|
|
To provide a localized text, specify matching `toolwindow.stripe.[id]` message key (escape spaces with `_`) in the [resource bundle](plugin_configuration_file.md#idea-plugin__resource-bundle) (code insight supported in 2020.3 and later).
|
|
|
|
* The `icon` to display on the tool window button (13x13 pixels, grey and monochromatic; see [](tool_window.md) in UI Guidelines and [](icons.md))
|
|
|
|
* The `anchor`, meaning the side of the screen on which the tool window is displayed ("left" (default), "right" or "bottom")
|
|
|
|
* The `secondary` attribute, specifying whether the tool window is displayed in the primary or the secondary group
|
|
|
|
* The `factoryClass` attribute (required), a class implementing [`ToolWindowFactory`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowFactory.kt).
|
|
|
|
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, no plugin code will be loaded or executed.
|
|
|
|
#### Conditional Display
|
|
|
|
If the tool window of a plugin should not be displayed for all projects:
|
|
|
|
<tabs>
|
|
|
|
<tab title="2023.3 and later">
|
|
|
|
Implement `ToolwindowFactory.isApplicableAsync(Project)`.
|
|
|
|
</tab>
|
|
|
|
<tab title="2021.1 and later">
|
|
|
|
Implement `ToolwindowFactory.isApplicable(Project)`.
|
|
|
|
</tab>
|
|
|
|
<tab title="2019.3 and earlier">
|
|
|
|
Specify the `conditionClass` attribute in <path>plugin.xml</path> with a class implementing [`Condition<Project>`](%gh-ic%/platform/util/src/com/intellij/openapi/util/Condition.java) (can be the same class as the `ToolWindowFactory` implementation).
|
|
|
|
</tab>
|
|
|
|
</tabs>
|
|
|
|
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 [programmatic setup](#programmatic-setup) for tool window registration.
|
|
|
|
### Programmatic Setup
|
|
|
|
For toolwindows shown only after invoking specific actions, use [`ToolWindowManager.registerToolWindow(String,RegisterToolWindowTaskBuilder)`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt).
|
|
|
|
Always use [`ToolWindowManager.invokeLater()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) instead of "plain" `Application.invokeLater()` when scheduling EDT tasks related to tool windows (see [](threading_model.md)).
|
|
|
|
## Contents (Tabs)
|
|
|
|
Displaying the contents of many tool windows requires access to [indexes](indexing_and_psi_stubs.md).
|
|
Because of that, tool windows are normally disabled while building indexes unless the `ToolWindowFactory` is marked [dumb aware](indexing_and_psi_stubs.md#DumbAwareAPI).
|
|
|
|
As mentioned previously, tool windows can contain multiple contents (tabs).
|
|
To manage the contents of a tool window, call [`ToolWindow.getContentManager()`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/wm/ToolWindow.java).
|
|
To add a content (tab), first create it by calling [`ContentManager.getFactory().createContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java), and then to add it to the tool window using [`ContentManager.addContent()`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/ContentManager.java).
|
|
Use `Content.setDisposer()` to register associated `Disposable` (see [](disposers.md)).
|
|
|
|
See [`SimpleToolWindowPanel`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/ui/SimpleToolWindowPanel.java) as a convenient base class, supporting [Toolbars](basic_action_system.md#buildingToolbarPopupMenu) and both vertical/horizontal layout.
|
|
|
|
### Closing Tabs
|
|
|
|
A plugin can control whether the user is allowed to close tabs either globally or on a per-content basis.
|
|
The former is done by passing the `canCloseContents` parameter to the `registerToolWindow()` function, or by specifying `canCloseContents="true"` in <path>plugin.xml</path>.
|
|
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)`](%gh-ic%/platform/ide-core/src/com/intellij/ui/content/Content.java).
|
|
|
|
## Tool Window FAQ
|
|
|
|
### Accessing Tool Window
|
|
|
|
Use [`ToolWindowManager.getToolWindow()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) specifying the `id` used for [registration](#declarative-setup).
|
|
|
|
### Tool Window Notification
|
|
|
|
[`ToolWindowManager.notifyByBalloon()`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/ToolWindowManager.kt) allows showing a notification for the given tool window.
|
|
|
|
### Events
|
|
|
|
Project-level topic [`ToolWindowManagerListener`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/ex/ToolWindowManagerListener.java) allows listening to tool window registration/show events (see [](plugin_listeners.md)).
|
|
|
|
## Sample Plugin
|
|
|
|
To clarify how to develop plugins that create tool windows, consider the **toolWindow** sample plugin available in the [code samples](%gh-sdk-samples-master%/tool_window).
|
|
|
|
See [](code_samples.md) on how to set up and run the plugin.
|
|
|
|
This plugin creates the <control>Sample Calendar</control> tool window that displays the system date, time and time zone.
|
|
When opened, this tool window is similar to the following screen:
|
|
|
|
{width="403"}
|