Programming MS Office 2000 Web Components第三章第三节

译者说明：欢迎访问我的Blog:  http://blog.csdn.net/daidaoke2001/

译文中的错误或不当之处望不吝指出，这也是我坚持翻译工作的最大动力。

我的Email：tangtaike@163.com

如需转载，请事先通知。

 

第三章第三节    编程模型的关键元素

 

         和前一章一样，我会在本章最后部分重点讲述图表组件编程模型的关键元素。本节中列出的属性，方法和事件将很可能是您经常会用到的，在这里按照常见的任务来对这些方法和事件进行分类和组织。

         我不再重复在前一章讲述电子表格组件的编程模型时已经提到的那些适用于Offic Web组件库中所有控件的内容――您可以返回第二章来浏览那些属性的列表和解释。

在图表空间中创建图表

         当您创建了一个新的ChartSpace对象时，它最初不包含任何图表。请使用WCCharts集合的Add方法来将一个图表添加到ChartSpace对象中。表3－1列出了在将图表添加到图表空间，或从空间中移除图表时会使用到的属性和方法。

 

表3－1。在将图表添加到图表空间，或从空间中移除图表时会使用到的属性和方法。

属性或方法	描述
ChartSpace.Charts	这个属性返回一个WCCharts集合，其中包含了图表控件中所有的WCChart对象。
WCCharts.Add	使用这个方法将一个新的图表添加到图表空间中。
ChartSpace.Clear	这个方法从图表控件中清除所有的内容。使用这个方法可以快速的移除所有的图表，数据源，以及任何其它在图表空间中创建的元素。

 

改变图表或系列的类型

         您应该记得，我们在本章很早的时候就讨论了各种图表类型。将一个图表类型变换成另一个图表类型和设置一个属性一样简单。如表3－2所示。

 

表3－2。改变图表或系列系列的属性和常量。

属性或枚举值	描述
WCChart.Type	这个属性设置或提取一个图表中所有系列的类型。
WCSeries.Type	这个属性设置或提取图表中单个系列的类型。多重系列中每个系列都能具有它们自己的类型，但是不是所有的类型都能被组合到一个图表中（就像我们在前面的“组合图表”一节中所提到的那样）。
ChartChartTypeEnum	这个枚举包含了在上面所描述的Type属性中可以使用的所有常量。

 

将数据装载到图表中

         表3－3列出了在装载数据到图表组件中时会用到的方法。如果需要了解更多的详细说明和例子代码，可以参考本章前面的“装载”一节。

表3－3。装载数据到图表中的方法。

方法	描述
WCChart.SetData	这个方法可用来一次将所有数据（包括系列名）装载到整个图表中。
WCSeries.SetData	这个方法将数据装载到一个指定的系列中。

输出GIF图形

         您可以随时将图表控件的当前内容以GIF图形的形式输出到磁盘上。这需要使用表3－4中所介绍的ExportPicture方法。

表3－4。创建图表控件的GIF图形的方法。

方法	描述
ChartSpace.ExportPicture	这个方法将图表控件的当前内容输出为一个GIF图形文件。您可以指定文件名，图片宽度，和高度。如果您指定了可选的FilterName参数，那么它必须是“GIF”，因为GIF是当前版本控件所仅支持的格式。

 

操作轴

         您会常常需要调整您的图表中各种轴的外观。请使用表3－5中列出的属性来完成这些任务。

表3－5。格式化图表中轴的属性。

