BaseWidget

java.lang.Object
- Dashboard.BaseWidget

All Implemented Interfaces:

Widget

Direct Known Subclasses:

BBjWidget, GridExWidget, JasperViewerWidget
```
public class BaseWidget
extends Object
implements Widget
```
Creates a widget base class that implements the Widget interface

Field Summary

Fields
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.
`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`	`FillErrorAction` Determines how the dashboard should react after encountering an error filling a widget.
`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.
`Object`	`UserData!` Contains user-settable data for the widget

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BBjNumber`	`active()` Returns the active status of the widget
`void`	`destroy()` Destroys the widget
`BBjString`	`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.
`BBjString`	`getFillErrorDesc()` Gets the description of the last error that occurred when filling the widget.
`BBjImage`	`getImage(BBjString p_imageName!)` Returns an image specified in the provided path.
`BBjImage`	`getImage(Object p_object!, BBjString p_defaultImagePath!, Object p_widget!)` Gets an image from the provided file path or Java URL.
`BBjString`	`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.
`BBjString`	`name()` Returns the name of the widget
`BBjImage`	`previewImage()` Returns the preview image of the widget
`BBjString`	`previewText()` Returns the preview text of the widget
`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
`void`	`setFillErrorDisplayText(BBjString p_displayText$)` Sets the text that will appear in the widget if it experiences an error filling its underlying dataset
`void`	`setLastSaveDir(BBjString p_lastSaveDir$)` Sets the last save directory used.
`BBjNumber`	`spacesValid()` Determines if spaces are valid on the client OS as part a file name.
`BBjString`	`title()` Returns the title of the widget

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Dashboard.Widget
clone, create, display, resize

- Field Detail
  - DashboardWidget!
```
public DashboardWidget DashboardWidget!
```
    Internal field variable used to associate the parent DashboardWidget with this widget. @since BBj 17.00
  - UserData!
```
public Object UserData!
```
    Contains user-settable data for the widget
  - CachedImage!
```
public BBjImage CachedImage!
```
    Saves out the last known good state of the widget into a BBjImage for use later on when loading the widget/dashboard
  - FillErrorAction
```
public BBjNumber FillErrorAction
```
    Determines 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
    
    Since:
    
    BBj 18.20
  - ON_FILL_ERROR_IGNORE
```
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). @since BBj 18.20
  - ON_FILL_ERROR_WARN
```
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. @since BBj 18.20
  - ON_FILL_ERROR_STOP
```
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). @since BBj 18.20
  - BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION_KEY_NAME$
```
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.
    
    Since:
    
    BBj 18.20
- Method Detail
  - logError
```
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.
    
    Parameters:
    
    p_errorNumber - The error number
    
    p_errorMessage$ - The error message
    
    p_lineNumber - The line number on which the error occurred
    
    Since:
    
    BBj 17.00
  - getImage
```
public 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.
    
    Returns:
    
    A BBjImage with the default or developer-defined preview of the widget
  - getImage
```
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.
    
    Parameters:
    
    p_object! - An image identifier, which is typically a string corresponding to the image path or a Java URL containing the path to the image
    
    p_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 image
    
    p_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.
    
    Returns:
    
    The BBjImage specified in the p_object! variable, the p_defaultImagePath! image if the desired image designation is invalid, or null() if both are invalid
    
    Since:
    
    BBj 18.20
    
    See Also:
    
    URL documentation for more information.
  - setActive
```
public void setActive(BBjNumber p_active)
```
    An internal method that sets the active status of the widget based on its parent
    
    Parameters:
    
    p_active - The active status of the widget, 0 = inactive, 1 = active
    
    Since:
    
    BBj 18.21
  - active
```
public BBjNumber active()
```
    Returns the active status of the widget
    
    Returns:
    
    Returns the active status of the widget, 0 = inactive, 1 = active
  - name
```
public BBjString name()
```
    Returns the name of the widget
    
    Specified by:
    
    name in interface Widget
    
    Returns:
    
    Returns the widget's name which is specified on creation
  - title
```
public BBjString title()
```
    Returns the title of the widget
    
    Specified by:
    
    title in interface Widget
    
    Returns:
    
    Returns widget's title which is specified on creation
  - destroy
```
public void destroy()
```
    Destroys the widget
    
    Specified by:
    
    destroy in interface Widget
  - isDestroyed
```
public BBjNumber isDestroyed()
```
    Determins if the widget is destroyed
    
    Specified by:
    
    isDestroyed in interface Widget
  - previewImage
```
public BBjImage previewImage()
```
    Description copied from interface: Widget
    
    Returns the preview image of the widget
    
    Specified by:
    
    previewImage in interface Widget
    
    Returns:
    
    BBjImage that contains the preview image image of the widget
  - previewText
```
public BBjString previewText()
```
    Description copied from interface: Widget
    
    Returns the preview text of the widget
    
    Specified by:
    
    previewText in interface Widget
    
    Returns:
    
    Preview text of the widget
  - getClientSlash
```
public BBjString getClientSlash()
```
    Returns the client's path separator: "\" for Windows and "/" for all other operating systems
    
    Returns:
    
    Returns "\" for Windows and "/" for all other operating systems
  - spacesValid
```
public BBjNumber spacesValid()
```
    Determines if spaces are valid on the client OS as part a file name.
    
    Returns:
    
    Returns 1 (TRUE) if spaces are valid on the client OS as part a file name, otherwise 0 (FALSE) is returned.
  - setLastSaveDir
```
public void setLastSaveDir(BBjString p_lastSaveDir$)
```
    Sets the last save directory used. In BUI, this is a NOOP.
    
    Parameters:
    
    p_lastSaveDir$ - Specifies the last save diretory
  - imageFileSaveDialog
```
public BBjString imageFileSaveDialog()
```
    Displays a file save dialog to save a client image file.
    
    Returns:
    
    Returns the file name of the selected client image or an empty string when no file is selected.
  - setFillErrorDisplayImage
```
public 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()
    
    Parameters:
    
    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.
    
    Since:
    
    BBj 18.20
  - setFillErrorDisplayText
```
public 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()
    
    Parameters:
    
    p_displayText$ - A string with the text to display instead of the empty chart
    
    Since:
    
    BBj 18.20
  - getFillError
```
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.
    
    Returns:
    
    A BBjNumber corresponding to the custom widget fill error.
    
    Since:
    
    BBj 18.20
  - getFillErrorDesc
```
public 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.
    
    Returns:
    
    A BBjString containing a description of the widget fill error.
    
    Since:
    
    BBj 18.20

Class BaseWidget

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface Dashboard.Widget

Field Detail

DashboardWidget!

UserData!

CachedImage!

FillErrorAction

ON_FILL_ERROR_IGNORE

ON_FILL_ERROR_WARN

ON_FILL_ERROR_STOP

BASIS_DASHBOARD_UTILITY_FILL_ERROR_ACTION_KEY_NAME$

Method Detail

logError

getImage

getImage

setActive

active

name

title

destroy

isDestroyed

previewImage

previewText

getClientSlash

spacesValid

setLastSaveDir

imageFileSaveDialog

setFillErrorDisplayImage

setFillErrorDisplayText

getFillError

getFillErrorDesc