mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 01:07:49 +08:00
d8e83b57ea
* Add UI Guidelines to SDK docs * Add UI Guidelines to SDK docs * Fixing build errors * optimize PNGs * add UI guidelines landing page placeholder * IJ SDK Docs <-> UI guidelines crosslinks updated * split_button.md: remove reference to removed setting * use <ui-path> * use MD instead of <note> * use %gh-ic% links * drop_down.md: fix <control> * code samples: fix most obvious issues * remove obsolete `_defaults.md` * ijs.tree: UI cleanup * Delete "under construction" pages * Fix headers * Add link-summary * Remove invalid links * Delete unused files * Remove ''@2x' from image file names * Use Markdown syntax for some images and tables * Rename non-unique files to unique * Remove alpha in images where content is unreadable * align quotation marks * Controls: cleanup/fixes, add code links, edit * tooltip.md: fix HTML * misc fixes * typography.md: fix table contents * typography.md: fix table header * UI guidelines landing page + TOC fixes * remove unused icons_list.md * Normalize image paths * validation_errors.md: Fix broken tab * "correct"/"incorrect" labels styling * Resize images to 50% * button.topic: fixes * grammar, spelling, minor edits * remove ' ' * fix 99px * cleanup * UI_kit.md: minor * Fix "MRK058: Large image in paragraph rendered as a block element by default." * button.topic: Add img[alt] * mnemonics.md: Update "Contact Us" link to the IJSDK YouTrack * split_button.md: Use ui-path * UI landing: add feedback snippet * Improve code snippets formatting and naming * Fix code samples * Fix code samples * Add Kotlin variants for code samples * Add icons_list.md * crosslinks * Change external link to https://intellij-icons.jetbrains.design/ * icons list -> https://intellij-icons.jetbrains.design * Hide info about reducing split button to simple action button (now it is available through the registry only) * reformat * icons_style.md: Images in new line --------- Co-authored-by: marianna.kononenko <marianna.kononenko@jetbrains.com> Co-authored-by: Yann Cébron <yann.cebron@jetbrains.com>
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 [](general_threading_rules.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#building-ui-from-actions) 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"}
|