Key Elements of the Programming Model

[Previous] [Next]

As in the previous chapter, I want to finish by highlighting the key elements of the Chart component's programming model. The properties, methods, and events listed in this section are the subset that you will likely want to use often and are organized according to the tasks you will typically want to perform.

I will not repeat the parts of the Spreadsheet component's programming model that I noted in the previous chapter as applying to all the controls in the Office Web Components library—you can refer back to Chapter 2 for a list and explanation of those properties.

Creating Charts in the Chart Space

When you create a new ChartSpace object, it initially does not contain any charts. To add a chart to the ChartSpace object, use the Add method of the WCCharts collection. Table 3-1 lists the properties and methods you will use to add and remove charts from the chart space.

Table 3-1. Properties and methods for adding and removing charts from the chart space.

Property or Method	Description
ChartSpace.Charts	This property returns the WCCharts collection of all the WCChart objects in the Chart control.
WCCharts.Add	Use this method to add a new chart to the chart space.
ChartSpace.Clear	This method clears all content from the Chart control. Use it to quickly remove all charts, data sources, and any other elements created within the chart space.

Changing Chart or Series Types

As you will recall, we discussed the various chart types much earlier in the chapter. Changing from one chart type to another is as simple as setting one property, as Table 3-2 shows.

Table 3-2. Properties and constants for changing chart or series types.

Property or Enum	Description
WCChart.Type	This property sets or returns the type for all series in a chart.
WCSeries.Type	This property sets or returns the type for a single series in a chart. Multiple series can each have their own type, but not all types can be combined in one chart (as discussed earlier in the chapter in the "Combination Charts" section).
ChartChartTypeEnum	This enumeration contains all the constants you can use with the two Type properties just described.

Loading the Chart with Data

Table 3-3 lists the methods you will use to load the Chart component with data. For more detailed explanations and example code, see the section "Loading Data" that appears earlier in the chapter.

Table 3-3. Methods for loading data into a chart.

Method	Description
WCChart.SetData	This method can be used to load data into the entire chart at once, including the series names.
WCSeries.SetData	This method loads data into a given series.

Exporting a GIF Image

You can export the Chart control's current contents to a GIF image on disk at any time. Use the ExportPicture method, which is described in Table 3-4.

Table 3-4. Method for creating a GIF image of the chart space.

Method	Description
ChartSpace.ExportPicture	This method exports the Chart control's current contents to a GIF image file. You can specify the filename, width, and height. If you specify the optional FilterName parameter, it must be "GIF" since the only format implemented in this version of the control is GIF.

Working with Axes

Often you will want to adjust the look of the various axes in your chart. Use the properties outlined in Table 3-5 to accomplish this.

Table 3-5. Properties for formatting the chart axes.

Property	Description
WCChart.Axes	This property returns the WCAxes collection, from which you can obtain a specific axis. To ask for an axis by its location, use the appropriate constant from ChartAxisPositionEnum. To retrieve the axes in order, use their index values.
WCAxis.NumberFormat	This property sets or returns the number format used for value axis labels. You can specify any number format that the Spreadsheet control supports, including the named formats and the custom formats.
WCAxis.Font	This property returns the OWCFont object for the axis. You can use the properties of this object to adjust the name, size, and other font attributes of the axis labels.
WCAxis.HasTitle	This property sets or returns whether the axis has a title. If this property is False, no title exists; the space it would have used is reclaimed for the chart. If this property is set to True, the axis will have a title; you can use the WCAxis.Title property to get at the WCTitle object and set its caption. Note that accessing the Title property while WCAxis.HasTitle is False results in a runtime error.
WCAxis.Title	This property returns the WCTitle object for the axis, with which you can set the title's caption, font, and color settings.
WCAxis.TickLabelSpacing	This property sets or returns the tick label spacing used for the axis. The tick label spacing determines how many labels are dropped from the axis between those that are displayed. This technique is useful for dropping date values when you have too many to show. The dropped labels can be assumed based on the surrounding labels.
WCAxis.TickMarkSpacing	This property sets or returns the spacing between tick marks on an axis. Like the TickLabelSpacing property, this property determines how many tick marks should be dropped between those that are shown.

Manipulating the Legend

You might want to hide or show the legend of a chart or hide individual legend entries. To do so, use the properties discussed in Table 3-6.

Table 3-6. Properties for manipulating legend display.

Property	Description
ChartSpace.HasChartSpaceLegend, WCChart.HasLegend	Like the WCAxis.HasTitle property described in Table 3-5, the HasChartSpaceLegend and HasLegend properties determine whether the chart space and individual chart will show and reserve space for a legend. To use the ChartSpaceLegend or Legend property described below, first set the HasChartSpaceLegend or HasLegend property to True.
ChartSpace.ChartSpaceLegend, WCChart.Legend	The ChartSpaceLegend and Legend properties return WCLegend objects that represent the legends for the entire chart space and the individual chart, respectively.
WCLegend.LegendEntries	This property returns the WCLegendEntries collection of all entries in the legend. The collection has a Count property that tells you how many entries appear in the legend and an Item property that lets you retrieve each one.
WCLegendEntry.Visible	This property determines whether a legend entry appears in the legend. Setting this to False will hide the legend entry.
WCLegend.Position	This property determines where the legend is placed in the chart. It can be placed on the top, bottom, left side, or right side (the default) of the chart.

Useful Events

The Chart control exposes a few interesting events that you might want to catch. All events are raised from the top-level ChartSpace object. Table 3-7 lists the most interesting events.

Table 3-7. Useful ChartSpace events.

Event	Description
Click, DblClick	Raised whenever the user clicks or double-clicks anywhere on the Chart control. Use the WCChartEventInfo object passed to these events to determine the current X and Y coordinates of the mouse within the Chart control, and pass those to the RangeFromPoint method to retrieve the chart object at that (X,Y) point.
MouseMove	Raised whenever the user moves the mouse over the Chart control. The WCChartEventInfo object is also passed to this event.
DataSetChange	Raised whenever a bound data source notifies the chart that the data has changed. The Chart control will automatically update to show the new data; however, you should use this event to reformat the chart in case new series were added. Beware of putting too much code in this event: since any change to the source data will raise the event, it can fire quite often.