mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-27 16:57:49 +08:00
126 lines
5.5 KiB
Markdown
126 lines
5.5 KiB
Markdown
<!-- Copyright 2000-2025 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
|
|
# Status Bar Widgets
|
|
|
|
<link-summary>Extending the status bar with custom widgets providing information about the current file, project, IDE, and similar.</link-summary>
|
|
|
|
<tldr>
|
|
|
|
**Product Help:** [Status bar](https://www.jetbrains.com/help/idea/guided-tour-around-the-user-interface.html#status-bar)
|
|
|
|
</tldr>
|
|
|
|
The IntelliJ Platform allows plugins to extend the IDE status bar with additional custom widgets.
|
|
|
|
Status bar widgets are small UI elements that allow providing users with useful information and settings for the current file, project, IDE, and similar.
|
|
For example, the status bar contains the widget showing the encoding of the current file, or the current VCS branch of the project.
|
|
|
|
Due to the prominent presentation and limited space, they should be used only for information or settings that are relevant enough to be "always" shown.
|
|
|
|
The starting point for extending the status bar with new widgets is the
|
|
[`StatusBarWidgetFactory`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/StatusBarWidgetFactory.java)
|
|
interface, which is registered in the <include from="snippets.topic" element-id="ep"><var name="ep" value="com.intellij.statusBarWidgetFactory"/></include>.
|
|
Note: `id` attribute must be provided in <path>plugin.xml</path> registration and match value from `StatusBarWidgetFactory.getId()`.
|
|
|
|
In case a widget provides information or functionality related to the editor files, consider extending the
|
|
[`StatusBarEditorBasedWidgetFactory`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/widget/StatusBarEditorBasedWidgetFactory.kt)
|
|
class.
|
|
|
|
Each widget factory returns a new widget from `createWidget()`.
|
|
To control the disposing of a widget, implement the `disposeWidget()`.
|
|
To dispose it, use `Disposer.dispose(widget)`.
|
|
|
|
Any widget must implement the
|
|
[`StatusBarWidget`](%gh-ic%/platform/ide-core/src/com/intellij/openapi/wm/StatusBarWidget.kt)
|
|
interface.
|
|
|
|
To reuse the IntelliJ Platform implementation, you can extend one of two classes:
|
|
|
|
- [`EditorBasedWidget`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/EditorBasedWidget.kt)
|
|
- [`EditorBasedStatusBarPopup`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/EditorBasedStatusBarPopup.kt)
|
|
|
|
## `EditorBasedWidget`
|
|
|
|
`EditorBasedWidget` is the basic widget implementation.
|
|
To implement it, override `ID()` which returns the unique ID of the widget.
|
|
This identifier may be necessary to later get a widget instance.
|
|
|
|
Use one of the existing predefined widget appearance options:
|
|
|
|
- `com.intellij.openapi.wm.StatusBarWidget.IconPresentation`
|
|
|
|
Widget with only an icon.
|
|
|
|
Example:
|
|
[`PowerSaveStatusWidgetFactory`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/PowerSaveStatusWidgetFactory.java)
|
|
|
|
- `com.intellij.openapi.wm.StatusBarWidget.TextPresentation`
|
|
|
|
Widget with only a text.
|
|
|
|
Example:
|
|
[`PositionPanel`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/PositionPanel.kt)
|
|
|
|
- `com.intellij.openapi.wm.StatusBarWidget.MultipleTextValuesPresentation`
|
|
|
|
Widget with a text and a popup.
|
|
|
|
Example:
|
|
[`DvcsStatusWidget`](%gh-ic%/platform/dvcs-impl/src/com/intellij/dvcs/ui/DvcsStatusWidget.java)
|
|
|
|
> Note that they can't be combined to get, for example, an icon and a text.
|
|
>
|
|
{style="note"}
|
|
|
|
To use the selected appearance, return a class that implements one of the above interfaces from `getPresentation()`.
|
|
|
|
To create a widget with custom content, it should implement the
|
|
[`CustomStatusBarWidget`](%gh-ic%/platform/platform-api/src/com/intellij/openapi/wm/CustomStatusBarWidget.java)
|
|
interface.
|
|
Override `getComponent()` to return the custom widget's component to display.
|
|
|
|
Example:
|
|
[`MemoryUsagePanel`](%gh-ic%/platform/platform-impl/src/com/intellij/openapi/wm/impl/status/MemoryUsagePanel.java)
|
|
|
|
## `EditorBasedStatusBarPopup`
|
|
|
|
`EditorBasedStatusBarPopup` is the basis for all widgets that have a popup with a list of actions.
|
|
For example, the encoding widget of the current file.
|
|
|
|
The component to display is returned from `createComponent()`.
|
|
Each update of the widget IDE calls `updateComponent()` to update this component.
|
|
In `updateComponent()` implementation, you can describe how the widget should change depending on the current state.
|
|
|
|
Implement `getWidgetState()` to return the current state of the widget.
|
|
This state will be passed to the `updateComponent()` when the widget is updated.
|
|
The method accepts a file currently opened in the editor.
|
|
To create your own state class, inherit it from `EditorBasedStatusBarPopup.WidgetState.WidgetState`.
|
|
|
|
Implement `ID()` and return the unique ID of the widget.
|
|
This identifier may be necessary to later get a widget instance.
|
|
|
|
Implement `createInstance()` and return the new widget instance.
|
|
|
|
Finally, implement the `createPopup()` method, which returns the [popup](popups.md) that will be displayed when the widget is clicked.
|
|
|
|
Custom listeners to be notified of widget updates can be registered using `registerCustomListeners()`.
|
|
|
|
To update a widget, use `update()`.
|
|
|
|
## Showing Widget in LightEdit Mode
|
|
|
|
By default, widgets aren't shown in [LightEdit](https://www.jetbrains.com/help/idea/lightedit-mode.html) mode.
|
|
To show a widget, implement
|
|
[`LightEditCompatible`](%gh-ic%/platform/core-api/src/com/intellij/ide/lightEdit/LightEditCompatible.java)
|
|
in your factory.
|
|
|
|
## FAQ
|
|
|
|
### How to get a widget programmatically?
|
|
|
|
```kotlin
|
|
val widget = WindowManager.getInstance().getStatusBar(project)
|
|
.getWidget(MyWidget.ID) as MyWidget
|
|
|
|
```
|