Building Charts

In General Interface Builder, the process for creating and modifying charts is the same as for other GUI components. You build charts by dragging and dropping components from the Component Libraries palette, modifying object properties, and configuring events.

For more information about charting properties and events, see Charting Components.

These steps summarize the process of building a chart:

1. Analyze source data.
   
   • Source data must be in the CDF. For details, see the General Interface Developer Guide. If chart data is generic XML, it must be transformed into the CDF for use in the chart.
     
   • Identify the CDF attributes to use for data series and axis labels, if applicable.
2. Enable the Charting add-in for your project, so charting components are available. See Enabling the Charting Add-in.
3. Choose a prototype component that best fits your data and what the chart should illustrate.
   The structure of and variations in source data, as well as the information you want to show in the chart, determine the major variation of chart to use. The chart prototype you choose should be suitable for displaying the specific data set. See Charting Component Library for short descriptions of each major variation of a chart.
   To view representative CDF data for a chart prototype component, first create an instance of the prototype, then view the properties of the top-level chart component. The XML String field contains sample CDF data for the chart.
4. Add an instance of the chart prototype to a new GUI component or an existing GUI component.
   For existing components, a Layout or Block component is useful for positioning the chart.
5. Customize the chart component by adding or removing child objects and modifying properties. For detailed instructions on performing these tasks, see Chapter 4, Building a Simple Application.
   
   • For the chart component, specify the location of the CDF data using properties.
     
   • For each data series, specify the CDF attributes to display in the chart.
6. Customize the chart component by defining events. For details, see Implementing Chart Events.

For a chart example, see the General Interface Chart Sample, workspace/JSXAPPS/samples/chart.

Chart Component Hierarchy

When you add a chart component to a General Interface Builder project, the chart hierarchy appears in the Component Hierarchy palette. The following shows the hierarchy of a typical Cartesian chart on the left, and a typical radial chart on the right.

The hierarchy is a shallow tree structure with the chart object at the root and all other chart components, such as axes, series, and legend, on a single level directly under the root. Label objects can be nested under chart, series, legend, or axis objects.

It is possible to create an instance of a chart object or component using the General Interface API. However, it is usually more efficient to begin with a prototype component and customize it as necessary. The API methods are useful for adding new series at runtime, if the chart has a variable number of series.

These restrictions apply when creating and organizing charts in the Component Hierarchy palette:

• A chart component must have one or more series components, and the type of series must match the type of chart.
• A Chart Label object can be added to a chart, a legend, an axis, or a Pie series. These components can have at most one Chart Label child object.
• Cartesian charts must have one vertical axis and one horizontal axis.

The following sections describe how to configure chart components.

Configuring Axes

Most chart prototype components in General Interface Builder are Cartesian charts, which display data on an x-y plane. Cartesian charts must have both an x-axis and a y-axis defined. Axes can have labels, major and minor tick marks, and titles.

An axis in a Cartesian chart can be one of the following types:

• Linear displays a range of linearly increasing values. By default, a linear axis displays a range of values large enough to contain the chart data and divides the range into between five and eleven intervals.
  
• Category displays a range of discrete values, one for each category. A category corresponds to one row of data in a CDF file.
  
• Logarithmic displays a range of linearly increasing values rendered in a logarithmically increasing scale. Only positive values are displayed.
  

When an axis component is created, the type is fixed. To modify an axis, recycle the existing axis component and add a new axis of the correct type to the chart.

Values

The type of axis determines how data values are assigned. For linear and logarithmic axes, data values are specified by each series. The series has two properties, X Field and Y Field, for specifying the name of attributes in the CDF file. Depending on the axis configuration, one or both of these properties may be required.

Other properties that configure axis values are Min Field (Area Series, Bar Series, Column Series) for the CDF attribute that specifies the minimum value, and Magnitude Field (Bubble series) for the CDF attribute that specifies the magnitude value.

For a category axis, data values are specified once for the axis. The axis has a Label Field property for specifying the name of an attribute in the CDF file. The values of this attribute are used as axis values for all series in the chart.

Title

