org.netbeans.spi.dashboard

Interface DashboardWidget

public interface DashboardWidget

A widget for display on the dashboard. A widget does not control its own rendering, but provides a title and list of elements that it wants to be rendered by the DashboardDisplayer. This allows for uniform design, different rendering in different contexts, and rendering that does not rely on Swing.

All widget instances should be registered in Dashboard/Widgets and linked from the dashboard categories required, such as Dashboard/Main. Only one widget instance should exist, but it might be shown in multiple places, on one dashboard or many. The DashboardDisplayer.Panel passed in to methods allows the widget to provide contextual information where necessary. The panel may also be used to mark the widget as invalid, where the title and elements need to be re-requested and re-rendered.

Various optional hooks are provided so that a widget can hook into its display. The DashboardWidget.attach(org.netbeans.spi.dashboard.DashboardDisplayer.Panel) hook will be called when a widget is first being prepared for display on a particular panel. It might be used to allocate expensive resources. The DashboardWidget.showing(org.netbeans.spi.dashboard.DashboardDisplayer.Panel) and DashboardWidget.hidden(org.netbeans.spi.dashboard.DashboardDisplayer.Panel) hooks will be called when a particular panel is opened or closed. If using these for attaching listeners, remember that a widget may be showing in more than one place - store the panel in a set and use set emptiness to control. The DashboardWidget.removed(java.lang.String) hook is called when a widget reference is removed by the user. Configuration data attached to the ID might be cleared up. A panel is not provided as one might not be in existence.

Method Summary

Modifier and Type	Method and Description
default void	attach(DashboardDisplayer.Panel panel) Optional hook called when the widget is first being attached to a particular panel in any run of the application.
List<WidgetElement>	elements(DashboardDisplayer.Panel panel) List of elements to be rendered for this widget.
default void	hidden(DashboardDisplayer.Panel panel) Optional hook called when the widget is hidden on a particular panel.
default void	removed(String id) Optional hook called when a widget reference is unregistered by the user.
default void	showing(DashboardDisplayer.Panel panel) Optional hook called when the widget is made visible on a particular panel.
String	title(DashboardDisplayer.Panel panel) The widget title.

Method Detail

title

String title(DashboardDisplayer.Panel panel)

The widget title. Empty text may be returned where no title is required, which a displayer might render differently.

Parameters:

panel - display panel link

Returns:

widget title

elements

List<WidgetElement> elements(DashboardDisplayer.Panel panel)

List of elements to be rendered for this widget.

Parameters:

panel - display panel link

Returns:

list of elements

attach

default void attach(DashboardDisplayer.Panel panel)

Optional hook called when the widget is first being attached to a particular panel in any run of the application. This method is guaranteed to be called before the title or elements are requested.

Parameters:

panel - display panel link

showing

default void showing(DashboardDisplayer.Panel panel)

Optional hook called when the widget is made visible on a particular panel.

Parameters:

panel - display panel link

hidden

default void hidden(DashboardDisplayer.Panel panel)

Optional hook called when the widget is hidden on a particular panel.

Parameters:

panel - display panel link

removed

default void removed(String id)

Optional hook called when a widget reference is unregistered by the user. The ID will match that which would be provided by the panel - the panel might not exist. Any configuration data stored linked to the panel ID should be disposed of.

Parameters:

id - widget registration / panel ID