prs/prs.media/dashboard how-to.txt

Steps to creating a new dashboard:

In PRSDesktop, create a new "User Control" XAML file under "Dashboards/". This is the control which is the dashboard itself. For the purposes of example, let this be "IncompleteTasksDashboard.xaml"
The dashboard class associated with that XAML file (IncompleteTasksDashboard) must implement PRSDesktop.IDashboardWidget<TGroup, TProperties> in the following way:

public partial class IncompleteTasksDashboard : UserControl, IDashboardWidget<Common, IncompleteTasksDashboardProperties>

The "Common" type is a type that derives from PRSDesktop.DashboardWidgetGroup. When designing a dashboard, the context menu that allows to select which dashboard to add is grouped based on this type. So our example, IncompleteTasksDashboard, will appear under the "Common" sub-menu.

The second type argument, IncompleteTasksDashboardProperties, is the class that defines the properties for the dashboard. This must be a class that implements PRSDesktop.IDashboardProperties, as below.

public class IncompleteTasksDashboardProperties : IDashboardProperties { }

Since IncompleteTasksDashboard derives from IDashboardWidget, there are several methods it must implement, which mirror the same methods for all panels:

- void Setup()
Called first, to initialise the dashboard. Put setup stuff in here rather than the constructor.

- void Refresh()
Called to refresh the dashboard's data.

- void Shutdown()
Called when closing the dashboard or navigating away.

Also, you will need to define a property called "Properties", which is of type TProperties - in this case, IncompleteTasksDashboardProperties.
This property is initialised automatically before Setup() is called from the saved dashboard properties. It is also automatically saved.
In essence, don't worry about trying to save or load this manually. *Every* change you make to it should be saved.

We need one final step to tell PRS where our dashboard is. You need to define a class that derives from PRSDesktop.DashboardElement<TDashboard, TGroup, TProperties>.
UtilityDashboard.xaml.cs scans for all types that derive from this class, and this is how it marries up the saved dashboard properties and the dashboard classes.
(Ultimately, it derives from DFLayoutElement). If you do not define this class, then you will not be able to create the dashboard; it will not appear in the menu.

public class IncompleteTasksDashboardElement : DashboardElement<IncompleteTasksDashboard, Common, IncompleteTasksDashboardProperties> { }

And that's basically it! Now you have a user control with properties that can be added to dashboards.