Specifying cosmetics settings for gauges

When using the Specify Gauge Settings dialog box to create and configure gauges, these settings are all made on the Cosmetics tab. This tab includes these groups for different types of data settings:

  • Number Formatting
  • Cosmetics
  • Padding & Margins
  • Gradient
  • Bulb
  • Font

When modifying a gauge by script, use the GaugeSetProperty method or the GaugeGetProperty method to make these settings. Use the GaugeProperty enumeration.

Number Formatting group

This table lists the settings you can make in the Number Formatting group box of the Cosmetics tab. GaugeSetProperty and GaugeGetProperty property names are also listed. These settings apply only to number values. Unless otherwise stated, they apply to all number values displayed on the gauge.

Cosmetics tab Fields / Options Property name Description / Comments
Default Number Scale DefaultNumberScale Specify the unit that should be interpreted as the default value for any numbers.

For example, if the numbers to be formatted represent the number of seconds in a time sequence, then you would specify seconds in this field.

Number Scale Unit NumberScaleUnit Specify the units of conversion to be used when converting numbers from lesser units to greater units. Specify units using a comma-separated list.

For example, to change the way numbers are displayed based on their values, you can specify a Thousands to Millions to Billions conversion sequence. To do this, you would specify K, M, B in this field.

To make time conversions (minutes to hours to days to weeks, for example), you would specify Min, Hr, Day, Wk in this field.

This specification must be used in conjunction with the Number Scale Value specification.

Note: The default number scale unit used is thousands to millions (K, M).
Number Scale Value NumberScaleValue Specify the conversion ratio to use from one unit to the next unit. You must have one value here for each unit specified in the Number Scale Unit field. Specify these values using a comma-separated list.

For example, to convert from thousands to millions to billions, you would specify 1000, 1000, 1000 in this field. To convert from the default of seconds to minutes to hours to days to weeks, you specify 60, 60, 24, 7 in this field.

This specification must be used in conjunction with the Number Scale Unit specification.

Note: The default number scale value used is thousands to millions (1000, 1000).
Decimal Separator DecimalSeparator Specify the character to be used as the decimal separator in numbers.

For example, in some countries, a period (which is the system default) is used to separate whole numbers from decimal parts. In other countries, a comma is used for this purpose. In this latter case, you would specify a comma (,) in this field.

Thousand Separator ThousandSeparator Specify the character to be used as the thousands separator in numbers.

For example, in some countries, a comma (which is the system default) is used to separate whole numbers with more than three digits with commas every three digits. In other countries, a period is used for this purpose. In this latter case, you would specify a period (.) in this field.

Thousand Separator Position ThousandSeparatorPosition Specify the number of digits after which the thousand separator character should be placed. You can use multiple values, separated by commas.

For example, if you were to specify 2,3 in this field, a number with nine digits would be formatted with a comma between the second and third digit from the right, and every third digit after that. If the number to be formatted were 123456789, it would be formatted as 1,234,567,89.

Format Number FormatNumber When selected (default), this option specifies that numbers are to be formatted with commas (Thousand Separators).

Otherwise, numbers are displayed without separators.

Force Decimals ForceDecimals When selected, this option specifies that all numbers on the gauge should display with the designated number of decimal places, even if only some or no decimal places are needed. This option adds zeroes, if necessary, to ensure that the designated number of decimal places display.

Otherwise, all numbers display with only the number of decimal places required.

Format Number Scale FormatNumberScale When selected (default), this option specifies that numbers are to be displayed with a trailing K (for thousands) or an M (for millions) after being truncated and rounded.

Otherwise, numbers are not truncated and rounded.

Cosmetics group

This table lists the settings you can make in the Cosmetics group box of the Cosmetics tab. GaugeSetProperty and GaugeGetProperty property names are also listed. These settings apply to the gauge component (the area surrounding the gauge image itself).  

Cosmetics tab Fields / Options Property name Description / Comments
Back Color BgColor Specify the RGB value for the background color, as a hexadecimal value (000000-FFFFFF).

You can double-click to display the Color dialog box, where you can select a color or define a custom color for the background (fill).  The hexadecimal code displays after you click OK to exit the Color dialog box.

To use a gradient fill, specify all the colors required for the gradient fill, separated by commas.

Back Alpha BgAlpha For each background color you specified, specify the transparency of the background, from 0 (transparent) to 100 (opaque).

Separate multiple alpha values with commas.  

Back Ratio BgRatio Specify the ratio of each color in the gradient on a scale of 100. The total of the ratios must equal 100.

For example, to plot an equidistant gradient for two colors, specify the ratio as 50,50.

Back Angle BgAngle Specify the angle for the gradient fill, in degrees, from 0 to 360.
Show Border ShowBorder When selected, this option displays a border around the outside of the gauge component area (not the gauge image itself).
Border Color BorderColor Specify the RGB value for the border color, as a hexadecimal value (000000-FFFFFF).

You can double-click to display the Color dialog box, where you can select a color or define a custom color for the border. The hexadecimal code displays after you click OK to exit the Color dialog box.

Border Thickness BorderThickness Specify, in pixels, the thickness of the border.
Border Alpha BorderAlpha Specify the transparency of the border, from 0 (transparent) to 100 (opaque).