属性	描述
WCChart.Axes	这个属性返回WCAxes集合，从中您能获得一个特定的轴。如果要以轴的位置来查找轴，可以使用ChartAxisPositionEnum枚举中合适的常量。如果要以轴的次序来查找，可以使用它们在集合中的下标值来定位。
WCAxis.NumberFormat	这个属性设置或提取用于值轴标签的数字格式。您可以使用任何电子表格所支持的数字格式，包括预命名的格式和客户化的格式。
WCAxis.Font	这个属性返回轴的OWCFont对象。您可用使用这个对象的各个属性来调整轴标签字体的名称，大小，以及其它属性。
WCAxis.HasTitle	这个属性设置或获取轴是否具有一个标题。如果这个属性为False，则不存在标题；而标题应该占用的空间会被图表回收。如果这个属性被置为True，轴将具有一个标题；您可以使用WCAxis.Title属性来获得WCTitle对象，并设置它的文本。请注意如果在当WCAxis.HasTitle属性为False时访问Title属性会导致运行时错误。
WCAxis.Title	这个属性返回轴的WCTitle对象，利用它您可以设置标题的文本，字体以及颜色属性。
WCAxis.TickLabelSpacing	这个属性设置或提取用于轴的刻度标签的空间。刻度标签空间决定了在那些显示出来的标签之间有多少标签被丢弃了。当您所要显示的标签太多，以至于无法显示时，这个技巧就很有用了。被丢弃的标签可以根据周围的标签来进行推算。
WCAxis.TickMarkSpacing	这个属性设置或提取轴上的刻度标记之间的空间。和TickLabelSpacing属性一样，这个属性决定了在那些显示出来的标记之间有多少标记被丢弃。

 

操作图例

您可能需要隐藏或者显示一个图表的图例，或者隐藏某个图例项。请使用表3－6中所介绍的属性来完成这些任务。

表3－6。操作图例的显示的属性。

属性	描述
ChartSpace.HasChartSpaceLegend, WCChart.HasLegend	和表3－5中介绍的属性WCAxis.HasTitle一样， HasChartSpaceLegend和HasLegend属性定义了图表空间和单独的图表是否显示图例，以及是否为图例保留空间。为了使用下面介绍的ChartSpaceLegend或Legend属性，需要先将HasChartSpaceLegend或HasLegend属性设为True。
ChartSpace.ChartSpaceLegend, WCChart.Legend	ChartSpaceLegend和Legend属性分别返回代表整个图表空间的图例，和代表单个图表的图例的WCLegend对象。
WCLegend.LegendEntries	这个属性返回WCLegendEntries集合，其中包含了图例中的所有项。这个集合有一个Count属性，可以告诉我们图例中有多少项，还有一个Item属性，可以让我们提取每一项。
WCLegendEntry.Visible	这个属性定义一个图例项是否显示在图例中。如果将它置为False就会隐藏这个图例项。
WCLegend.Position	这个属性定义将图例放置在图表的哪个位置。可以被放置在图表的顶部，底部，左边，或者右边（缺省位置）。

 

有用的事件

         图表控件暴露了一些您可能会需要捕捉的有趣事件。所有事件都是从顶级的ChartSpace对象中触发的。表3－7列出了这些最有趣的事件。

表3－7。有用的图表事件。

事件	描述
Click, DblClick	当用户在图表控件的任何位置点击或双击时被触发。系统将一个WCChartEventInfo 对象传递给这些事件，从而可以判断鼠标当前在图表控件中的X和Y座标，如果将它们传递给RangeFromPoint方法，就能获得在(X,Y)点处的图表对象。
MouseMove	当用户在图表控件上方移动鼠标时被触发。WCChartEventInfo 对象也被传递给这个事件。
DataSetChange	当一个绑定数据源通知图表数据发生变化时被触发。图表控件会自动更新以显示新数据；但是，您应该使用这个事件来重新设置图表，因为有可能增加了新的系列。小心不要在这个事件中放置太多的代码：因为源数据的任何改动都会触发这个事件，它可能十分频繁的被触发。

 

 

小             结

         虽然图表组件可能界面看上去很简单，但实际上它的内部相当复杂。本章中我们已经了解了许多图表控件的功能。不过，在本书第二部分中我会讨论使用图表组件创建的一些解决方案，从中您会发现使用图表组件的更多信息。还有，请花一些时间阅读随书光盘中本章的例子文件，这对您开始编写使用图表控件的代码会很有帮助。

 

 

附录：英文原文

Key Elements of the Programming Model

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.

 

 

Summary

Although the Chart component might look rather simple on the surface, there is quite a bit of complexity hiding in it. We've covered much of the functionality of the Chart control in this chapter. However, you'll find more information on using the Chart component in Part II of this book where I discuss several solutions you can build using it. Also, spend some time looking at this chapter's example files on the companion CD as they will help you get started writing code against the Chart control.