Method Detail

• addChartDomainMarker

  public void addChartDomainMarker(BBjString p_key$, BBjString p_markerColorDesc$, BBjNumber p_markerOpacity, BBjString p_label$, BBjString p_labelColorDesc$, BBjNumber p_labelOpacity, RectangleAnchor p_rectangleAnchor!, TextAnchor p_textAnchor!)

  Adds a threshold marker for the chart's domain (markers are typically added to plots to highlight or draw attention to specific values) - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis.

  This method allows you to add multiple domain markers to a chart while specifying the label text and position. In contrast, the setChartDomainMarker() methods only allow to you specify a single marker and does not include a label for the marker.

  Typically a marker will be drawn by the renderer as a line perpendicular to the domain axis, however this is entirely up to the renderer. Note that this does not apply to charts without a domain, such as a PieChart or RingChart.

  The rectangle anchor will typically be a value like RectangleAnchor.TOP, RectangleAnchor.CENTER, RectangleAnchor.TOP_LEFT, RectangleAnchor.BOTTOM_RIGHT.

  The text anchor will typically be a value like TextAnchor.TOP, TextAnchor.CENTER, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_RIGHT, TextAnchor.TOP_LEFT, TextAnchor.BOTTOM_RIGHT.

  Parameters:

  p_key$ The column key corresponding to the point on the domain at which the marker will be placed

  p_markerColorDesc$ A string with a hex description of the color for the marker. Example: "#ffccaa" or "#fca"

  p_markerOpacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_label$ The text for the label that accompanies the marker

  p_labelColorDesc$ A string with a hex description of the color for the label. Example: "#ffccaa" or "#fca"

  p_labelOpacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_rectangleAnchor! The anchor point for the label's rectangle (passing in null() will use the default of RectangleAnchor.CENTER)

  p_textAnchor! The anchor point for the label's text in the rectangle (passing in null() will use the default of TextAnchor.CENTER)

  See Also:

  RectangleAnchor for more information on anchor values

  TextAnchor for more information on anchor values

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• addChartRangeMarker

  public void addChartRangeMarker(BBjNumber p_value, BBjString p_colorDesc$, BBjNumber p_opacity, BBjString p_label$, BBjString p_labelColorDesc$, BBjNumber p_labelOpacity, RectangleAnchor p_rectangleAnchor!, TextAnchor p_textAnchor!)

  Adds a threshold marker for the chart's range (markers are typically added to plots to highlight or draw attention to specific values) - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis.

  This method allows you to add multiple range markers to a chart while specifying the label text and position. In contrast, the setChartRangeMarker() methods only allow to you specify a single marker and does not include a label for the marker.

  Typically a marker will be drawn by the renderer as a line perpendicular to the range axis, however this is entirely up to the renderer. Note that this does not apply to charts without a range, such as a PieChart or RingChart.

  The rectangle anchor will typically be a value like RectangleAnchor.TOP, RectangleAnchor.CENTER, RectangleAnchor.TOP_LEFT, RectangleAnchor.BOTTOM_RIGHT.

  The text anchor will typically be a value like TextAnchor.TOP, TextAnchor.CENTER, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_RIGHT, TextAnchor.TOP_LEFT, TextAnchor.BOTTOM_RIGHT.

  Note that the range marker label will not display in a 3DLineChart due to a limitation in the underlying JFreeCharts libary. The range marker will still be rendered, but the label will be absent unless it's a different type of category chart.

  Parameters:

  p_value The position (determined by value) at which the marker will be placed

  p_markerColorDesc$ A string with a hex description of the color for the marker. Example: "#ffccaa" or "#fca"

  p_markerOpacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_label$ The text for the label that accompanies the marker

  p_labelColorDesc$ A string with a hex description of the color for the label. Example: "#ffccaa" or "#fca"

  p_labelOpacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_rectangleAnchor! The anchor point for the label's rectangle (passing in null() will use the default of RectangleAnchor.CENTER which is horizontally in the middle of the marker)

  p_textAnchor! The anchor point for the label's text in the rectangle (passing in null() will use the default of TextAnchor.TOP_CENTER which is vertically below the marker)

  See Also:

  RectangleAnchor for more information on anchor values

  TextAnchor for more information on anchor values

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• adjustColorBrightness

  public static Color adjustColorBrightness(Color p_color!, BBjNumber p_fraction)

  Lighten or Darken a Color by a specified amount

  Parameters:

  p_color! The Java Color to be modified

  p_fraction The amount to lighten or darken the Color. A positive number will lighten the colors, a negative number will darken the colors. Possible values range from -1.0 to 1.0

  Returns:

  A modified version of the original Color

• adjustColorOpacity

  public static Color adjustColorOpacity(Color p_color!, BBjNumber p_fraction)

  Sets the opacity for a Color to a specified amount

  Parameters:

  p_color! The Java Color to be modified

  p_fraction The amount to affec the opacity the Color. A positive number will increase the opacity, a negative number will decrease the opacity. Possible values range from -1.0 to 1.0

  Returns:

  A modified version of the original Color

• adjustColorSaturation

  public static Color adjustColorSaturation(Color p_color!, BBjNumber p_fraction)

  Saturate or Desaturate a Color by a specified amount

  Parameters:

  p_color! The Java Color to be modified

  p_fraction The amount to saturate the Color. A positive number will increase the saturation, a negative number will decrease the saturation. Possible values range from -1.0 to 1.0

  Returns:

  A modified version of the original Color

• adjustColorVectorBrightness

  public static BBjVector adjustColorVectorBrightness(BBjVector p_colorVector!, BBjNumber p_fraction)

  Lighten or Darken every color in the vector by a specified amount

  Parameters:

  p_colorVector! A vector filled with Colors to be modified

  p_fraction The amount to lighten or darken each Color. A positive number will lighten the colors, a negative number will darken the colors. Possible values range from -1.0 to 1.0

  Returns:

  The vector of modified colors

• adjustColorVectorOpacity

  public static BBjVector adjustColorVectorOpacity(BBjVector p_colorVector!, BBjNumber p_fraction)

  Increase or decrease the opacity for every color in the vector to a specified amount

  Parameters:

  p_colorVector! A vector filled with Colors to be modified

  p_fraction The amount to adjust the opacity value for each Color. A positive number will increase the opacity (making it more opaque), a negative number will decrease the opacity (making it more transparent). Possible values range from -1.0 to 1.0

  Returns:

  The vector of modified colors

• adjustColorVectorOpacityToFixedAmount

  public static BBjVector adjustColorVectorOpacityToFixedAmount(BBjVector p_colorVector!, BBjNumber p_opacity)

  Sets the opacity to a fixed amount for every color in the vector

  Parameters:

  p_colorVector! A vector filled with Colors to be modified

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  The vector of modified colors

• adjustColorVectorSaturation

  public static BBjVector adjustColorVectorSaturation(BBjVector p_colorVector!, BBjNumber p_fraction)

  Saturate or Desaturate every color in the vector by a specified amount

  Parameters:

  p_colorVector! A vector filled with Colors to be modified

  p_fraction The amount to saturate each Color. A positive number will increase the saturation, a negative number will decrease the saturation. Possible values range from -1.0 to 1.0

  Returns:

  The vector of modified colors

• cloneCommonChartWidgetParameters

  public void cloneCommonChartWidgetParameters(ChartWidget widget!)

  A method used internally to propagate a chart widget's properties to a cloned version of the chart