The axis title is specified by a Chart Label component that is a child of the axis component. When you create an axis component, the label component is automatically created. Axis titles are displayed parallel to the chart axis. For details on configuring this component, see Configuring Labels.

Labels

Axis labels appear next to the tick marks along a chart axis. Labels are optional and can be displayed or hidden using the Show Labels property for the axis.

Text

You can configure the position of axis labels relative to the axis and the text of axis labels. Axis properties allow you to configure label position relative to the axis, including the gap between the axis label and tick marks and position of axis labels relative to the axis. Label properties allow you to configure the label text, such as the text string, font, rotation, CSS class, and background color.

Functions

You can use the Label Function property to specify JavaScript for converting an axis value into an axis label. The signature of the function is:

function (value : String|Number) : String

For example, the following function formats axis labels by appending the degree symbol to axis values:

function degreeLabel(value) {
    return value + "°";
}

This function formats axis labels in the m/d format, using the axis value as the number of days from January 1, 2007:

function date05Label(value) {
    var t = new Date(2007, 0, value);
    return (t.getMonth() + 1) + "/" + t.getDate();
}

The following static functions are provided:

• jsx3.chart.Axis.percent Appends the % character to a linear axis value
• jsx3.chart.Axis.scientific Formats a linear axis value in scientific notation

The Label Function property value is actually a string value that evaluates to a function. Specify the name of a static function, such as Axis.percent or an inline function of the form:

function (x) { return x; }

When setting this value in the Properties Editor palette or in JavaScript code, the specified value must be a string that evaluates to a function with this signature. Omit any quotation marks, because the field is assumed to be a string.

CSS Formatting

If axis labels require complex styling, use the Label CSS Class and Label CSS Styles properties. Label CSS Class and Label CSS Styles specify the CSS class and style attribute, respectively, to apply to each axis label.

For category axes, the Label Field property defines the category attribute in the CDF file containing chart data.

Major and Minor Tick Lines

Each axis includes small markers, or tick marks, with corresponding labels. Charts can have two kinds of tick marks, major and minor. Major tick marks are the markers along an axis that correspond to an axis label. The text for an axis label can be an attribute in the chart CDF file. Minor tick marks evenly divide the distance between major tick marks, which helps users visualize the size of the interval.

For linear axes, major tick lines are drawn at the beginning of each interval. The Interval property controls the frequency of major tick marks.

Position

Tick marks can be displayed on the outside or inside edge of an axis or centered on the line representing the axis. Use the Mj Tick Placement property to configure the position of major tick marks, and the Mn Tick Placement property for minor tick marks.

Tick marks are optional in General Interface charts. To remove tick marks from an axis, specify a value of none for one of these properties.

The following example shows the vertical axis with Mj Tick Placement = cross and Mn Tick Placement = none. For the horizontal axis, Mj Tick Placement = outside and Mn Tick Placement = inside.

Length

In this example, the length of major tick marks on the horizontal axis is 3 pixels and the length of minor tick marks is 2 pixels. Use the Mj Tick Length and Mn Tick Length properties to specify the length of major and minor tick marks.

Stroke

Mj Tick Stroke and Mn Tick Stroke define the outline of major and minor tick marks. These properties take vector stroke values, which have this format:

color [width [alpha]]

where color is the marker color as a string or number, width is an integer value specifying the width of the line in pixels, and alpha specifies the marker transparency as a float value between 0.0 and 1.0. Both width and alpha are optional.

For category axes, Mj Tick Alignment specifies the position of major tick marks relative to each category. The default value, between, places each category and its axis label between two major ticks.

If aligned is specified, the tick marks are aligned with each category and axis label.

Configuring Data Series

A chart must include at least one series for displaying data. Each type of chart has a corresponding series type, which is the only type of series that can be added to the chart.

Data

To associate a CDF attribute with a series component, you specify the attribute name for a particular series property. For Cartesian charts, use either the X Field or Y Field properties, depending on which axis should display series data. For area, bar, and column charts, you can also specify a CDF attribute for the Min Field property to configure a minimum value. For radial charts, use the Field property to identify the series. For more information on chart data, see Displaying Data in Charts.

Coloring

