Status Bar Widgets
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, 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
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
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
interface.
To reuse the IntelliJ Platform implementation, you can extend one of two classes:
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
com.intellij.openapi.wm.StatusBarWidget.TextPresentation
Widget with only a text.
Example: PositionPanel
com.intellij.openapi.wm.StatusBarWidget.MultipleTextValuesPresentation
Widget with a text and a popup.
Example: DvcsStatusWidget
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
interface. Override getComponent()
to return the custom widget's component to display.
Example: MemoryUsagePanel
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 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()
.
The first argument to the method is the factory that created the widget. To get it, use StatusBarWidgetsManager.findWidgetFactory()
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()
.
Showing Widget in LightEdit Mode
By default, widgets aren't shown in LightEdit mode. To show a widget, implement LightEditCompatible
in your factory.