• createCombinedImage

  public static BBjImage createCombinedImage(BBjImage p_imageBottom!, BBjImage p_imageTop!, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by overlaying one image on top of another, specifying the final image dimensions

  Parameters:

  p_imageBottom! A BBjImage that will be drawn on the bottom of the final image

  p_imageTop! A BBjImage that will be drawn on the top of the final image

  p_width The width of the resultant image

  p_height The height of the resultant image

  Returns:

  A BBjImage that's a combination of the two provided images

  Since:

  18.20

• createCombinedImagesWithText

  public static BBjImage createCombinedImagesWithText(BBjImage p_imageBottom!, BBjImage p_imageMiddle!, BBjString p_text$, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by combining two images with text

  This is an internal method that's used to draw text (such as the user-settable ErrorDisplayText) over two existing images (such as a partially-filled chart and default error image). It's a convenience method that combines calls to the createImageFromText() and createCombinedImage() methods.

  Parameters:

  p_imageBottom! A BBjImage that will be drawn on the bottom of the final image

  p_imageMiddle! A BBjImage that will be drawn over the bottom image

  p_text$ A BBjString of the text to display over the images

  p_width The width of the resultant image

  p_height The height of the resultant image

  Returns:

  A BBjImage that's a combination of the provided image with the text drawn on top of it

  Since:

  18.20

• createCombinedImageWithText

  public static BBjImage createCombinedImageWithText(BBjImage p_image!, BBjString p_text$, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by combining an existing image with text

  This is an internal method that's used to draw text (such as the user-settable ErrorDisplayText) over an existing image (such as a partially-filled chart). It's a convenience method that combines calls to the createImageFromText() and createCombinedImage() methods.

  Parameters:

  p_image! An existing BBjImage, such as a chart image

  p_text$ A BBjString of the text to display over the image

  p_width The width of the resultant image

  p_height The height of the resultant image

  Returns:

  A BBjImage that's a combination of the provided image with the text drawn on top of it

  Since:

  18.20

• createImageFromText

  public static BBjImage createImageFromText(BBjString p_text$, BBjString p_foreColor$, BBjNumber p_foreOpacity, BBjString p_backColor$, BBjNumber p_backOpacity, BBjString p_fontFile$, BBjString p_fontStyle$, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by drawing automatically-sized text on a graphics context

  This method dynamically determines the best font size to maximize the size of the text given the image's dimensions. You can use a linefeed character ($0A$) to split the text into multiple lines. The text block will be centered both vertically and horizontally in the resultant image.

  Parameters:

  p_text$ The text string to draw

  p_foreColor$ The foreground color of the resultant text specified as a hex color string. An example would be "#ff00cc" or "#f0c"

  p_foreOpacity The desired opacity value (0-1) of the foreground color. 0=Fully Transparent, 1=Fully Opaque.

  p_backColor$ The background color of the resultant text specified as a hex color string. An example would be "#ff00cc" or "#f0c"

  p_backOpacity The desired opacity value (0-1) of the background color. 0=Fully Transparent, 1=Fully Opaque.

  p_fontFile$ The path to the desired font file, ie. System.getProperty("basis.BBjHome") + "/utils/dashboard/fonts/CabinCondensed-Bold.ttf"

  p_fontStyle$ The font's style which is one of the following: BOLD, ITALIC, or PLAIN

  p_width The width of the resultant BBjImage

  p_height The height of the resultant BBjImage

  Returns:

  A BBjImage that's an image of the text

  Since:

  18.20

• createImageFromText

  public static BBjImage createImageFromText(BBjString p_text$, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by drawing automatically-sized text on a graphics context

  This method is used internally to indicate that a widget does not contain any data or has experienced an error. The method uses a default font, foreground color, and background color. It centers the text both vertically and horizontally. It also dynamically determines the best font size to maximize the size of the text given the image's dimensions. You can use a linefeed character ($0A$) to split the text into multiple lines.

  Parameters:

  p_text$ The text to display in the image

  p_width The width of the resultant image

  p_height The height of the resultant image

  Returns:

  A BBjImage that's an image of the text

  Since:

  18.20

• createImageFromText

  public static BBjImage createImageFromText(BBjString p_text$, BBjString p_foreColor$, BBjNumber p_foreOpacity, BBjString p_backColor$, BBjNumber p_backOpacity, Font p_font!, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by drawing text on a graphics context

  You can use a linefeed character ($0A$) to split the text into multiple lines

  Parameters:

  p_text$ The text string to draw

  p_foreColor$ The foreground color of the resultant text specified as a hex color string. An example would be "#ff00cc" or "#f0c"

  p_foreOpacity The desired opacity value (0-1) of the foreground color. 0=Fully Transparent, 1=Fully Opaque.

  p_backColor$ The background color of the resultant text specified as a hex color string. An example would be "#ff00cc" or "#f0c"

  p_backOpacity The desired opacity value (0-1) of the background color. 0=Fully Transparent, 1=Fully Opaque.

  p_font! The Java Font used to draw the text, which defines the font family, font styles, and font size.

  p_width The width of the resultant BBjImage

  p_height The height of the resultant BBjImage

  Returns:

  A BBjImage with the text drawn in it

• createImageFromText

  public static BBjImage createImageFromText(BBjString p_text$, BBjString p_foreColor$, BBjNumber p_foreOpacity, Font p_font!, BBjNumber p_width, BBjNumber p_height)

  Creates a BBjImage by drawing text on a transparent background

  You can use a linefeed character ($0A$) to split the text into multiple lines

  Parameters:

  p_text$ The text string to draw

  p_foreColor$ The foreground color of the resultant text specified as a hex color string. An example would be "#ff00cc" or "#f0c"

  p_foreOpacity The desired opacity value (0-1) of the foreground color. 0=Fully Transparent, 1=Fully Opaque.

  p_font! The Java Font used to draw the text, which defines the font family, font styles, and font size.

  p_width The width of the resultant Image

  p_height The height of the resultant Image

  Returns:

  A BBjImage with a transparent background and the text drawn in it

• createRadialGradientPaint

  public static Paint createRadialGradientPaint(Color p_color1!, Color p_color2!, Point2D p_center!)

  Gets a radial gradient paint based off of two colors and the center point relative to the entire chart

  Parameters:

  p_color1! The starting Color

  p_color2! The ending Color

  p_center! The center from which the radius extends

  Returns:

  A RadialGradientPaint created from the Colors

  See Also:

  Oracle's RadialGradientPaint documentation for more information.

• darkenColor

  public static Color darkenColor(Color p_color!, BBjNumber p_fraction)

  Make a color darker

  Parameters:

  p_color! Color to make darker.

  p_fraction Darkness fraction (0-1).

  Returns:

  A darker version of the original

• email

  public void email(BBjNumber p_parentX, BBjNumber p_parentY, BBjNumber p_parentWidth, BBjNumber p_parentHeight)

  Displays a dialog that facilitates emailing a screenshot of the chart as an attachment to one or more recipients

• exportData

  public void exportData(BBjNumber p_parentX, BBjNumber p_parentY, BBjNumber p_parentWidth, BBjNumber p_parentHeight)

  Displays an export dialog that allows the user to export the widget's data to a CSV file with several output options

  Parameters:

  p_parentX X location of the parent window

  p_parentY Y location of the parent window

  p_parentWidth Width of the parent window

  p_parentHeight Height of the parent window

• fillJDBCXYSeries

  public void fillJDBCXYSeries(XYSeries p_series!, BBjString p_connectString$, BBjString p_sql$)

  Given an SQL query, fill an XYSeries with the resultant two columns of numerical data

  Parameters:

  p_series! The series to be filled with data

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

• fillJDBCXYSeries

  public void fillJDBCXYSeries(XYSeries p_series!, BBjString p_connectString$, BBjString p_sql$, BBjString p_mode$)

  Given an SQL query, fill an XYSeries with the resultant two columns of numerical data

  Parameters:

  p_series! The series to be filled with data

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

  p_mode$ A string comprised of a list of properties and values separated by commas that will be passed to the database or JDBC connection at connect time. For example: "USER=myusername, PWD=mypass, AUTOCOMMIT=N"

  Since:

  BBj 16.00

• fillJDBCXYSeries

  public void fillJDBCXYSeries(XYSeries p_series!, BBjRecordSet p_rs!, BBjVector p_columns!)

  Given a BBjRecordSet and a vector of columns, fill an XYSeries with the resultant two columns of numerical data

  Parameters:

  p_series! The series to be filled with data

  p_rs! The BBjRecordSet containing the data used to populate the series

  p_columns! A BBjVector that contains an ordered list of the columns to be used for the series data. The entries may be a string corresponding to a field name, or a 0-based index of the column number. If null() is passed in for the p_columns! vector then the first two columns of the BBjRecordSet will be used.

• getBBjColor

  public static BBjColor getBBjColor(Color p_color!)

  Method to create a BBjColor from a Java Color, taking into account an alpha channel if it exists

  Parameters:

  p_color! A java.awt.color

  Returns:

  A BBjColor version of the supplied Color

  See Also:

  Oracle's Color documentation for more information.

• getBBjColorWithAlphaFromHexString

  public static BBjColor getBBjColorWithAlphaFromHexString(BBjString p_colorHexString$, BBjNumber p_opacity)

  Method to create a BBjColor with an alpha channel from a hex string

  Parameters:

  p_colorHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  A BBjColor built from the specific hex color string with the desired opacity value

• getChartDataItemFromPoint

  public DataItem getChartDataItemFromPoint(BBjNumber p_x, BBjNumber p_y)

  Gets the chart's last data item with an area that encloses the specified coordinates

  This method is typically used to get information about a data entity in the chart when the user clicks on the chart. Depending on the chart type, it's possible that the provided point will be inside more than one data entity, such as in an AreaChart where the areas overlap one another. This method will return the last entity that matches, but the getChartDataItemsFromPoint() method will return information for all matching entities.

  Parameters:

  p_x The X location in the chart

  p_y The X location in the chart

  Returns:

  Null() if no data items match the coordinates or a DataItem object (or one of its subclasses) that contains the data item corresponding to the specified coordinates. For Bar and Line charts the returned object will be CategoryDataItem from which you can get the row key, column key, and value. For Pie charts, the returned object will be a KeyedValueDataItem from which you can get the key and value. For XY charts, the the returned object will be a KeyedValueDataItem from which you can get the series, item, x, and y values for the data item in the XY chart.

• getChartDataItemsFromPoint

  public BBjVector getChartDataItemsFromPoint(BBjNumber p_x, BBjNumber p_y)

  Gets all of the chart's data items with an area that encloses the specified coordinates

  This method is typically used to get information about a data entity in the chart when the user clicks on the chart. Depending on the chart type, it's possible that the provided point will be inside more than one data entity, such as in an AreaChart where the areas overlap one another. This method will return all matching entities, but the getChartDataItemFromPoint() method will return only the last matching entity.

  Parameters:

  p_x The X location in the chart

  p_y The X location in the chart

  Returns:

  A BBjVector filled with DataItem objects (or one of its subclasses) that contain the data corresponding to the specified coordinates. For Bar and Line charts the returned objects will be CategoryDataItem objects from which you can get the row key, column key, and value. For Pie charts, the returned objects will be a KeyedValueDataItem from which you can get the key and value. For XY charts, the the returned objects will be a KeyedValueDataItem from which you can get the series, item, x, and y values for the data item in the XY chart. If no data items in the chart match the specified coordinates, the returned vector will be empty.

• getChartDomainAxisFormat

  public DecimalFormat getChartDomainAxisFormat()

  Returns the custom decimal format for the XYChart's domain axis (x-axis) numbers - note that this applies only to an XYChart

  Returns:

  DecimalFormat A java DecimalFormat that defines the desired format if it has been set previously via the ChartWidget::setChartDomainAxisFormat() method, otherwise null()

  See Also:

  DecimalFormat

  Since:

  BBj 19.00

• getChartFontFile

  public BBjString getChartFontFile()

  Gets the customized font file for the chart.

  Returns:

  BBjString A string that contains the path to the font file.

• getChartHeight

  public BBjNumber getChartHeight()

  Returns the height of the chart

  Returns:

  The chart's height in pixels

• getChartRangeAxisFormat

  public DecimalFormat getChartRangeAxisFormat()

  Returns the custom decimal format for the chart's range axis (y-axis) numbers

  Returns:

  DecimalFormat A java DecimalFormat that defines the desired format if it has been set previously via the ChartWidget::setChartRangeAxisFormat() method

• getChartRangeAxisToCurrency

  public BBjNumber getChartRangeAxisToCurrency()

  Return a BBjNumber indicating if the range axis was set to show its values formatted as currency for the current locale

  Returns:

  A number indicating whether the range axis will be formatted as currency or not. 0=No currency formatting, 1=Currency formatting.

• getChartRangeAxisToPercent

  public BBjNumber getChartRangeAxisToPercent()

  Return a BBjNumber indicating if the range axis was set to show its values formatted as a percentage.

  When the range axis is set to show values as a percentage, the range values will be multiplied by 100 and the percent sign will be appended to the value.

  Returns:

  A number indicating whether the range axis will be formatted as a percentage or not. 0=Not as a percentage, 1=As a percentage.

• getChartWidth

  public BBjNumber getChartWidth()

  Returns the width of the chart

  Returns:

  The chart's width in pixels

• getColorTheme

  public static BBjVector getColorTheme(BBjNumber p_colorThemeIndex)

  Gets a pre-defined color theme vector

  Parameters:

  p_colorThemeIndex Color theme index

  Returns:

  A vector filled with the Colors in the theme

  See Also:

  See ChartWidget.getColorThemeSky() for an example

• getColorThemeCount

  public static BBjNumber getColorThemeCount()

  Gets the total number of color themes

  Returns:

  A number corresponding to the total number of color themes offered by the ChartWidget

• getColorThemeDescription

  public static BBjString getColorThemeDescription(BBjNumber p_colorThemeIndex)

  Gets the description of the specified color theme

  Parameters:

  p_colorThemeIndex The number of the desired color theme for which to return a description

  Returns:

  A string that describes the color theme corresponding to the supplied color theme index

• getColorWithAlpha

  public static Color getColorWithAlpha(BBjColor p_color!, BBjNumber p_opacity)

  Method to create a Java Color with an alpha channel from a BBjColor where opacity = (0-1)

  Parameters:

  p_color! A BBjColor

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  A Color with the desired opacity value

  See Also:

  Oracle's Color documentation for more information.

• getColorWithAlpha

  public static Color getColorWithAlpha(Color p_color!, BBjNumber p_opacity)

  Method to create a Java Color with an alpha channel from a Java Color by specifying an opacity amount.

  Parameters:

  p_color! A Color

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  A Color with the desired opacity value

  See Also:

  Oracle's Color documentation for more information.

• getColorWithAlphaFromHexString

  public static Color getColorWithAlphaFromHexString(BBjString p_colorHexString$, BBjNumber p_opacity)

  Method to create a Java Color with an alpha channel from a hex string

  Parameters:

  p_colorHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  A Java Color built from the specific hex color string with the desired opacity value

  See Also:

  Oracle's Color documentation for more information.

• getDataset

  public Object getDataset()

• getDefaultChartColors

  public static BBjVector getDefaultChartColors()

  Gets the default colors for a chart

  Returns:

  Returns a BBjVector filled with Java Color objects that are used as the default color theme when a custom color theme has not been specified.

• getDevicePixelRatio

  public BBjNumber getDevicePixelRatio()

  Gets the screen's device pixel ratio used for modifying ChartWidgets

  Returns:

  A BBjNumber containing the device pixel ratio

• getFont

  public static Font getFont(BBjFont p_font!)

  Create a java font from a BBjFont

  Parameters:

  p_font! A BBjFont

  Returns:

  A java.awt.Font version of the BBjFont

• getFontScalingFactor

  public BBjNumber getFontScalingFactor()

  Gets the custom font scaling factor for the chart as set by the original dashboard program.

  Parameters:

  BBjNumber A multiplication factor that is applied to the base font size. If the base font is 10 points, and p_factor is 1.2, then the resultant base font size will be 12 points.

• getHexStringFromColor

  public static BBjString getHexStringFromColor(Color p_color!)

  Method to get a hex representation of a Java Color with an alpha channel

  Parameters:

  p_color! A Java Color

  Returns:

  A hex color string. An example would be "#ff00cc"

  See Also:

  Oracle's Color documentation for more information.

• getHSBValuesFromRGBColor

  public static BBjVector getHSBValuesFromRGBColor(Color p_color!)

  Method to convert a RGB Color to its corresponding HSB (Java) values and return an array containing the 3 HSB values

  Parameters:

  p_color! A Color

  Returns:

  A BBjVector filled with the Hue, Saturation, and Brightness float values of the Color

• getHSLValuesFromRGBColor

  public static BBjVector getHSLValuesFromRGBColor(Color p_color!)

  Method to convert a RGB Color to its corresponding HSL (CSS) values and return an array containing the 3 HSL values

  Parameters:

  p_color! A Color

  Returns:

  A BBjVector filled with the Hue, Saturation, and Lightness float values of the Color

• getJavaColor

  public static Color getJavaColor(BBjColor p_color!)

  Method to create a Java Color from a BBjColor

  Parameters:

  p_color! A BBjColor

  Returns:

  A java.awt.Color version of the supplied BBjColor

  See Also:

  Oracle's Color documentation for more information.

• getJavaColor

  public static Color getJavaColor(BBjString p_colorHexString$)

  Method to create a Java Color from a hex color string

  Parameters:

  p_colorHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  Returns:

  A java.awt.Color version of the supplied hex color

  See Also:

  Oracle's Color documentation for more information.

• getJDBCCategoryDataset

  public org.jfree.data.category.Defaultorg.jfree.data.category.CategoryDataset getJDBCCategoryDataset(BBjString p_connectString$, BBjString p_sql$)

  Given an SQL query, return a DefaultCategoryDataset filled with the desired data

  Parameters:

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

  Returns:

  A JDBCCategoryDataset filled with the query results

  See Also:

  JFreeChart's DefaultCategoryDataset documentation for more information.

• getJDBCCategoryDataset

  public org.jfree.data.category.Defaultorg.jfree.data.category.CategoryDataset getJDBCCategoryDataset(BBjString p_connectString$, BBjString p_sql$, BBjString p_mode$)

  Given an SQL query, return a DefaultCategoryDataset filled with the desired data

  Parameters:

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

  p_mode$ A string comprised of a list of properties and values separated by commas that will be passed to the database or JDBC connection at connect time. For example: "USER=myusername, PWD=mypass, AUTOCOMMIT=N"

  Returns:

  A JDBCCategoryDataset filled with the query results

  See Also:

  JFreeChart's DefaultCategoryDataset documentation for more information.

  Since:

  BBj 16.00

• getJDBCCategoryDataset

  public org.jfree.data.category.Defaultorg.jfree.data.category.CategoryDataset getJDBCCategoryDataset(BBjRecordSet p_rs!, BBjVector p_columns!)

  Given a BBjRecordSet and a BBjVector containing the columns of interest, return a DefaultCategoryDataset filled with the desired data

  Parameters:

  p_rs! The BBjRecordSet containing the data used to populate the chart

  p_columns! A BBjVector that contains an ordered list of the columns to be used for the charts's data. The entries may be a string corresponding to a field name, or a 0-based index of the column number. If null() is passed in for the p_columns! vector then the first three columns of the BBjRecordSet will be used.

  Returns:

  A JDBCCategoryDataset filled with the query results

  See Also:

  JFreeChart's DefaultCategoryDataset documentation for more information.

• getJDBCPieDataset

  public Defaultorg.jfree.data.general.PieDataset getJDBCPieDataset(BBjString p_connectString$, BBjString p_sql$)

  Given an SQL query, return a DefaultPieDataset filled with the desired data

  Parameters:

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

  Returns:

  A JDBCPieDataset filled with the query results

  See Also:

  JFreeChart's DefaultPieDataset documentation for more information.

• getJDBCPieDataset

  public Defaultorg.jfree.data.general.PieDataset getJDBCPieDataset(BBjString p_connectString$, BBjString p_sql$, BBjString p_mode$)

  Given an SQL query, return a DefaultPieDataset filled with the desired data

  Parameters:

  p_connectString$ The connection string with which to make the database connection

  p_sql$ The SQL query to execute

  p_mode$ A string comprised of a list of properties and values separated by commas that will be passed to the database or JDBC connection at connect time. For example: "USER=myusername, PWD=mypass, AUTOCOMMIT=N"

  Returns:

  A JDBCPieDataset filled with the query results

  See Also:

  JFreeChart's DefaultPieDataset documentation for more information.

  Since:

  BBj 16.00

• getJDBCPieDataset

  public Defaultorg.jfree.data.general.PieDataset getJDBCPieDataset(BBjRecordSet p_rs!, BBjVector p_columns!)

  Given a BBjRecordSet and a BBjVector containing the columns of interest return a DefaultCategoryDataset filled with the desired data

  Parameters:

  p_rs! The BBjRecordSet containing the data used to populate the chart

  p_columns! A BBjVector that contains an ordered list of the columns to be used for the charts's data. The entries may be a string corresponding to a field name, or a 0-based index of the column number. If null() is passed in for the p_columns! vector then the first two columns of the BBjRecordSet will be used.

  Returns:

  A JDBCPieDataset filled with the query results

  See Also:

  JFreeChart's DefaultPieDataset documentation for more information.

• getLegendFontSize

  public BBjNumber getLegendFontSize()

  Gets the font size for the chart's legend items. This is used internally to ensure that the legend item shapes are the same size as the legen item text.

  Returns:

  The font size in pixels of the legend item text

• getRGBColorFromHSLValues

  public static Color getRGBColorFromHSLValues(BBjNumber p_hue, BBjNumber p_saturation, BBjNumber p_lightness)

  Method to create a java RGB Color from its corresponding HSL (CSS) values

  Parameters:

  p_hue The hue component of the color

  p_saturation The saturation component of the color

  p_lightness The lightness component of the color

  Returns:

  A Color

• getUserFontScalingFactor

  public BBjNumber getUserFontScalingFactor()

  Gets the custom font scaling factor or the chart as set by the user in the Customize screen.

  Parameters:

  BBjNumber A multiplication factor that is applied to the base font size. If the base font is 10 points, and p_factor is 1.2, then the resultant base font size will be 12 points.

• getVectorOfJavaColorsFromDivergentHexColorStrings

  public static BBjVector getVectorOfJavaColorsFromDivergentHexColorStrings(BBjNumber p_numColors, BBjString p_colorDescStart$, BBjString p_colorDescMiddle$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaMiddle!, BBjNumber p_alphaFinish!)

  Method to create a vector of divergent colors with a specified starting, middle, and ending range.

  In order to result in a balanced divergent palette, the p_numColors must be at least 3 and should be an odd number.

  Parameters:

  p_numColors The number of colors in the resultant vector

  p_colorDescStart$ A hex color string of the starting color. An example would be "#ff0000" (Red).

  p_colorDescMiddle$ A hex color string of the middle color. An example would be "ffffff" (White).

  p_colorDescFinish$ A hex color string of the ending color. An example would be "0000ff" (Blue).

  p_alphaStart! The opacity value (0-1) of the starting color

  p_alphaMiddle! The opacity value (0-1) of the starting color

  p_alphaFinish! The opacity value (0-1) of the ending color

  Returns:

  A vector filled with colors ranging from the starting color/opacity to the middle color/opacity to the ending color/opacity.

• getVectorOfJavaColorsFromHexColorStrings

  public static BBjVector getVectorOfJavaColorsFromHexColorStrings(BBjNumber p_numColors, BBjString p_colorDescStart$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaFinish!)

  Method to create a vector of Java Colors with a specified starting and ending range

  Parameters:

  p_numColors The number of colors in the resultant vector

  p_colorDescStart$ A hex color string of the starting color. An example would be "#ff0000" (Red).

  p_colorDescFinish$ A hex color string of the ending color. An example would be "#0000ff" (Blue).

  p_alphaStart! The opacity value (0-1) of the starting color

  p_alphaFinish! The opacity value (0-1) of the ending color

  Returns:

  A vector filled with colors ranging from the starting color/opacity to the ending color/opacity.

  See Also:

  Oracle's Color documentation for more information.

• hasLegend

  public BBjNumber hasLegend()

  Indicates whether the chart has a legend

  Returns:

  0=Does not have a legend, 1=Does have a legend

• is3D

  public BBjNumber is3D()

  Indicates whether the chart is 3D or Flat (2D)

  Note: As of BBj 23.00, the Dashboard Utility uses JFreeCharts 1.5.x which removes the pseudo-3D charts. Therefore, this method will always return 0 for 23 and higher.

  Returns:

  0=Flat (2D), 1=3D, 0 for version 23 and higher

• isAreaChart

  public BBjNumber isAreaChart()

  Indicates whether the chart is an Area Chart

  Returns:

  0=Not a Area Chart, 1=Area Chart

• isBarChart

  public BBjNumber isBarChart()

  Indicates whether the chart is a Bar Chart

  Returns:

  0=Not a Bar Chart, 1=Bar Chart

• isDataSetEmpty

  public BBjNumber isDataSetEmpty()

  Indicates whether a chart's underlying dataset is empty or not

  The method traverses the underlying dataset to determine if the widget is empty or not, which is slightly different than the getNumRows() method. For example, a PieChartWidget might have 4 slices defined, all with zero values, so the getNumRows() method would return the number 4. However, the isDataSetEmpty() method would return 1, because even though there were four slices all values for the slices were zero.

  Note that if you change a widget's SQL via the setSQL() method, you would have to execute the refresh() method on the widget before executing this method, otherwise this method will be checking the widget's dataset for the previous SQL statement. Just setting the SQL statement doesn't force the widget to execute the new SQL statement and fill out the dataset, but the refresh() method does do that. This means that you could execute the setSQL() method, the refresh() method, then executing this method would check the result set of the new SQL statement.

  Returns:

  0=DataSet is not empty, 1=DataSet is empty

  Since:

  BBj 15.11

• isFlat

  public BBjNumber isFlat()

  Indicates whether the chart is 3D or Flat (2D)

  Note: As of BBj 23.00, the Dashboard Utility uses JFreeCharts 1.5.x which removes the pseudo-3D charts. Therefore, this method will always return 1 for version 23 and higher.

  Returns:

  0=3D, 1=Flat (2D), 1 for version 23 and higher

• isLineChart

  public BBjNumber isLineChart()

  Indicates whether the chart is a Line Chart

  Returns:

  0=Not a Chart, 1=Line Chart

• isPieChart

  public BBjNumber isPieChart()

  Indicates whether the chart is a Pie Chart

  Returns:

  0=Not a Chart, 1=Pie Chart

• isRingChart

  public BBjNumber isRingChart()

  Indicates whether the chart is a Ring Chart

  Returns:

  0=Not a Chart, 1= Chart

• isStackedAreaChart

  public BBjNumber isStackedAreaChart()

  Indicates whether the chart is a Stacked Area Chart

  Returns:

  0=Not a Stacked Area Chart, 1=Stacked Area Chart

• isStackedBarChart

  public BBjNumber isStackedBarChart()

  Indicates whether the chart is a Stacked Bar Chart

  Returns:

  0=Not a Stacked Bar Chart, 1=Stacked Bar Chart

• isStackedPercentageBarChart

  public BBjNumber isStackedPercentageBarChart()

  Indicates whether the chart is a Stacked Percentage Bar Chart

  Returns:

  0=Not a Stacked Percentage Bar Chart, 1=Stacked Percentage Bar Chart

• isXYChart

  public BBjNumber isXYChart()

  Indicates whether the chart is an XY Chart

  Returns:

  0=Not an XY Chart, 1=XY Chart

• lightenColor

  public static Color lightenColor(Color p_color!, BBjNumber p_fraction)

  Make a color lighter

  Parameters:

  p_color! Color to make lighter.

  p_fraction Lightness fraction (0-1).

  Returns:

  A lighter version of the original

• makeColorVectorFromCommaDelimitedHexColorString

  public static BBjVector makeColorVectorFromCommaDelimitedHexColorString(BBjString p_colorString!)

  Return a vector of java colors given a comma delimited string of hex colors

  Parameters:

  p_colorString! A comma delimited string of hex colors. An example parameter would be "#354751, #6e90b3, #efeeec" or "#345, #69b, #eee"

  Returns:

  A vector filled with Colors decoded from the hex colors

• makeColorVectorFromCommaDelimitedHexColorString

  public static BBjVector makeColorVectorFromCommaDelimitedHexColorString(BBjString p_colorString!, BBjNumber p_opacity)

  Return a vector of Java Colors given a comma delimited string of hex colors and an opacity amount to be applied to all colors

  Parameters:

  p_colorString! A comma delimited string of hex colors. An example parameter would be "#354751, #6e90b3, #efeeec" or "#345, #69b, #eee"

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

  Returns:

  A vector filled with Colors decoded from the hex colors

  See Also:

  Oracle's Color documentation for more information.

• makeLargerColorVectorByDarkening

  public static BBjVector makeLargerColorVectorByDarkening(BBjVector p_colorVector!, BBjNumber p_size)

  Gets a larger vector of colors by repeating the source vector, darkening it each time

  Parameters:

  p_colorVector! A vector filled with Colors

  p_size The desired number of Colors in the resultant vector

  Returns:

  A vector based off of the original vector with desired number of colors. The extra colors are created by repeatedly darkening the colors in the origial vector.

• makeLargerColorVectorByLightening

  public static BBjVector makeLargerColorVectorByLightening(BBjVector p_colorVector!, BBjNumber p_size)

  Gets a larger vector of colors by repeating the source vector, lightening it each time

  Parameters:

  p_colorVector! A vector filled with Colors

  p_size The desired number of Colors in the resultant vector

  Returns:

  A vector based off of the original vector with desired number of colors. The extra colors are created by repeatedly lightening the colors in the origial vector.

• makeLargerColorVectorByReducingOpacity

  public static BBjVector makeLargerColorVectorByReducingOpacity(BBjVector p_colorVector!, BBjNumber p_size)

  Gets a larger vector of colors by repeating the source vector, decreasing the opacity each time

  Parameters:

  p_colorVector! A vector filled with Colors

  p_size The desired number of Colors in the resultant vector

  Returns:

  A vector based off of the original vector with desired number of colors. The extra colors are created by repeatedly reducing the opacity of the colors in the origial vector.

• OnClearTip

  public void OnClearTip(BBjTimerEvent p_event!)

  Removes the chart's tip that is shown after clicking on a data entity. This method is called automatically and is not typically accessed via code.

  Parameters:

  p_event! The BBjTimerEvent that caused this method to execute

• refresh

  public void refresh()

  Refreshes the chart, which results in the widget showing an up-to-date version of the chart based on the underlying dataset. This is executed in response to a refresh event, and the chart is filled with curent data and all customizations are applied.

• resize

  public void resize(BBjNumber p_width, BBjNumber p_height)

  Resizes the widget using the provided with and height

  Parameters:

  p_width Width of the widget

  p_height Height of the widget

• restoreCustomColorTheme

  public void restoreCustomColorTheme()

  Restores any custom colors assigned to the chart by the program (after removing user customized theme color)

• reverseColorVector

  public static BBjVector reverseColorVector(BBjVector p_colorVector!)

  Reverses the order of the colors in a vector

  Parameters:

  p_colorVector! A vector filled with Colors

  Returns:

  The vector of modified colors

• rotateColorVector

  public static BBjVector rotateColorVector(BBjVector p_colorVector!, BBjNumber p_amount)

  Rotate the colors in a vector forwards or backwards by a specified amount.

  Supplying a positive number, such as +1, will cause the Colors to be rotated to the right, so the Color that was previously the last Color will now be the first Color. Suppliying a negative number, such as -1, will cause the Colors to be rotated to the left, so the Color that was previously the second Color will now be the first Color.

  Parameters:

  p_colorVector! A vector filled with Colors

  p_amount The desired number of Colors in the resultant vector

  Returns:

  The vector of modified colors

• saturateColor

  public static Color saturateColor(Color p_color!, BBjNumber p_fraction)

  Make a color more or less saturated

  Parameters:

  p_color! Color to modify.

  p_fraction Saturation fraction (-1 to 1). Negative numbers decrease the saturation while postive numbers increase the saturation.

  Returns:

  A more or less saturated version of the original

• save

  public void save()

  Interactively saves a screenshot of the chart as a PNG file on the client

• saveColorThemePaletteImagesToDirectory

  public static void saveColorThemePaletteImagesToDirectory(BBjString p_outputDirectory$, BBjString p_namePrefix$, BBjNumber p_width, BBjNumber p_height)

  Generates a series of PNG image files that are a visual representation of each Color Theme's palette

  Parameters:

  p_outputDirectory$ The path that will be used as the output directory where the images will be saved.

  p_namePrefix$ The prefix for the image names. A string that will be used before each theme when naming the images.

  p_width The width of each palette entry in the image

  p_height The height of each palette entry in the image

• saveColorVectorAsPaletteImage

  public static void saveColorVectorAsPaletteImage(BBjVector p_colorVector!, BBjString p_outputFilename$, BBjNumber p_width, BBjNumber p_height)

  Generates a color palette PNG image file that is a visual representation of all Colors in the supplied vector

  Parameters:

  p_colorVector! A BBjVector filled with Java Color objects.

  p_colorVector$ A string with the filename to be used for the output image file.

  p_width The width of each palette entry in the image

  p_height The height of each palette entry in the image

• setChartBackground

  public void setChartBackground(BBjNumber p_red, BBjNumber p_green, BBjNumber p_blue, BBjNumber p_opacity)

  Sets a background color for the entire chart

  Parameters:

  p_red The Red value for the color (0-1)

  p_green The Green value for the color (0-1)

  p_blue The Blue value for the color (0-1)

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartBackground

  public void setChartBackground(BBjString p_colorHexString$, BBjNumber p_opacity)

  Sets a background color for the entire chart

  Parameters:

  p_colorHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartBackground

  public void setChartBackground(Paint p_paint!)

  Sets a background paint for the entire chart

  Parameters:

  p_paint! A java.awt.paint object

  See Also:

  Oracle's Paint documentation for more information.

• setChartBackgroundGradient

  public void setChartBackgroundGradient(BBjString p_colors!, BBjNumber p_orientation)

  Sets the colors for the chart's background as a gradient

  Parameters:

  p_colors! A comma delimited string of hex descriptions of the range of colors. The colors go from top to bottom, or left to right, depending on the orientation. Ex: "#000000, $ffcc00, #ffffff".

  p_orientation The gradient's orientation, same as the charts: ORIENTATION_VERTICAL=0, ORIENTATION_HORIZONTAL=1.

• setChartBackgroundImage

  public void setChartBackgroundImage(BBjImage p_image!, BBjNumber p_opacity)

  Sets a background image for the entire chart

  Parameters:

  p_image! The image to be used for the background

  p_opacity The desired opacity value for the image (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartBackgroundImage

  public void setChartBackgroundImage(BBjString p_imageFile$, BBjNumber p_opacity)

  Sets a background image for the entire chart

  Parameters:

  p_imageFile$ A string with the path to the image to be used for the background

  p_opacity The desired opacity value for the image (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartColors

  public void setChartColors(BBjString p_colorDescStart$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaFinish!)

  Sets the colors for the chart dynamically by generating a series of colors given a starting and ending color with opacities

  The colors for the chart are considered to be dynamic, as the number of colors in the range will be regerated whenever the underlying dataset changes, such as in response to a refresh event.

  Parameters:

  p_colorDescStart$ A string with a hex description of the starting color for the range of colors. Example: "#ffccaa" or "#fca"

  p_colorDescFinish$ A string with a hex description of the last color for the range of colors.

  p_alphaStart! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_alphaFinish! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartColors

  public void setChartColors(BBjString p_colorDescStart$, BBjString p_colorDescMiddle$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaMiddle!, BBjNumber p_alphaFinish!)

  Sets the colors for the chart dynamically by generating a series of divergent colors given a starting, middle, and ending color with opacities

  The colors for the chart are considered to be dynamic, as the number of colors in the range will be regerated whenever the underlying dataset changes, such as in response to a refresh event.

  Parameters:

  p_colorDescStart$ A string with a hex description of the starting color for the range of colors. Example: "#ffccaa" or "#fca"

  p_colorDescFinish$ A string with a hex description of the last color for the range of colors.

  p_alphaStart! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_alphaFinish! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartColors

  public void setChartColors(BBjNumber p_numColors, BBjString p_colorDescStart$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaFinish!)

  Sets the colors for the chart by generating a series of colors given a starting and ending color

  Parameters:

  p_numColors The number of colors in the vector

  p_colorDescStart$ A string with a hex description of the starting color for the range of colors. Example: "#ffccaa" or "#fca"

  p_colorDescFinish$ A string with a hex description of the last color for the range of colors.

  p_alphaStart! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_alphaFinish! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartColors

  public void setChartColors(BBjNumber p_numColors, Color p_colorStart!, Color p_colorFinish!)

  Sets the colors for the chart by generating a series of colors given starting and ending Java Colors which may include an opacity

  Parameters:

  p_numColors The number of colors in the vector

  p_colorStart! A Java Color to be used as the starting color for the range of colors.

  p_colorFinish! A Java Color to be used as the last color for the range of colors.

  See Also:

  Oracle's Color documentation for more information.

• setChartColors

  public void setChartColors(BBjString p_colors!)

  Sets the colors for the chart given a fixed number of hex color descriptions in a string

  Parameters:

  p_colors! A comma delimited string of hex descriptions of the range of colors. Ex: "#000000, #ffcc00, #ffffff".

• setChartColors

  public void setChartColors(BBjString p_colors!, BBjNumber p_opacity)

  Sets the colors for the chart given a fixed number of hex color descriptions in a string and an opacity value

  Parameters:

  p_colors! A comma delimited string of hex descriptions of the range of colors. Ex: "#000000, $ffcc00, #ffffff".

  p_opacity A number from 0-1 that determines the starting opacity level for all colors (0=transparent, 1=opaque)

• setChartColors

  public void setChartColors(BBjVector p_colors!)

  Sets the colors for the chart given a fixed number of Java Colors in a BBjVector

  Parameters:

  p_colors! A vector filled with Java Color objects

  See Also:

  Oracle's Color documentation for more information.

• setChartColorTheme

  public void setChartColorTheme(BBjNumber p_colorThemeIndex)

  Sets the colors for the chart given a color theme number

  Parameters:

  p_colorThemeIndex The number of the color theme to apply to the chart

• setChartDataItemLabelFormat

  public void setChartDataItemLabelFormat(BBjString p_customLabelFormat$)

  Sets a custom label format for the chart's label items - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis

  Note that if you provide a format string that results in a label that cannot fit within the data entity, such as a bar in the BarChart, then the label may not be displayed. If this happens, you can either reduce the length of the string, reduce the font size for the chart's labels, or modify the label's placement. To change the label's font size, you can execute the ChartWidget::setChartFontSizes() method, specifying a smaller-than-default value for the label size. For example:

  myBarChart!.setChartFontSizes(0, 0, 0, 9, 0, 0, 0) will only set the label size to 9px while leaving the other chart fonts at their default sizes.

  See the related ChartWidget::setChartDataItemLabels() method to modify the label's position.

  Parameters:

  p_customLabelFormat$ A string defining the desired label format. The default label format is {2}. An example label format would be "{2}%" and would display a bar's value as "45%" instead of the default "45"

  • {0} = The rowKey$ of the dataset entry
  • {1} = The colKey$, or domain value of the dataset entry
  • {2} = The value, or range value of the dataset

  See Also:

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartDataItemLabelFormat

  public void setChartDataItemLabelFormat(BBjString p_customLabelFormat$, NumberFormat p_numberFormat!, NumberFormat p_percentageFormat!)

  Sets a custom label format for the chart's label items by providing a label string and NumberFormatters for the number and percentage fields - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis

  A sample use case would be:

  
   myBarChart!.setChartDataItemLabelFormat("{1}: {2}", java.text.NumberFormat.getCurrencyInstance(), java.text.NumberFormat.getPercentInstance())
   

  which would cause the label to display the key followed by the value formatted as currency. That way it would show up in a format similar to:

  
   Current: $218.10
   

  If the currency format is not specified, the value would display as "218.0" which does not include the pennies or currency unit.

  Note that if you provide a format string that results in a label that cannot fit within the data entity, such as a bar in the BarChart, then the label may not be displayed. If this happens, you can either reduce the length of the string, reduce the font size for the chart's labels, or modify the label's placement. To change the label's font size, you can execute the ChartWidget::setChartFontSizes() method, specifying a smaller-than-default value for the label size. For example:

  myBarChart!.setChartFontSizes(0, 0, 0, 9, 0, 0, 0) will only set the label size to 9px while leaving the other chart fonts at their default sizes.

  See the related ChartWidget::setChartDataItemLabels() method to modify the label's position.

  Parameters:

  p_customLabelFormat$ A string defining the desired label format. The default label format is {2}. An example label format would be "{2}%" and would display a bar's value as "45%" instead of the default "45"

  • {0} = The rowKey$ of the dataset entry
  • {1} = The colKey$, or domain value of the dataset entry
  • {2} = The value, or range value of the dataset

  p_numberFormat! A NumberFormat object that formats the range value {2} of the dataset entry as a number with the specified format. For an XYChartWidget, this provides the formatter for the x-values {1}.

  p_percentageFormat! A NumberFormat object that formats the range value {2} of the dataset entry as a percentage with the specified format. For an XYChartWidget, this provides the formatter for the y-values {2}.

  See Also:

  Oracle's NumberFormat documentation for more information.

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartDataItemLabels

  public void setChartDataItemLabels(BBjString p_colorHexString$)

  Enables data item labels in a chart, displaying the range value in the specified color - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis

  This method signature only specifies the label text color and uses default values for the label's position. See the other method signatures to control the label position.

  Note that the legacy setLabelsInBarChartColor() method also enables data item labels but uses default positioning and only works with BarCharts.

  See the related ChartWidget::setChartDataItemLabelFormat() method to modify the label's formatting.

  Parameters:

  p_colorHexString$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  See Also:

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartDataItemLabels

  public void setChartDataItemLabels(BBjString p_colorHexString$, BBjNumber p_labelLocation)

  Enables data item labels in a chart, displaying the range value in the specified color and position - note that this applies only to category-based charts (BarCharts, LineCharts, AreaCharts) and XYCharts that have a domain and range axis

  This method signature offers a simplified positioning model that places the labels vertically relative to the data item. See the other method signature that offers complete control over the label position but uses the JFreeChart's custom classes for positioning parameters.

  Note that the legacy setLabelsInBarChartColor() method also enables data item labels but uses default positioning and only works with BarCharts.

  See the related ChartWidget::setChartDataItemLabelFormat() method to modify the label's formatting.

  Parameters:

  p_colorHexString$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  p_labelLocation The location of the label relative to the data item as defined by one of the following static fields

  • ChartWidget.getDATA_ITEM_LABEL_POSITION_INSIDE_CENTER() - inside the middle of the data item, e.g. inside the bar centered vertically and horizontally (the default location when the location is not specified with a different method signature)
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_INSIDE_TOP() - inside the top of the data item, e.g. inside the bar at the top
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_OUTSIDE_TOP() - outside the top of the data item, e.g. outside the bar at the top
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_INSIDE_BOTTOM() - inside the bottom of the data item, e.g. inside the bar at the bottom
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_OUTSIDE_BOTTOM() - outside the bottom of the data item, e.g. below an XYChart's data point
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_INSIDE_LEFT() - inside the left of the data item, e.g. inside the bar centered vertically at the left side
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_OUTSIDE_LEFT() - outside the top of the data item, e.g. outside the bar centered vertically at the left side
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_INSIDE_RIGHT() - inside the bottom of the data item, e.g. inside the bar centered vertically at the right side
  • ChartWidget.getDATA_ITEM_LABEL_POSITION_OUTSIDE_RIGHT() - outside the bottom of the data item, e.g. outside the bar centered vertically at the right side

  See Also:

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartDataItemLabels

  public void setChartDataItemLabels(BBjString p_colorHexString$, ItemLabelAnchor p_itemLabelAnchor!, TextAnchor p_textAnchor!, TextAnchor p_rotationAnchor!, BBjNumber p_angle)

  Enables data item labels in a chart, displaying the range value in the specified color and position - note that this applies only to category-based charts, such as BarCharts, LineCharts, AreaCharts, etc. that have a domain and range axis.

  This method signature offers the developer complete control over the label's position, but uses the JFreeChart's custom classes for positioning. See other method signatures for simplified positioning.

  Note that the legacy setLabelsInBarChartColor() method also enables data item labels but uses default positioning and only works with BarCharts.

  See the related ChartWidget::setChartDataItemLabelFormat() method to modify the label's formatting.

  The rectangle anchor will typically be a value like RectangleAnchor.TOP, RectangleAnchor.CENTER, RectangleAnchor.TOP_LEFT, RectangleAnchor.BOTTOM_RIGHT.

  The text anchor will typically be a value like TextAnchor.TOP, TextAnchor.CENTER, TextAnchor.CENTER_LEFT, TextAnchor.CENTER_RIGHT, TextAnchor.TOP_LEFT, TextAnchor.BOTTOM_RIGHT.

  Parameters:

  p_colorHexString$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  p_itemLabelAnchor! The anchor point for the label's rectangle (passing in null() will use the default of ItemLabelAnchor.CENTER)

  p_textAnchor! The anchor point for the label's text in the rectangle (passing in null() will use the default of TextAnchor.CENTER)

  p_rotationAnchor! The anchor point for the label's rotation (passing in null() will use the default of TextAnchor.CENTER)

  p_angle The angle of rotation in degrees for the label (passing in 0 will result in the default of non-rotated text)

  See Also:

  RectangleAnchor for more information on anchor values

  TextAnchor for more information on anchor values

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartDomainAxisFontScaling

  public void setChartDomainAxisFontScaling(BBjNumber p_scaleFonts)

  Sets whether the font for the domain axis should be scaled down when the axis contains a large number of entries

  Parameters:

  p_scaleFonts A number that indicates whether to scale the fonts or not. 0=DoNotScaleFonts, 1=ScaleFonts (default)

• setChartDomainAxisFormat

  public void setChartDomainAxisFormat(BBjString p_format$)

  Sets a format for the XYChart's domain axis (x-axis) numbers, allowing you for format numbers with digits, decimals, spaces, separators, currency symbols, and arbitrary text - note that this applies only to an XYChart

  Internally the JFreeCharts use a Java NumberFormatter to define a custom format. This method bridges the gap and allows you to specify a format mask using BBj's masking characters, which will then be converted to a Java NumberFormat automatically. Special mask characters such as #, 0, ., $, and & should be successfully converted.

  A few of the commly used special symbols are:

  • 0   Digit
  • #   Digit, zero shows as absent
  • .   Decimal separator
  • ,    Grouping separator
  • -   Minus sign
  • %   Multiply by 100 and show as percentage
  • &   Currency sign
  • '   Escape any of the above special characters
  • ''   Single quote

  Some examples would be:

  
  widget!.setChartDomainAxisFormat("Total: $##0.00") -> Total: $12.34
  widget!.setChartDomainAxisFormat("&##0M") -> $123M if the default locale of the JVM yields a dollar sign for the currency symbol
  widget!.setChartDomainAxisFormat("&##0M") -> €123M if the default locale of the JVM yields a euro for the currency symbol
  

  Parameters:

  p_format$ A string that defines the desired format using BBj's masking characters

  See Also:

  Numeric Output

  Numeric Output - BBj

  DecimalFormat

  Since:

  BBj 19.00

• setChartDomainAxisFormat

  public void setChartDomainAxisFormat(DecimalFormat p_format!)

  Sets a format for the XYChart's domain axis (x-axis) numbers, allowing you for format numbers with digits, decimals, spaces, separators, currency symbols, and arbitrary text - note that this applies only to an XYChart

  Parameters:

  p_format! A java DecimalFormat that defines the desired format

  See Also:

  Oracle's DecimalFormat documentation for more information.

  Since:

  BBj 19.00

• setChartDomainAxisMargins

  public void setChartDomainAxisMargins(BBjNumber p_lowerMargin, BBjNumber p_upperMargin)

  Sets the lower and upper margins on the domain axis as a percentage of the length of the axis

  Parameters:

  p_lowerMargin The lower, or left side in vertical orientation, margin as a percentage of the axis length. For example, 0.05 would indicate a margin that is 5% of the total length.

  p_upperMargin The upper, or right side in vertical orientation, margin as a percentage of the axis length. For example, 0.05 would indicate a margin that is 5% of the total length.

• setChartDomainAxisNumLines

  public void setChartDomainAxisNumLines(BBjNumber p_numLines)

  Sets maximum number of lines used to display a label on the chart's domain (x axis) when applicable

  The default number of lines is one. You can use this method to increase the number of lines available for a domain label. When two or more lines are specified, the label may wrap to fill the available space. Setting this value to an integer greater than one may cause the labels to be wrapped in unexpected places. Note that this only applies to charts that have a domain axes, so it will have no effect on a PieChart, for example.

  Parameters:

  p_numLines An integer that determines the maximum number of lines to use for each label. Possible values are integers greater than zero.

• setChartDomainAxisTitle

  public void setChartDomainAxisTitle(BBjString p_title$)

  Sets the title for the domain axis

  This can be used to dynamically change the axis title, such as in response to a refresh event. Even if the chart was originally created without this axis title, calling this method will add the title to the chart.

  Note that for an XYChartWidget, setting the domain title via setDomainAxisLabels() will override this method.

  Parameters:

  p_title$ The new title for the domain axis

  Since:

  BBj 17.00

• setChartDomainAxisVisible

  public void setChartDomainAxisVisible(BBjNumber p_visible)

  Sets whether the domain axis is visible or not

  Parameters:

  p_visible A number that indicates the axis visibility. 0=Invisible, 1=visible (default)

• setChartDomainMarker

  public void setChartDomainMarker(BBjString p_key$, BBjString p_colorDesc$, BBjNumber p_opacity, BBjNumber p_markerType)

  Sets a threshold marker for the chart's domain. Markers are typically added to plots to highlight or draw attention to specific values.

  Note that the addChartDomainMarker() method allows you to add multiple threshold markers specifying the value, color, label, label color, and label position.

  Typically a marker will be drawn by the renderer as a line perpendicular to the domain axis, however this is entirely up to the renderer. Note that this does not apply to charts without a domain, such as a PieChart or RingChart

  Parameters:

  p_key$ The column key corresponding to the point on the domain at which the marker will be placed

  p_colorDesc$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  p_opacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_markerType A number that determines how the marker will be drawn. 0=Region, 1=Line

• setChartDomainMarker

  public void setChartDomainMarker(BBjString p_key$, BBjString p_colorDesc$, BBjNumber p_opacity)

  Sets a threshold marker for the chart's domain. Markers are typically added to plots to highlight or draw attention to specific values.

  Typically a marker will be drawn by the renderer as a line perpendicular to the domain axis, however this is entirely up to the renderer. Note that this does not apply to charts without a domain, such as a PieChart or RingChart

  Parameters:

  p_key$ The column key corresponding to the point on the domain at which the marker will be placed

  p_colorDesc$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  p_opacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartDomainMarker

  public void setChartDomainMarker(BBjString p_key$, Color p_color!)

  Sets a threshold marker for the chart's domain. Markers are typically added to plots to highlight or draw attention to specific values.

  Typically a marker will be drawn by the renderer as a line perpendicular to the domain axis, however this is entirely up to the renderer. Note that this does not apply to charts without a domain, such as a PieChart or RingChart

  Parameters:

  p_key$ The column key corresponding to the point on the domain at which the marker will be placed

  p_color A Java Color that indicates the marker's color

• setChartEmptyDisplayImage

  public void setChartEmptyDisplayImage(BBjString p_imageFile$)

  Sets the image that will appear in the widget if the chart contains no data

  Some charts, like the pie chart, do not display anything at all when the underlying dataset is empty. To avoid the widget from appearing blank, you may specify an image or text that will be placed on top of the empty 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: ChartWidget::setChartEmptyDisplayText()

  Parameters:

  p_imageFile$ A string with the path to an image to display over the empty chart. The path may be fully qualified or rely on the prefix.

  Since:

  BBj 16.00

• setChartEmptyDisplayText

  public void setChartEmptyDisplayText(BBjString p_displayText$)

  Sets the text that will appear in the widget if the chart contains no data.

  Some charts, like the pie chart, do not display anything at all when the underlying dataset is empty. To avoid the widget from appearing empty, you may specify an image or text that will be placed on top of the empty 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: ChartWidget::setChartEmptyDisplayImage()

  Parameters:

  p_displayText$ A string with the text to display instead of the empty chart

  Since:

  BBj 16.00

• setChartFontColor

  public void setChartFontColor(BBjString p_colorHexString$, BBjNumber p_opacity)

  Sets the color for the fonts used in the chart for the labels, legend, title, etc.

  Parameters:

  p_shadowHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartFontColor

  public void setChartFontColor(BBjColor p_color!, BBjNumber p_opacity)

  Sets the color for the fonts used in the chart for the labels, legend, title, etc.

  Parameters:

  p_color! A BBjColor

  p_opacity The desired opacity value (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartFontColors

  public void setChartFontColors(BBjString p_colors!, BBjNumber p_opacity)

  Sets the colors for the fonts used in the chart for the labels, legend, title, etc. by providing hex color strings in the format of "#ff00cc" for each color.

  Note that specifying specific font colors will override any colors that may have been set via the setChartFontColor() method.

  Note if you specify an empty string for any element, then the default color will be used for that element. This makes it easy to modify individual element font colors in a single method. For example, the following code will set all fonts to black (hex 0) with an opacity of 50% resulting in a light gray color. The next line will then override those colors and set the title to a dark blue, the domain to a dark red, and the range to a dark green color.

  
   widget!.setChartFontColor("#000000", .5)
   widget!.setChartFontColors("#1a4065, , , , #732626, #267326, ", 0.9)
   

  Note that all colors are hex color strings. An example would be "#ff00cc" or "#f0c"

  Parameters:

  p_titleColor The font color for the title

  p_subtitleColor The font color for the subtitles (domain/range titles)

  p_legendItemColor The font color for the legend items

  p_labelColor The font color for the labels (pie chart labels, and embedded pie or bar chart labels, data item labels for category-based and XYCharts)

  p_domainItemColor The font color for the items on the domain axis

  p_rangeItemColor The font color for the items on the range axis

  p_annotationColor The font color for the annotations

• setChartFontFile

  public void setChartFontFile(BBjString p_fontFile$)

  Sets a font for the chart. This allows you to set the font used in the chart for the labels, legend, title, etc.

  This method calls the setChartFontFile() method specifying true for the p_throwError parameter

  Parameters:

  p_fontFile$ A string that contains the path to the desired font file.

• setChartFontFile

  public void setChartFontFile(BBjString p_fontFile$, BBjNumber p_throwError)

  Sets a font for the chart. This allows you to set the font used in the chart for the labels, legend, title, etc.

  You may specify any font given a fully qualified path, a font name or path that can be found via the current PREFIX setting, or any font located in the /utils/dashboard/fonts directory.

  The following code sets the widget's font by specifying the name of the font file that's located in the dashboard utility's font directory:

  
   widget!.setChartFontFile("SourceSansPro-Regular.ttf")
   

  The following code sets the widget's font by specifying the fully qualified font name:

  
   widget!.setChartFontFile("/Users/bbj/Fonts/TypewriterKeys.ttf")
   

  Parameters:

  p_fontFile$ A string that contains the path to the desired font file.

  p_throwError A number indicating whether to throw an error if the specified font file is not valid. 0=No Error, 1=Throw Error

• setChartFontSizes

  public void setChartFontSizes(BBjNumber p_titleSize, BBjNumber p_subtitleSize, BBjNumber p_legendItemSize, BBjNumber p_labelSize, BBjNumber p_domainItemSize, BBjNumber p_rangeItemSize, BBjNumber p_annotationSize)

  Sets the size for the various fonts used in the chart for the labels, legend, title, etc.

  Note that if you specify a font size of 0 for any element, then the default size will be used for that element. This makes it easy to modify individual element font sizes in a single method. For example, the following code will set the domain font size to 10, the range font size to 12, and will leave all other elements at their default font size.

  
   widget!.setChartFontSizes(0, 0, 0, 0, 10, 12, 0)
   

  Note that specifying specific element font sizes will still be affected by any font scaling that may have been set via the setFontScaling() method.

  Parameters:

  p_titleSize The font size for the title

  p_subtitleSize The font size for the subtitles (domain/range titles)

  p_legendItemSize The font size for the legend items

  p_labelSize The font size for the labels (pie chart labels, and embedded pie or bar chart labels)

  p_domainItemSize The font size for the items on the domain axis

  p_rangeItemSize The font size for the items on the range axis

  p_annotationSize The font size for the annotations

• setChartFontStyles

  public void setChartFontStyles(BBjNumber p_titleStyle, BBjNumber p_subtitleStyle, BBjNumber p_legendItemStyle, BBjNumber p_labelStyle, BBjNumber p_domainItemStyle, BBjNumber p_rangeItemStyle, BBjNumber p_annotationStyle)

  Sets the style (plain/bold/italic) for the various fonts used in the chart for the labels, legend, title, etc.

  Because the chart's fonts are ultimately used by the Java JFreeChart library, the values for the possible styles are the same constants used for the Java Font object, which are listed below:

  • PLAIN = 0
  • BOLD = 1
  • ITALIC = 2

  They also correspond to the plain/bold/italic constants used with the BBjFont object. This means that if you want to set the style for an element to ITALIC, you may enter a number, e.g. 2, a BBjFont constant, e.g. BBjFont.FONT_ITALIC, or a java.awt.Font constant, e.g. Font.ITALIC. The font styles are additive, so you can specify that a font be both bold and italic by specifying the number 3, BBjFont.FONT_BOLD+BBjFont.FONT_ITALIC, or Font.BOLD+Font.ITALIC.

  If you specify a font style of -1 for any element in the parameter list, then the default style will be used for that element. This makes it easy to modify individual element font styles in a single method. For example, the following code will set the title font style to ITALIC, the label font to BOLD, and will leave all other elements at their default style.

  
   widget!.setChartFontStyles(BBjFont.FONT_ITALIC, -1, -1, BBjFont.FONT_BOLD, -1, -1, -1)
   

  Parameters:

  p_titleStyle The font style for the title (-1, 0, 1, or 2)

  p_subtitleStyle The font style for the subtitles (domain/range titles) (-1, 0, 1, or 2)

  p_legendItemStyle The font style for the legend items (-1, 0, 1, or 2)

  p_labelStyle The font style for the labels (pie chart labels, and embedded pie or bar chart labels) (-1, 0, 1, or 2)

  p_domainItemStyle The font style for the items on the domain axis (-1, 0, 1, or 2)

  p_rangeItemStyle The font style for the items on the range axis (-1, 0, 1, or 2)

  p_annotationStyle The font style for the annotations (-1, 0, 1, or 2)

  See Also:

  HTML-formatted sample program

  Downloadable sample program

  Since:

  BBj 19.00

• setChartLegendBackground

  public void setChartLegendBackground(BBjString p_colorHexString$, BBjNumber p_opacity)

  Applies the background color for the legend

  Parameters:

  p_colorHexString$ A hex color string for the legend background color. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartLegendFrame

  public void setChartLegendFrame(BBjNumber p_width, BBjString p_colorHexString$, BBjNumber p_opacity)

  Applies the border width and color for the legend

  Parameters:

  p_width The width of the border

  p_colorHexString$ A hex color string for the border color. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setChartLegendPadding

  public void setChartLegendPadding(BBjNumber p_top, BBjNumber p_right, BBjNumber p_bottom, BBjNumber p_left)

  Sets the padding between the legend border and the legend items

  Parameters:

  p_top The padding amount for the top of the chart in pixels

  p_right The padding amount for the right side of the chart in pixels

  p_bottom The padding amount for the bottom of the chart in pixels

  p_left The padding amount for the left side of the chart in pixels

• setChartLegendShape

  public void setChartLegendShape(BBjNumber p_shape, BBjNumber p_outlineWidth, Color p_outlineColor!)

  Sets the parameters for a chart's legend shape.

  Note that due to the underlying JFreeChart implementation, this method works on all chart types EXCEPT for PieCharts and charts that extend a PieChart, such as a RingChart.

  The possible values for the shape are

  • Circle
  • Square
  • Rectangle
  • RoundedRectangle
  • Capsule
  • Ellipse
  • Diamond

  A sample use case would be to set the shape to a Capsule with a 2 pixel red border:

  
   barChartWidget!.setChartLegendShape(ChartWidget.getLEGENDSHAPE_CAPSULE(), 2, ChartWidget.getJavaColor("#ff0000"))
   

  Parameters:

  p_shape The legend's shape (a constant defined in the ChartWidget class)

  p_outlineWidth The stroke, or outline width of the shape in pixels

  p_outlineColor! The Java Color used to paint the shape's outline

• setChartLegendShape

  public void setChartLegendShape(BBjNumber p_shape, BBjNumber p_outlineWidth, BBjString p_colorHexString$, BBjNumber p_opacity)

  Sets the parameters for a chart's legend shape.

  Note that due to the underlying JFreeChart implementation, this method works on all chart types EXCEPT for PieCharts and charts that extend a PieChart, such as a RingChart.

  The possible values for the shape are

  • Circle
  • Square
  • Rectangle
  • RoundedRectangle
  • Capsule
  • Ellipse
  • Diamond

  A sample use case would be to set the shape to a Capsule with a 2 pixel red border:

  
   barChartWidget!.setChartLegendShape(ChartWidget.getLEGENDSHAPE_CAPSULE(), 2, ChartWidget.getJavaColor("#ff0000"))
   

  Parameters:

  p_shape The legend's shape (a constant defined in the ChartWidget class)

  p_outlineWidth The stroke, or outline width of the shape in pixels

  p_colorHexString$ A hex color string for the shape's outline color. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the outline color (0-1). 0 = Fully Transparent, 1 = Fully Opaque.

• setChartLegendShapeRadius

  public void setChartLegendShapeRadius(BBjNumber p_radius)

  Sets the radius for a chart's legend shape (typically a circle) in pixels, overriding the default.

  Parameters:

  p_radius The circle's radius in pixels

• setChartLegendShapeRadiusScalingFactor

  public void setChartLegendShapeRadiusScalingFactor(BBjNumber p_factor)

  Sets a scaling factor for the radius of a chart's legend shape (typically a circle) as a percentage of the orginal value, overriding the default.

  Specifying a scaling factor less than 1 decreases the size of the legend shapes. Specifying a scaling factor greater than 1 increases size of the legend shapes. Note that the legend shape must be an integer, although the scaling factor does not need to be an integer. This means that you may provide a floating point scaling factor, but the final shape radius will be rounded to the nearest integer.

  Parameters:

  p_factor The amount to scale the legend shape radius by. Values <1 make it smaller and values >1 make it bigger.

• setChartMaximumDomainLabelWidthRatio

  public void setChartMaximumDomainLabelWidthRatio(BBjNumber p_widthRatio)

  Sets a scaling factor that affects the domain axis label width.

  The default is 1.5, and higher values will cause the labels to be more likely to overrun each other instead of being truncated. Values from 1 to 3 should produce reasonably good results

  Parameters:

  p_widthRatio A number that indicates domain width ratio

• setChartPadding

  public void setChartPadding(BBjNumber p_top, BBjNumber p_right, BBjNumber p_bottom, BBjNumber p_left)

  Sets the padding between the chart border and the chart drawing area

  Parameters:

  p_top The padding amount for the top of the chart in pixels

  p_right The padding amount for the right side of the chart in pixels

  p_bottom The padding amount for the bottom of the chart in pixels

  p_left The padding amount for the left side of the chart in pixels

• setChartPlotShadow

  public void setChartPlotShadow(BBjNumber p_size, BBjString p_colorString!, BBjNumber p_opacity, BBjNumber p_distance, BBjNumber p_angle)

  Sets a diffused shadow for the plot, which adds a shadow to the plot contents (bars, lines, pie slices, etc.).

  Note that this does not work properly with 3DPieCharts as of JFreeCharts 1.0.19

  Parameters:

  p_size The shadow size in pixels which affects the shadows diffusion. Smaller sizes make smaller, more crisp shadows. Larger sizes result in larger, more blurry shadows.

  p_colorString! A string with a hex description of the shadow color. Example: "#ffccaa" or "#fca"

  p_opacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_distance The shadow offset distance in pixels

  p_angle The shadow offset angle in degrees

• setChartRangeAxisFormat

  public void setChartRangeAxisFormat(BBjString p_format$)

  Sets a format for the chart's range axis (y-axis) numbers, allowing you to format numbers with digits, decimals, spaces, separators, currency symbols, and arbitrary text.

  Note that this method overrides any other axis formatting such as the setChartRangeAxisToCurrency(), setChartRangeAxisToCurrencyWithFractionalDigits(), and setChartRangeAxisToPercent() methods. To clear this format and use another formatting style like setChartRangeAxisToCurrency(), call this method first specifying an empty string for the p_format$ parameter.

  Internally the JFreeCharts use a Java NumberFormatter to define a custom format. This method bridges the gap and allows you to specify a format mask using BBj's masking characters, which will then be converted to a Java NumberFormat automatically. Special mask characters such as #, 0, ., $, and & should be successfully converted.

  A few of the commonly used special symbols are:

  • 0   Digit
  • #   Digit, zero shows as absent
  • .   Decimal separator
  • ,    Grouping separator
  • -   Minus sign
  • %   Multiply by 100 and show as a percentage
  • &   Currency sign
  • '   Escape any of the above special characters
  • ''   Single quote

  Some examples would be:

  
  widget!.setChartRangeAxisFormat("Total: $##0.00") -> Total: $12.34
  widget!.setChartRangeAxisFormat("&##0M") -> $123M if the default locale of the JVM yields a dollar sign for the currency symbol
  widget!.setChartRangeAxisFormat("&##0M") -> €123M if the default locale of the JVM yields a euro for the currency symbol
  

  Parameters:

  p_format$ A string that defines the desired format using BBj's masking characters

  See Also:

  Numeric Output

  Numeric Output - BBj

  DecimalFormat

• setChartRangeAxisFormat

  public void setChartRangeAxisFormat(DecimalFormat p_format!)

  Sets a format for the chart's range axis (y-axis) numbers, allowing you for format numbers with digits, decimals, spaces, separators, currency symbols, and arbitrary text.

  Note that this method overrides any other axis formatting such as the setChartRangeAxisToCurrency(), setChartRangeAxisToCurrencyWithFractionalDigits(), and setChartRangeAxisToPercent() methods. To clear this format and use another formatting style like setChartRangeAxisToCurrency(), call this method first specifying null() for the p_format! parameter.

  Parameters:

  p_format! A java DecimalFormat that defines the desired format

  See Also:

  Oracle's DecimalFormat documentation for more information.

• setChartRangeAxisMinimumSize

  public void setChartRangeAxisMinimumSize(BBjNumber p_minimumSize)

  Sets the minimum size allowed for the axis range when it is automatically calculated

  Parameters:

  p_minimumSize A number that indicates the numeric range that the range axis will span. The number must be greater than 0.

• setChartRangeAxisTitle

  public void setChartRangeAxisTitle(BBjString p_title$)

  Sets the title for the range axis

  This can be used to dynamically change the axis title, such as in response to a refresh event. Even if the chart was originally created without this axis title, calling this method will add the title to the chart.

  Parameters:

  p_title$ The new title for the range axis

  Since:

  BBj 17.00

• setChartRangeAxisToCurrency

  public void setChartRangeAxisToCurrency()

  Sets the range axis to show its values formatted as currency for the current locale

  Use the setChartRangeAxisToCurrencyWithFractionalDigits() method to use a currency format and specify how many fractional digits to display.

• setChartRangeAxisToCurrencyWithFractionalDigits

  public void setChartRangeAxisToCurrencyWithFractionalDigits(BBjNumber p_fractionDigits)

  Sets the range axis to show its values formatted as currency for the current locale with the provided number of fractional digits.

  The number of fractional digits will usually be in the range of 0 to 3.

  Parameters:

  p_fractionDigits The number of fractional digits to display. A value of 0 indicates that only integer values will be used, whereas a value of 2 indicates that two fractional digits should be included. This translates to showing pennies when the locale determines that the currency value uses dollars.

• setChartRangeAxisToPercent

  public void setChartRangeAxisToPercent()

  Sets the range axis to show its values formatted as a percentage, which multiplies the values by 100 and appends the percent sign

• setChartRangeAxisUseIntegers

  public void setChartRangeAxisUseIntegers(BBjNumber p_useIntegers)

  Sets whether the range axis is limited to integer values or not

  Parameters:

  p_useIntegers A number that indicates whether to use integers or not. 0=Standard (default), 1=Integers

• setChartRangeAxisVisible

  public void setChartRangeAxisVisible(BBjNumber p_visible)

  Sets whether the range axis is visible or not

  Parameters:

  p_visible A number that indicates the axis visibility. 0=Invisible, 1=visible (default)

• setChartRangeColors

  public void setChartRangeColors(BBjString p_colorDescStart$, BBjString p_colorDescFinish$, BBjNumber p_alphaStart!, BBjNumber p_alphaFinish!)

  Sets the range Paint for each bar in the chart

  Parameters:

  p_colorDescStart$ A string with a hex description of the starting color for the range of colors. Example: "#ffccaa" or "#fca"

  p_colorDescFinish$ A string with a hex description of the last color for the range of colors.

  p_alphaStart! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

  p_alphaFinish! A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartRangeColors

  public void setChartRangeColors(BBjString p_colors!)

  Sets the colors for the chart's bars as a gradient going across the range

  Parameters:

  p_colors! A comma delimited string of hex descriptions of the range of colors. Ex: "#000000, $ffcc00, #ffffff".

• setChartRangeColors

  public void setChartRangeColors(BBjString p_colors!, BBjNumber p_opacity)

  Sets the colors for the chart's bars as a gradient going across the range

  Parameters:

  p_colors! A comma delimited string of hex descriptions of the range of colors. Ex: "#000000, $ffcc00, #ffffff".

  p_opacity A number from 0-1 that determines the starting opacity level for all colors (0=transparent, 1=opaque)

• setChartRangeColors

  public void setChartRangeColors(BBjVector p_colors!)

  Sets the range Paint for each bar in the chart

  Parameters:

  p_colors! A BBjVector filled with Java Color objects

• setChartRangeMarker

  public void setChartRangeMarker(BBjNumber p_value, BBjString p_colorDesc$, BBjNumber p_opacity)

  Sets a threshold marker for the chart's range. Markers are typically added to plots to highlight or draw attention to specific values.

  Note that the addChartRangeMarker() method allows you to add multiple threshold markers specifying the value, color, label, label color, and label position.

  Typically a marker will be drawn by the renderer as a line perpendicular to the range axis, however this is entirely up to the renderer. Note that this does not apply to charts without a range, such as a PieChart or RingChart.

  Parameters:

  p_value The position (determined by value) at which the marker will be placed

  p_colorDesc$ A string with a hex description of the color for marker. Example: "#ffccaa" or "#fca"

  p_opacity A number from 0-1 that determines the starting opacity level (0=transparent, 1=opaque)

• setChartRangeMarker

  public void setChartRangeMarker(BBjNumber p_value, Color p_color!)

  Sets a threshold marker for the chart's range. Markers are typically added to plots to highlight or draw attention to specific values.

  Typically a marker will be drawn by the renderer as a line perpendicular to the range axis, however this is entirely up to the renderer. Note that this does not apply to charts without a range, such as a PieChart or RingChart

  Parameters:

  p_value The position (determined by value) at which the marker will be placed

  p_color A Java Color that indicates the marker's color

• setChartTitle

  public void setChartTitle(BBjString p_chartTitle$)

  Sets the title of the chart

  Parameters:

  p_chartTitle$ A string with the title to be displayed in the chart

• setChartTitles

  public void setChartTitles(BBjString p_chartTitle$, BBjString p_chartDomainTitle$, BBjString p_chartRangeTitle$)

  Sets the main chart title, domain title, and range title for all category charts (bar, line, area, etc.)

  This can be called at any time on the widget and facilitates changing the titles on a chart in response to a filter or click event which may cause the SQL and data to change. This method may be called on a PieChartWidget as well, but only the main title will be changed.

  Parameters:

  p_chartTitle$ A string with the main title to be displayed in the chart

  p_chartDomainTitle$ A string with the domain title to be displayed in the chart

  p_chartRangeTitle$ A string with the range title to be displayed in the chart

  Since:

  BBj 15.11

• setDevicePixelRatio

  public void setDevicePixelRatio(BBjNumber p_pixelRatio)

  Sets the screen's device pixel ratio used for modifying ChartWidgets

  Parameters:

  p_pixelRatio A BBjNumber specifying the screen's pixel ratio to use when creating the widget's graphics

  See Also:

  The BBjWidget's DevicePixelRatio static field variable for more information.

• setFontScalingFactor

  public void setFontScalingFactor(BBjNumber p_factor)

  Sets a font scaling factor for the chart via a dashboard program. This allows you to increase or decrease the size of all fonts used in the chart for the labels, legend, title, etc.

  Specifying a scaling factor less than 1 decreases the fonts. Specifying a scaling factor greater than 1 increases the fonts.

  Parameters:

  p_factor A multiplication factor that will be applied to the base font size. If the base font is 10 points, and p_factor is 1.2, then the resultant base font size will be 12 points.

• setGradientShadingAmount

  public void setGradientShadingAmount(BBjNumber p_gradientShadingAmount)

  Sets the gradient shanding amount for the entire chart. The default is 0.5, so values greater than this will have a more pronounced gradient on the chart (the bars, for instance). Setting it to zero removes the gradient effect entirely.

  Parameters:

  p_gradientShadingAmount The gradient amount for shading

• setLegendBackground

  public void setLegendBackground(BBjString p_colorHexString$, BBjNumber p_opacity)

  Sets a background color for the legend

  Parameters:

  p_colorHexString$ A hex color string for the legend background color. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the color (0-1). 0 = Fully Transparent, 1 = Fully Opaque.

• setLegendBackground

  public void setLegendBackground(Paint p_paint!)

  Sets a background paint for the legend

  Parameters:

  p_paint! A java.awt.paint object

  See Also:

  Oracle's Paint documentation for more information.

• setLegendLabelFormat

  public void setLegendLabelFormat(BBjString p_customLabelFormat$)

  Define a custom label format for chart's legend items

  Parameters:

  p_customLabelFormat$ A string defining the desired label format An example label format would be "{0}: {1} ({2})" and would display as "Apple: 40 (40%)" {0} = The text portion of the dataset entry {1} = The numeric portion of the dataset entry {2} = The numeric portion of the dataset entry followed by a percent sign

• setLegendLabelFormat

  public void setLegendLabelFormat(BBjString p_customLabelFormat$, NumberFormat p_numberFormat!, NumberFormat p_percentageFormat!)

  Define a custom label format for the chart's legend items by providing a label string and NumberFormatters for the number and percentage fields.

  A sample use case would be:

  
   widget!.setLegendLabelFormat("{0}: {1}", java.text.NumberFormat.getCurrencyInstance(), java.text.NumberFormat.getPercentInstance())
   

  which would cause the label to display the key followed by the value formatted as currency. That way it would show up in a format similar to:

  
   Current: $218.10
   

  If the currency format is not specified, the value would display as "218.0" which does not include the pennies or currency unit.

  Parameters:

  p_customLabelFormat$ A string defining the desired label format An example label format would be "{0}: {1} ({2})" and would display as "Apple: 40 (40%)"

  • {0} = The text portion of the dataset entry
  • {1} = The numeric portion of the dataset entry
  • {2} = The numeric portion of the dataset entry followed by a percent sign

  p_numberFormat! A NumberFormat object that formats the numeric portion {1} of the dataset entry

  p_percentageFormat! A NumberFormat object that formats the percentage portion {2} of the dataset entry

  See Also:

  Oracle's NumberFormat documentation for more information.

• setLegendPosition

  public void setLegendPosition(org.jfree.chart.ui.RectangleEdge p_side!, org.jfree.chart.ui.HorizontalAlignment p_halign!, org.jfree.chart.ui.VerticalAlignment p_valign!)

  Sets the position of the legend in the chart

  Use code like widget!.getSideLeft(), widget!.getHAlignLeft(), widget!.getVAlignTop(), etc.

  Parameters:

  p_side The side of the chart (Top, Left, Bottom, Right)

  p_halign The horizontal alignment (Left, Center, Right)

  p_valign The vertical alignment (Top, Center, Bottom)

• setPlotBackground

  public void setPlotBackground(BBjNumber p_red, BBjNumber p_green, BBjNumber p_blue, BBjNumber p_opacity)

  Sets a background color for the plot, not the entire chart

  Parameters:

  p_red The Red value for the color (0-1)

  p_green The Green value for the color (0-1)

  p_blue The Blue value for the color (0-1)

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setPlotBackground

  public void setPlotBackground(BBjString p_colorHexString$, BBjNumber p_opacity)

  Sets a background color for the plot, not the entire chart

  Parameters:

  p_colorHexString$ A hex color string. An example would be "#ff00cc" or "#f0c"

  p_opacity The desired opacity value for the color (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setPlotBackground

  public void setPlotBackground(Paint p_paint!)

  Sets a background paint for the plot, not the entire chart

  Parameters:

  p_paint! A java.awt.paint object

  See Also:

  Oracle's Paint documentation for more information.

• setPlotBackgroundImage

  public void setPlotBackgroundImage(BBjImage p_image!, BBjNumber p_opacity)

  Sets a background image for the plot, not the whole chart

  Parameters:

  p_image! The image to be used for the background

  p_opacity The desired opacity value for the image (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setPlotBackgroundImage

  public void setPlotBackgroundImage(BBjString p_imageFile$, BBjNumber p_opacity)

  Sets a background image for the plot, not the whole chart

  Parameters:

  p_imageFile$ A string with the path to the image to be used for the background

  p_opacity The desired opacity value for the image (0-1). 0=Fully Transparent, 1=Fully Opaque.

• setRangeValues

  public void setRangeValues(BBjNumber p_minRangeValue, BBjNumber p_maxRangeValue)

  Sets the minimum and maximum values for the range of the chart's plot

  Note that this does not apply to charts without a range, such as a PieChart or RingChart

  Parameters:

  p_minRangeValue The minimum value for the range

  p_maxRangeValue The maximum value for the range

• setUserFontScalingFactor

  public void setUserFontScalingFactor(BBjNumber p_factor)

  Sets a font scaling factor for the chart based on the user's preferences. This method is used by the Customize screen to affect the user's choice of font scaling. Dashboard programs should not call this method, and should call the setFontScalingFactor() method instead.

  Specifying a scaling factor less than 1 decreases the fonts. Specifying a scaling factor greater than 1 increases the fonts.

  Parameters:

  p_factor A multiplication factor that will be applied to the base font size. If the base font is 10 points, and p_factor is 1.2, then the resultant base font size will be 12 points.

• showTip

  public void showTip(BBjString p_tip$)

  Shows the chart's tip after clicking on a data entity.

  This method is called automatically by default when the user left-clicks on a chart if the program hasn't registered a callback for the click event. Note that you can have your program register for the click event, create a custom message for the tip, then use this method to tell the widget to display your custom message.

  Parameters:

  p_tip$ The string of text to show in the tip

• shuffleColorVector

  public static BBjVector shuffleColorVector(BBjVector p_colorVector!)

  Shuffles the order of the colors in a vector

  Parameters:

  p_colorVector! A vector filled with Colors

  Returns:

  The vector of modified colors