Add a section describing how to implement your own status bar widgets (#803)

ijs.tree

@@ -95,6 +95,7 @@
       <toc-element id="file_and_class_choosers.md"/>
       <toc-element id="editor_components.md"/>
       <toc-element id="lists_and_trees.md"/>
+      <toc-element id="status_bar_widgets.md"/>
       <toc-element id="misc_swing_components.md"/>
       <toc-element id="work_with_icons_and_images.md" toc-title="Icons and Images"/>
       <toc-element id="color_scheme_management.md"/>

topics/intro/content_updates.md

@@ -13,6 +13,11 @@ See [GitHub Changelog](https://github.com/JetBrains/intellij-sdk-docs/commits/ma
 
 ## 2022
 
+### July-22
+
+Status Bar Widgets
+: Add section [](status_bar_widgets.md) describing how to implement your own status bar widgets.
+
 ### June-22
 
 PHP Type Providers

topics/user_interface_components/status_bar_widgets.md

@@ -0,0 +1,120 @@
+[//]: # (title: Status Bar Widgets)
+
+<!-- Copyright 2000-2022 JetBrains s.r.o. and other contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+The IntelliJ Platform allows plugins to extend the IDE [status bar](https://www.jetbrains.com/help/idea/guided-tour-around-the-user-interface.html#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, etc.
+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`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/StatusBarWidgetFactory.java)
+interface, which is registered in the `com.intellij.statusBarWidgetFactory` extension point.
+
+In case a widget provides information or functionality related to the editor files, consider extending the
+[`StatusBarEditorBasedWidgetFactory`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/widget/StatusBarEditorBasedWidgetFactory.java)
+class.
+
+Each widget factory returns a new widget from `createWidget()`.
+To control the disposing of a widget, implement the `disposeWidget()`, if you just want to dispose it, use `Disposer.dispose(widget)`.
+
+Any widget must implement the
+[`StatusBarWidget`](upsource:///platform/ide-core/src/com/intellij/openapi/wm/StatusBarWidget.java)
+interface.
+
+To reuse the IntelliJ Platform implementation, you can extend one of two classes:
+
+- [`EditorBasedWidget`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/EditorBasedWidget.java)
+- [`EditorBasedStatusBarPopup`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/EditorBasedStatusBarPopup.java)
+
+## EditorBasedWidget
+
+`EditorBasedWidget` is the basic widget implementation.
+To implement it, override `ID()` where returns the unique ID of the widget.
+This identifier may be needed to later obtain 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](upsource:///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](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/PositionPanel.java)
+
+- `com.intellij.openapi.wm.StatusBarWidget.MultipleTextValuesPresentation`
+
+  Widget with a text and a popup.
+
+  Example:
+  [DvcsStatusWidget](upsource:///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.
+>
+{type="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`](upsource:///platform/platform-api/src/com/intellij/openapi/wm/CustomStatusBarWidget.java)
+interface.
+Override `getComponent()` to return the custom widget's component to display.
+
+Example:
+[MemoryUsagePanel](upsource:///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 that's 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 needed 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()`.
+
+## Controlling Widgets Programmatically
+
+By default, when adding a widget to the status bar, it can be displayed/hidden through the context menu of the status bar or widget.
+
+If you want to change visibility programmatically use
+[`StatusBarWidgetSettings.setEnabled()`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/widget/StatusBarWidgetSettings.kt).
+
+The first argument to the method is the factory that created the widget.
+To get it, use
+[`StatusBarWidgetsManager.findWidgetFactory()`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/widget/StatusBarWidgetsManager.java)
+and pass the widget ID and a boolean value that describes whether the widget will be visible or not.
+
+Also, you need to update the widget for the changes to take effect with
+[`StatusBarWidgetsManager.updateWidget()`](upsource:///platform/platform-impl/src/com/intellij/openapi/wm/impl/status/widget/StatusBarWidgetsManager.java).
+
+## 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`](upsource:///platform/core-api/src/com/intellij/ide/lightEdit/LightEditCompatible.java)
+in your factory.

topics/user_interface_components/user_interface_components.md

@@ -32,6 +32,7 @@ The following components are particularly noteworthy:
 *  [](file_and_class_choosers.md)
 *  [](editor_components.md)
 *  [](lists_and_trees.md)
+*  [](status_bar_widgets.md)
 *  Tables (TableView) (TBD)
 *  Drag & Drop Helpers (TBD)
 *  [](misc_swing_components.md)