Series are configured with a default coloring scheme, which can be used without modification. You can also specify custom color and transparency values for series by modifying the Fill and Fill Gradient properties for Cartesian charts or the Colors property for radial charts.

For example, the chart on the left has a blue series with a color and alpha value of #0099FF .4 specified for the Fill property. The chart on the right has a Fill value of #0099FF 1 and a value of #FFD700 45 1 specified for the Fill Gradient property.

Unlike other types of charts, the colored areas in a Pie chart represent categories. Fill values for each slice are defined either in the chart or in each series. To specify fills, you can set the series Colors property to an array of jsx3.vector.Fill values. Another option is to set the series Color Function property to a function with the following signature:

function (record : jsx3.xml.Entity, index : int) : jsx3.vector.Fill

The following example shows a function that fills Pie chart slices with one of 10 values on the gradient between black and red:

function sliceColorer(record, index) {
   var r = Math.round((index % 10) * 255 / 9);
   var rgb = r << 16;
   return new jsx3.vector.Fill(rgb);
}

By default, the static function PieChart.defaultColoring is used.

Tooltip Functions

A series can use a static function to generate tooltip text. At runtime, the tooltip displays information when the cursor moves over a data point. For example:

Each prototype series component has a default tooltip function specified. This example uses the default jsx3.chart.BubbleSeries.tooltip function, which displays the value of the current data point.

Point Renderers

Line, area, bubble, and point series can display a shape at each data point. The shape, which is rendered by a point renderer, can be one of the default shapes provided or a custom shape that you define. The default shapes are shown in the following example:

The Point Renderer property specifies the type of renderer for the series. To use a default shape, select the corresponding property from the context menu on the Properties Editor palette. For example,

Types

Both Line Series and Area Series components also have a Type property that controls how data points are connected. The following examples summarize the possible values for this property.

The line above an area series must be continuous, so horizontal and vertical are not supported for area series.

Configuring Grid Lines

Grid lines render colored lines and rectangles in the data area of a chart, aligned with the major and minor tick marks of chart axes. The lines visually extend major and minor tick marks, providing users with reference points for interpreting data. A Cartesian chart can have an unlimited number of grid lines.

Display Properties

Grid lines are always rendered behind the chart axes. Use the Draw in Foreground property to control whether grid lines display behind or in front of the data series. In the following example, this property is set to TRUE:

Depending on chart data and appearance settings, stacked 100% variations of Area, Bar, Column, and Line charts may require setting Draw in Foreground to TRUE.

Each grid line can render both horizontal and vertical lines and fills. For example:

The Layering property controls whether horizontal fills, major ticks, and minor ticks display in front of vertical fills and tick marks. In this example, the Layering property is set to "Vertical Above Horizontal".

Data Area Stroke

The Border property specifies the stroke to use for outlining the data area of the chart. This property takes a vector stroke value. For details of how to specify a vector stroke value, see the descriptions of Mj Tick Stroke and Mn Tick Stroke in Configuring Axes.

Grid Line Fill

To configure fill values for grid lines, use the Ver. Fill and Hor. Fill properties. These properties take one or more vector fill values, which have the following format:

color [alpha]

where color is the marker color as a string or number, and alpha specifies the marker transparency as a float value between 0.0 and 1.0. alpha is optional.

For example:

#CCCCCC, #DDDDDD

This example shows an array of two color values separated by a comma. When displayed in the chart, these values alternate at major tick marks. If additional color values are specified, the fill cycles through the values in the array at each major tick.

Grid Line Stroke

The Ver Major Stroke and Hor. Major Stroke properties control the stroke used between major tick lines. Similarly, the Ver Minor Stroke and Hor. Minor Stroke properties control the stroke used between minor tick lines. These properties take one or more vector stroke values. If an array of stroke values is specified, the fill cycles through the values in the array at each major tick.

For details of how to specify a vector stroke value, see the descriptions of Mj Tick Stroke and Mn Tick Stroke in Configuring Axes.

Configuring Legends

A legend displays a visual key to the series or categories in a chart. For Cartesian charts the legend displays series information, and for radial charts the legend displays category information. A chart can have at most one legend.

