public class Dashboard extends DashboardItem
Dashboard Data class that encapsulates the entities that comprise a dashboard
Modifier and Type | Field and Description |
---|---|
BBjNumber | FillErrorAction Determines how the dashboard should react after encountering an error filling a widget. This numeric field variable defaults to Dashboard.getON_FILL_ERROR_IGNORE() (0), meaning that if an error occurs when filling the widget with data the program will silently log the error then continue to run normally. This prevents an entire dashboard application from failing when there is a problem with one widget. The behavior can be set using static field variables like Dashboard.getON_FILL_ERROR_IGNORE(), Dashboard.getON_FILL_ERROR_WARN(), or Dashboard.getON_FILL_ERROR_STOP(). The FillErrorAction can be set programmatically on a Widget, Dashboard Category, or Dashboard object. If you set the FillErrorAction on a Dashboard object, all added DashboardCategories and their Widgets will inherit the setting. If you set the FillErrorAction on a DashboardCategory object, all added Widgets will inherit the setting.
Here is an example showing how to set the behavior in code via a dashboard:
Here are two examples showing how to set the FillErrorAction via a global string:
1) Setting the global string entry in code, before creating any dashboards or widgets:
|
static BBjString | ImageList$ The imagelist image file used by the Dashboard for its icons, such as on the Customize and Exit buttons. This version is used for device pixel ratios 2.0 and lower. For pixel ratios higher than 2.0 see the ImageListHiRes field variable. The specified image file will be used instead of the [BBjHome]/utils/dashboard/images/iconWidgetImageList@2x.png file. If you wish to make your own imagelist file, it can be any size as long as it follows the rules for an imagelist: the imagelist file is made by joining images of equal width together end-to-end horizontally to create a single image. The Dashboard calculates the height of the provided imagelist, then uses that height for the width of the individual images since it assumes square icons. Typically these imagelists will have 10 entries, so if the icons are 36x36 pixels each then the entire imagelist should be 360x36 pixels. The icons in order, from index #0 to #9 are:
|
static BBjString | ImageListHiRes$ The high-res imagelist used by the Dashboard for its icons, such as on the Customize and Exit buttons. This is used for device pixel ratios greater than 2.0. |
static BBjNumber | ON_FILL_ERROR_IGNORE A constant to define how the dashboard handles widget fill errors - this value indicates it should ignore the error and proceed as normal (note that all errors are logged to the BBjServices debug log file). |
static BBjNumber | ON_FILL_ERROR_STOP A constant to define how the dashboard handles widget fill errors - this value indicates it should THROW the error which usually results in the program stopping (note that all errors are logged to the BBjServices debug log file). |
static BBjNumber | ON_FILL_ERROR_WARN A constant to define how the dashboard handles widget fill errors - this value indicates it should warn the user then proceed as normal (note that all errors are logged to the BBjServices debug log file). |
BBjNumber | PersistUserSettings A number that sets whether or not to save out user settings for the dashboard and widgets, such as dashboard size and placement, widget visibility, refresh settings, etc. 0=Do Not Save Settings, 1 = Save Settings (default) Note that settings will still be applied if they were previously saved, regardless of this setting as it only affects whether settings will be saved. |
Constructor and Description |
---|
Dashboard(BBjString p_name$, BBjString p_title$) Dashboard Constructs a Dashboard given a name which uniquely identifies the Dashboard, and a title which displays on the Dashboard window's title bar Note that the p_name$ parameter is used to uniquely identify the Dashboard, and the first 8 characters of the name are used as a prefix when saving the user's preferences for the Dashboard window's size and position as well as information about each Dashboard Category and all of the widgets contained within those categories. Providing a unique identifier for the Dashboard name will ensure that all of its properties will not be overwritten by other Dashboards with a similar name. |
Modifier and Type | Method and Description |
---|---|
DashboardCategory | addDashboardCategory(BBjString p_categoryName$, BBjString p_categoryTitle$) Adds a dashboard category, which is used to group widgets, to the dashboard |
void | destroy() Destroys the dashboard |
BBjVector | getDashboardCategories() Returns the categories of the dashboard |
DashboardCategory | getDashboardCategory(BBjString p_categoryName$) Returns a category of the dashboard, give a category name |
static BBjString | getTranslation(BBjString p_translationKey$) Returns the translation value given a key |
void | removeDashboardCategory(BBjString p_categoryName$) Removes a dashboard category from the dashboard |
void | updateDashboardCategory(BBjString p_categoryName$, BBjString p_newCategoryName$, BBjString p_newCategoryTitle$) Updates a dashboard category in the dashboard |
getBackColor, getName, getTitle, getUserData, setBackColor, setName, setTitle, setUserData
public BBjNumber FillErrorAction
Determines how the dashboard should react after encountering an error filling a widget.
This numeric field variable defaults to Dashboard.getON_FILL_ERROR_IGNORE() (0), meaning that if an error occurs when filling the widget with data the program will silently log the error then continue to run normally. This prevents an entire dashboard application from failing when there is a problem with one widget. The behavior can be set using static field variables like Dashboard.getON_FILL_ERROR_IGNORE(), Dashboard.getON_FILL_ERROR_WARN(), or Dashboard.getON_FILL_ERROR_STOP().
The FillErrorAction can be set programmatically on a Widget, Dashboard Category, or Dashboard object. If you set the FillErrorAction on a Dashboard object, all added DashboardCategories and their Widgets will inherit the setting. If you set the FillErrorAction on a DashboardCategory object, all added Widgets will inherit the setting.
Here is an example showing how to set the behavior in code via a dashboard:
dashboard!.setFillErrorAction(Dashboard.getON_FILL_ERROR_WARN())
Note that you may also set the "BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION" global string entry
either via code or in a configuration file to control the behavior. If the FillErrorAction is set
via a global string it will override all default and programmatically set values for all widgets.
Here are two examples showing how to set the FillErrorAction via a global string:
1) Setting the global string entry in code, before creating any dashboards or widgets:
temp$ = STBL("BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION", "1")
2) Setting the global string entry in the config file, without changing any code:
SET BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION=1
Dashboard Utility Overview
BBj 18.20
public static BBjString ImageList$
The imagelist image file used by the Dashboard for its icons, such as on the Customize and Exit buttons. This version is used for device pixel ratios 2.0 and lower. For pixel ratios higher than 2.0 see the ImageListHiRes field variable.
The specified image file will be used instead of the [BBjHome]/utils/dashboard/images/iconWidgetImageList@2x.png file. If you wish to make your own imagelist file, it can be any size as long as it follows the rules for an imagelist: the imagelist file is made by joining images of equal width together end-to-end horizontally to create a single image. The Dashboard calculates the height of the provided imagelist, then uses that height for the width of the individual images since it assumes square icons. Typically these imagelists will have 10 entries, so if the icons are 36x36 pixels each then the entire imagelist should be 360x36 pixels.
The icons in order, from index #0 to #9 are:
BBj 17.00
public static BBjString ImageListHiRes$
The high-res imagelist used by the Dashboard for its icons, such as on the Customize and Exit buttons. This is used for device pixel ratios greater than 2.0.
BBj 17.00
public static BBjNumber ON_FILL_ERROR_IGNORE
A constant to define how the dashboard handles widget fill errors - this value indicates it should ignore the error and proceed as normal (note that all errors are logged to the BBjServices debug log file).
BBj 18.20
public static BBjNumber ON_FILL_ERROR_STOP
A constant to define how the dashboard handles widget fill errors - this value indicates it should THROW the error which usually results in the program stopping (note that all errors are logged to the BBjServices debug log file).
BBj 18.20
public static BBjNumber ON_FILL_ERROR_WARN
A constant to define how the dashboard handles widget fill errors - this value indicates it should warn the user then proceed as normal (note that all errors are logged to the BBjServices debug log file).
BBj 18.20
public BBjNumber PersistUserSettings
A number that sets whether or not to save out user settings for the dashboard and widgets, such as dashboard size and placement, widget visibility, refresh settings, etc. 0=Do Not Save Settings, 1 = Save Settings (default)
Note that settings will still be applied if they were previously saved, regardless of this setting as it only affects whether settings will be saved.
public Dashboard(BBjString p_name$, BBjString p_title$)
Dashboard Constructs a Dashboard given a name which uniquely identifies the Dashboard, and a title which displays on the Dashboard window's title bar
Note that the p_name$ parameter is used to uniquely identify the Dashboard, and the first 8 characters of the name are used as a prefix when saving the user's preferences for the Dashboard window's size and position as well as information about each Dashboard Category and all of the widgets contained within those categories. Providing a unique identifier for the Dashboard name will ensure that all of its properties will not be overwritten by other Dashboards with a similar name.
p_name$
Name of the dashboardp_title$
Title of the dashboardpublic DashboardCategory addDashboardCategory(BBjString p_categoryName$, BBjString p_categoryTitle$)
Adds a dashboard category, which is used to group widgets, to the dashboard
p_categoryName$
Name of the categoryp_categoryTitle$
Title of the categorypublic void destroy()
Destroys the dashboard
public BBjVector getDashboardCategories()
Returns the categories of the dashboard
public DashboardCategory getDashboardCategory(BBjString p_categoryName$)
Returns a category of the dashboard, give a category name
public static BBjString getTranslation(BBjString p_translationKey$)
Returns the translation value given a key
p_translationKey$
Key of the translation to obtainpublic void removeDashboardCategory(BBjString p_categoryName$)
Removes a dashboard category from the dashboard
p_categoryName$
Name of the dashboard category to removepublic void updateDashboardCategory(BBjString p_categoryName$, BBjString p_newCategoryName$, BBjString p_newCategoryTitle$)
Updates a dashboard category in the dashboard
p_categoryName$
Existing name of the dashboard category to updatep_newCategoryName$
New name of the dashboard categoryp_newCategoryTitle$
New title of the dashboard category