Padding & Margins group

This table lists the settings you can make in the Padding & Margins group box of the Cosmetics tab. GaugeSetProperty and GaugeGetProperty property names are also listed.  

Cosmetics tab Fields / Options Property name Description / Comments
Left Margin

Right Margin

Top Margin

Bottom Margin

ChartLeftMargin

ChartRightMargin

ChartTopMargin

ChartBottomMargin

Specify, in pixels, the thickness of any margins around the gauge component.

Margins refer to the spaces around the outside the actual gauge display, used to separate the gauge from surrounding material. Each of the margins-left, right, top, and bottom - must be set individually.

Use these options to override the default spaces with higher values.

This attribute can be helpful when you have multiple gauges and you want all of them  to align with each other.

Value Padding ValuePadding Specify, in pixels, the thickness of any padding.

Padding refers to the amount of space between the value text and the edge of the data plot in which the value is displayed.

Gradient group

The Gradient group settings can be used to provide a more attractive or 3D appearance to angular and linear gauge types.

This table lists the settings you can make in the Gradient group box of the Cosmetics tab. GaugeSetProperty and GaugeGetProperty property names are also listed.  

Cosmetics tab Fields / Options Property name Description / Comments
Gauge Fill Mix GaugeFillMix Specify a gradient mix formula for the gauge. The formula can include any combination of these values, using a list separated by commas:
  • {dark- xx}, where xx represents the percentage of base color darkness

    For example, {dark-10} represents a color which is 10% darker than the colors specified.

  • {light- xx}, where xx represents the percentage of base color lightness
  • {color}, which refers to the base color, as set on the Color Ranges tab
  • { HexCode } such as {FFFFFF} or {FF0000}

    This setting can be used to override the default base color, or it can be used in combination with that and other color specifications to define a gradient.

Gauge Fill Ratio GaugeFillRatio Specify a gradient fill ratio for the gauge.

The ratio determines how far a color spreads before it is mixed with the next color to form a gradient. Separate the ratios by commas, for example: 60,20,20. The sum of the ratio values should equal 100, and the number of ratios in the list should equal the number of colors you specify in the Gauge Fill Mix field. The system maps each ratio to the corresponding color in the mix.

Bulb group

The Bulb group box has only one option: 3D. When selected (default), this gives Bulb type gauges a three-dimensional appearance. Otherwise, Bulb gauges have a flat two-dimensional appearance.

The GaugeProperties enumeration property name for this is Is3D.

Font group

The Font group box controls font specifications for the base font (used by default when other specifications have not been made), the gauge component caption (title), and the sub-caption.

This table lists the settings you can make in the Font group box of the Cosmetics tab. GaugeSetProperty and GaugeGetProperty property names are also listed.  

Cosmetics tab Fields / Options Property name Description / Comments
Base Font BaseFont Specify the font or font family to use for all text on the gauge; for example, Arial.
Base Font Size BaseFontSize Specify a font size, in points (0 to 72), for the base (description) text.
Base Font Color BaseFontColor Specify the RGB value for the base font color, as a hexadecimal value (000000-FFFFFF).

You can double-click to display the Color dialog box, where you can select a color or define a custom color for the base font. The hexadecimal code displays after you click OK to exit the Color dialog box.

Caption Alignment CaptionAlignment Using the drop-down list, specify whether the caption should be aligned left, center, or right.
Caption On Top CaptionOnTop When selected (default), this option displays the caption above the gauge.

By default the caption displays underneath the gauge.

Caption Font Size CaptionFontSize Specify a font size, in points (0 to 72), for the caption text.
Caption Font CaptionFont Specify the font or font family to use for the caption text; for example, Arial.
Caption Font Color CaptionFontColor Specify the RGB value for the caption font color, as a hexadecimal value (000000-FFFFFF).

You can double-click to display the Color dialog box, where you can select a color or define a custom color for the caption font.  The hexadecimal code displays after you click OK to exit the Color dialog box.

Caption Font Bold CaptionFontBold When selected (default), uses the Boldface font attribute to display the caption.
Caption Horizontal Padding CaptionHorizontalPadding For captions that are not center-justified, specify the number of spaces to be placed as padding to the left or right of the caption (for left-justified captions or right-justified captions, respectively). If the caption is justified center, this setting has no effect.
Align Caption With Canvas AlignCaptionWithCanvas When selected (default), causes the caption to be aligned with reference to the component canvas.

Otherwise, the caption is aligned as set using the Caption Alignment setting.

Sub-Caption Font Size SubCaptionFontSize Specify a font size, in points (0 to 72), for the sub-caption text.
Sub-Caption Font SubCaptionFont Specify the font or font family to use for the sub-caption text; for example, Arial.
Sub-Caption Font Color SubCaptionFontColor Specify the RGB value for the sub-caption font color, as a hexadecimal value (000000-FFFFFF).

You can double-click to display the Color dialog box, where you can select a color or define a custom color for the sub-caption font.  The hexadecimal code displays after you click OK to exit the Color dialog box.

Sub-Caption Font Bold SubCaptionFontBold When selected (default), uses the Boldface font attribute to display the sub-caption.

For more information about these and other gauge properties, see the FusionCharts Developer help (www.fusioncharts.com/dev/).