public class BaseWidget
implements Widget
BaseWidget Creates a widget base class that implements the Widget interface
| Modifier and Type | Field and Description |
|---|---|
static BBjString | BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION_KEY_NAME$Name of STBL key whose value can be set to determine how widgets react to fill errors, overriding the default value. See the FillErrorAction field variable for more information on handling widget fill errors. |
BBjImage | CachedImage!Saves out the last known good state of the widget into a BBjImage for use later on when loading the widget/dashboard |
DashboardWidget | DashboardWidget!Internal field variable used to associate the parent DashboardWidget with this widget. |
BBjNumber | FillErrorActionDetermines how the dashboard should react after encountering an error filling a widget. This numeric field variable defaults to Widget.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 Widget.getON_FILL_ERROR_IGNORE(), Widget.getON_FILL_ERROR_WARN(), or Widget.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 widget:
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 BBjNumber | ON_FILL_ERROR_IGNOREA 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_STOPA 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_WARNA 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. |
Object | UserData!Contains user-settable data for the widget |
| Modifier and Type | Method and Description |
|---|---|
BBjNumber | active()Returns the active status of the widget |
void | destroy()Destroys the widget |
BBjString | getClientSlash()getClientSlash Returns the client's path separator: "" for Windows and "/" for all other operating systems |
BBjNumber | getFillError()Gets the number of the last error that occurred when filling the widget. A return value of 0 indicates that no fill error occurred. |
BBjString | getFillErrorDesc()Gets the description of the last error that occurred when filling the widget. A return value of an empty string indicates that no fill error occurred. |
BBjImage | getImage(BBjString p_imageName!)Returns an image specified in the provided path. This is used internally by the Dashboard Utility for loading images, such as a widget's preview image. If the specified image is not found, it will return the default preview image for all widgets, which is an image with text saying that no preview of the widget is available. This is typically used to provide a preview of the widget in the Customize screen. |
BBjImage | getImage(Object p_object!, BBjString p_defaultImagePath!, Object p_widget!)Gets an image from the provided file path or Java URL. If the desired image cannot be retrieved, the provided default image will be returned instead (if the default image parameter is null(), then that will be the return value). You may either provide a fully-qualified path or a relative path based on the prefix for the first parameter. You may pass in null() or a valid widget for the last parameter. If the widget parameter is valid, the method will log a Dashboard Utility error with an error code of 320 and set the widget's error code and description accordingly. |
BBjString | imageFileSaveDialog()imageFileSaveDialog Displays a file save dialog to save a client image file. |
BBjNumber | isDestroyed()Determins if the widget is destroyed |
void | logError(BBjNumber p_errorNumber, BBjString p_errorMessage$, BBjNumber p_lineNumber)This is the common method that handles errors for the widgets. It's responsible for THROWing the passed in error and logging it to the BBjServices Debug log file. As of BBj 18.20, the routine will behave differently based on the widget's FillErrorAction. It always logs the error information, but depending on the FillErrorAction it may quietly ignore the error and continue, warn the user of the error and continue, or THROW the error and stop. See the BaseWidget's FillErrorAction field for more information. |
BBjString | name()Returns the name of the widget |
BBjImage | previewImage() |
BBjString | previewText() |
void | setActive(BBjNumber p_active)An internal method that sets the active status of the widget based on its parent |
void | setFillErrorDisplayImage(BBjString p_imageFile$)Sets the image that will appear in the widget if it experiences an error upon creation or filling its dataset As of BBj 18.20, it's possible for a dashboard to continue after a widget experiences a fill error. Given the nature of the fill error, the widget may be entirely empty or may contain only partial data. To signify that the widget has incomplete data, you may specify an image or text that will be placed on top of the widget. If a custom error image or text is not set then the widget will display a default error indicator. See Also: BaseWidget::setFillErrorDisplayText() |
void | setFillErrorDisplayText(BBjString p_displayText$)Sets the text that will appear in the widget if it experiences an error filling its underlying dataset As of BBj 18.20, it's possible for a dashboard to continue after a widget experiences a fill error. Given the nature of the fill error, it may be entirely empty or may contain only partial data. To signify that the widget has incomplete data, you may specify an image or text that will be placed on top of the widget. Note that all chart customizations, such as background images and gradients, will still be honored and the text will be placed on top of the regularly rendered chart. See Also: BaseWidget::setFillErrorDisplayImage() |
void | setLastSaveDir(BBjString p_lastSaveDir$)setLastSaveDir Sets the last save directory used. In BUI, this is a NOOP. |
BBjNumber | spacesValid()spacesValid Determines if spaces are valid on the client OS as part a file name. |
BBjString | title()Returns the title of the widget |
public static BBjString BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION_KEY_NAME$Name of STBL key whose value can be set to determine how widgets react to fill errors, overriding the default value. See the FillErrorAction field variable for more information on handling widget fill errors.
BBj 18.20public BBjImage CachedImage!Saves out the last known good state of the widget into a BBjImage for use later on when loading the widget/dashboard
public DashboardWidget DashboardWidget!Internal field variable used to associate the parent DashboardWidget with this widget.
BBj 17.00public BBjNumber FillErrorActionDetermines how the dashboard should react after encountering an error filling a widget.
This numeric field variable defaults to Widget.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 Widget.getON_FILL_ERROR_IGNORE(), Widget.getON_FILL_ERROR_WARN(), or Widget.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 widget:
widget!.setFillErrorAction(Widget.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
BBj 18.20public static BBjNumber ON_FILL_ERROR_IGNOREA 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.20public static BBjNumber ON_FILL_ERROR_STOPA 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.20public static BBjNumber ON_FILL_ERROR_WARNA 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.20public Object UserData!Contains user-settable data for the widget
public BBjNumber active()Returns the active status of the widget
public void destroy()
Destroys the widget
public BBjString getClientSlash()getClientSlash Returns the client's path separator: "" for Windows and "/" for all other operating systems
public BBjNumber getFillError()Gets the number of the last error that occurred when filling the widget. A return value of 0 indicates that no fill error occurred.
BBj 18.20public BBjString getFillErrorDesc()Gets the description of the last error that occurred when filling the widget. A return value of an empty string indicates that no fill error occurred.
BBj 18.20public BBjImage getImage(BBjString p_imageName!)Returns an image specified in the provided path. This is used internally by the Dashboard Utility for loading images, such as a widget's preview image. If the specified image is not found, it will return the default preview image for all widgets, which is an image with text saying that no preview of the widget is available. This is typically used to provide a preview of the widget in the Customize screen.
public BBjImage getImage(Object p_object!, BBjString p_defaultImagePath!, Object p_widget!)Gets an image from the provided file path or Java URL. If the desired image cannot be retrieved, the provided default image will be returned instead (if the default image parameter is null(), then that will be the return value).
You may either provide a fully-qualified path or a relative path based on the prefix for the first parameter. You may pass in null() or a valid widget for the last parameter. If the widget parameter is valid, the method will log a Dashboard Utility error with an error code of 320 and set the widget's error code and description accordingly.
p_object! An image identifier, which is typically a string corresponding to the image path or a Java URL containing the path to the imagep_defaultImagePath! A string path to a BBjImage that will be loaded as a fallback if the desired image cannot be loaded or does not resolve to a valid imagep_widget! A dashboard widget correlated to the image. If this parameter not null(), then the error code and description will be assigned to the widget. Oracle's URL documentation for more information. BBj 18.20public BBjString imageFileSaveDialog()imageFileSaveDialog Displays a file save dialog to save a client image file.
public BBjNumber isDestroyed()Determins if the widget is destroyed
public void logError(BBjNumber p_errorNumber, BBjString p_errorMessage$, BBjNumber p_lineNumber)
This is the common method that handles errors for the widgets. It's responsible for THROWing the passed in error and logging it to the BBjServices Debug log file.
As of BBj 18.20, the routine will behave differently based on the widget's FillErrorAction. It always logs the error information, but depending on the FillErrorAction it may quietly ignore the error and continue, warn the user of the error and continue, or THROW the error and stop. See the BaseWidget's FillErrorAction field for more information.
p_errorNumber The error numberp_errorMessage$ The error messagep_lineNumber The line number on which the error occurred BBj 17.00public BBjString name()Returns the name of the widget
public BBjImage previewImage()public BBjString previewText()public void setActive(BBjNumber p_active)
An internal method that sets the active status of the widget based on its parent
p_active The active status of the widget, 0=inactive, 1=active BBj 18.21public void setFillErrorDisplayImage(BBjString p_imageFile$)
Sets the image that will appear in the widget if it experiences an error upon creation or filling its dataset
As of BBj 18.20, it's possible for a dashboard to continue after a widget experiences a fill error. Given the nature of the fill error, the widget may be entirely empty or may contain only partial data. To signify that the widget has incomplete data, you may specify an image or text that will be placed on top of the widget. If a custom error image or text is not set then the widget will display a default error indicator.
See Also: BaseWidget::setFillErrorDisplayText()
p_imageFile$ A string with the path to an image to display over the widget. The path may be fully qualified or rely on the prefix. BBj 18.20public void setFillErrorDisplayText(BBjString p_displayText$)
Sets the text that will appear in the widget if it experiences an error filling its underlying dataset
As of BBj 18.20, it's possible for a dashboard to continue after a widget experiences a fill error. Given the nature of the fill error, it may be entirely empty or may contain only partial data. To signify that the widget has incomplete data, you may specify an image or text that will be placed on top of the widget. Note that all chart customizations, such as background images and gradients, will still be honored and the text will be placed on top of the regularly rendered chart.
See Also: BaseWidget::setFillErrorDisplayImage()
p_displayText$ A string with the text to display instead of the empty chart BBj 18.20public void setLastSaveDir(BBjString p_lastSaveDir$)
setLastSaveDir Sets the last save directory used. In BUI, this is a NOOP.
p_lastSaveDir$ Specifies the last save diretorypublic BBjNumber spacesValid()spacesValid Determines if spaces are valid on the client OS as part a file name.
public BBjString title()Returns the title of the widget