When a legend component is added to a chart, the legend automatically displays the correct entries by introspecting the chart.

Position

To reposition the legend relative to the chart, modify the Legend Placement property for the chart. The default position is on the right side of the chart, centered vertically.

Size

The size of the legend is controlled by the Box Height and Line Height properties. Box Height specifies the size of each legend symbol, similar to a font size. Larger values increase the symbol size without affecting the text string with the series name. Line Height specifies the spacing between each entry, so larger values create more white space between entries.

Text Appearance

The appearance of the text string with the series name is controlled by the Label CSS Class and Label CSS Styles properties.

The legend title is specified by a Chart Label child object. When you create a Legend component, the label component is automatically created. For details on configuring this component, see Configuring Labels.

You can use the Padding and Margin properties to control the amount of white space inside the legend box and between the legend box and the edge of the chart, respectively.

By default, the legend box has a white background. You can specify a vector fill value for the Background Fill property to specify a background fill color. For details on how to specify a vector fill value, see the descriptions of Ver. Fill and Hor. Fill in Configuring Grid Lines.

The Background Stroke property controls the outline of the legend box, and takes a vector stroke value. For details on how to specify a vector stroke value, see the descriptions of Mj Tick Stroke and Mn Tick Stroke in Configuring Axes.

Configuring Labels

A Chart Label object defines style settings for a block of text. In addition to defining the title of a chart component, this object also provides internal text labels for other components. Label is used for rendering legend titles, axis titles, and Pie chart series labels. When an object that can use a label does not have one defined, no text is displayed.

The text of the label is specified by the Text property. The Font Face, Font Size, Font Weight, and Color properties can be used to apply manual formatting to the text string. You can also specify a CSS class for this purpose, although the effect of class settings may vary, depending on whether the label is rotated.

Labels can be rotated either 90 or 270 degrees using the Rotation property.

Specifying Properties with Vector Values

The private jsx3.vector package determines how vectors are rendered.

Vector Fill

A jsx3.vector.Fill class specifies how the interior of a vector shape is colored. The most basic vector fill value is a simple RGB color value. The vector.Fill class also supports more advanced coloring options, such as opacity and gradient fill.

The constructor for jsx3.vector.Fill is function(color, alpha)

• color {String | int} is the color value, accepts a hex String or 24-bit integer value and defaults to #000000
• alpha {Number} is the opacity value, accepts valid values between 0 (transparent) and 1 (opaque) and defaults to 1.

  Gradient fill cannot be specified in the constructor.

Several chart components, such as series and grid lines, have properties for storing string representations of a vector fill object. Storing a string representation instead of an actual instance allows you to edit these values in the Properties Editor palette. The following is the syntax of the string representation:

color [alpha]

where color can be either a string such as "#FF0000" or "red". Specifying alpha, which can be a float value between 0.0 and 1.0, is optional.

Gradient Vector Fill

Some prototype components support gradient vector fill objects. In these cases, the gradient information is also stored in an instance field as a string representation. If specified, the gradient string representation is combined with the fill string representation to create one jsx3.vector.Fill object. The string representation of a gradient is:

color2 [angle [alpha2 [percent stop color,]*]]

The gradient is rendered starting from the main fill color/fill alpha and ending at color2/alpha2 along the specified angle. Optional intermediate colors along the way are defined by percent and stop_color pairs. Pairs are separated by commas. For example, red 0 1 50% white, 75% black. color2 is a string (#FF0000) or predefined color name (red).
angle specifies the angle of the gradient vector measured in degrees (between 0 and 360) counter-clockwise from 12 o'clock.
alpha2 is an optional float value between 0.0 and 1.0.

Vector Stroke

A jsx3.vector.Stroke class specifies how the outline of a vector shape is drawn. The most basic vector stroke definition consists of an RGB value and a width. The opacity property can also be specified.

Several jsx3.chart classes have fields that hold string representations of jsx3.vector.Stroke object. The syntax of the string representation is:

color [width [alpha]]

where color can be either a string such as "#FF0000" or "red". Specifying alpha, which can be a float value between 0.0 and 1.0, is optional. width is an integer value specifying the width of the line in pixels.