Session Name

FoxChartsJim Nelson

The Kong Company

21 Los Vientos Drive

Newbury Park, CA 91320

Voice: (805) 498-9195

Fax: (805) 498-9195

Email: JimRNelson@GMail.Com

FoxCharts creates great-looking, modern charts in pure VFP code, using NO ActiveX components. It can create pie and doughnut charts as well as a number of different horizontal and vertical charts. It takes full advantage of colors, using solid or gradient colors, hatch brushes, transparencies, 3D effects, and animation. There are customizable tooltips and full mouse behavior customization. The Visual Chart Designer provides a mechanism whereby a chart can be modified as it is visible on the screen, by either the developer or the end user.

Table of Contents1. Overview

2. Installation

3. Setting up Your Data

4. Getting Started: Simple Chart Examples

4.1. Pie, Doughnut, and Simple Bar Charts

4.1.1. Data-Related Properties 4.1.2. Creating a Simple Pie Chart4.2. Points, Lines, and Bar Charts

4.2.1. Data-related Properties

4.2.2. Creating a Simple Line Chart5. Refining Your Chart

5.1. The Different Chart Types5.1.1. Pies, Doughnuts, and Simple Bars5.1.2. Lines and Points

5.1.3. Bars5.1.4. Areas 5.2. Depth: Adding the Third Dimension5.3. Colors

5.3.1. RGB Colors

5.3.2. Transparencies

5.3.3. Colors for Shapes5.3.3.1. Color Type Selection

5.3.3.2. Gradient Colors

5.3.3.3. Brush Types

5.3.4. Background Colors

5.4. Legends

5.5. Scaling

5.6. Lines, Bars, Axes, and Tick Marks5.6.1. Lines

5.6.2. Bars

5.6.3. Axes

5.6.4. Tick Marks5.7. ToolTips

5.8. Margins

5.9. Chart-Specific Properties

5.9.1. Pies, Doughnuts, and Simple Bars5.9.2. Lines and Points

5.9.3. Bars5.9.4. Areas6. Printing Your Chart

6.1. Printing Directly, Using GDIPlusX Functions

6.2. Saving the Chart to a File

6.3. Embedding in a Report (FRX)

6.4. Printing with the Designer Using a Vectorial Chart in EMF

7. Using the Visual Chart Designer

8. Customization

8.1. Obtaining Current Chart Properties

8.2. Changing Scaling Values and Legends

8.3. Drawing Custom Images

8.4. Click and DblClick

8.5. Mouse Movement over a Chart Shape

8.6. Shape Legends9. Summary

10. Biography

Section 1: OverviewFoxCharts creates great-looking, modern charts in pure VFP code, using NO ActiveX components. It can create pie and doughnut charts as well as a number of different horizontal and vertical charts. It takes full advantage of colors, using solid or gradient colors, hatch brushes, transparencies, 3D effects, and animation. There are customizable tooltips and full mouse behavior customization. The Visual Chart Designer provides a mechanism whereby a chart can be modified as it is visible on the screen, by either the developer or the end user.

It is easy to set up and easy to customize. The code is Open Source, benefiting from all the GDIPlusX drawing capabilities, allowing developers to modify the charts as they see fit. (GDIPlusX is a set of Visual FoxPro 9.0 class libraries that wrap the 603 GDI+ Flat API functions of GDIPlus.dll.) It is easy to save to disk or print, and charts can be saved as EMF (Enhanced MetaFile) images, resulting in perfect charts when printed, used in a report, or exported to a PDF.

Doughnut Sample, with color gradients, detached slices, and shape transparencies.

The overall structure of FoxCharts is amazingly simple.FoxCharts is a container which can be dropped onto any form or class, anywhere that a container can go. There can be as many instances of FoxCharts in a form or class as desired.

The data to be charted comes from the fields in a cursor (or table, or equivalent). The fields are referenced by their names.

FoxCharts is property-driven; there is a very large number of properties in the FoxCharts container which indicate what data is charted, which type of chart is used, as well as all the various legends, colors, scaling, etc. Understanding these properties and their relationships to one another is the key to understanding FoxCharts.

After all the properties are set, calling a single method creates the chart.

Sample of an Area Chart, with shape transparencies and depth (3-D)

Section 2: InstallationFoxCharts is part of VFPx, a Visual FoxPro Community effort to create open source add-ons for Visual FoxPro. It is based on GDIPlusX, which is also part of VFPx.To obtain the current version of FoxCharts, visit the VFPx home page at:

http://www.Codeplex.Com/VFPxFrom there, navigate to the page for FoxCharts, and download three zip files: The most recent release of FoxCharts. Unzipping it creates a new folder which has two sub-folders:

The Source folder, which contains all the files needed to run FoxCharts. The only file which you directly reference is FoxCharts.VCX, which contains the FoxCharts class. The remainder of the files are referenced by FoxCharts; they need to be somewhere in your path.

The Samples folder, which contains a large number of sample charts. Use DemoStart.PRG to try all the different samples.

The Help file. Unzipping it creates a CHM file in the same folder. This Help file is very thorough; it is quite helpful to become familiar with it.

JRN_FoxCharts_Tools.Zip. Unzipping it creates a new folder, JRN_FoxCharts_Tools. This folder contains a couple of add-on tools not part of FoxCharts proper: GetChartDataFromRows.PRG, explained in Section 3. VisualChartDesigner.VCX, explained in Section 7.

A Documentation folder.

A Samples folder, which contains VisualChartDesigner_Sample.SCX

An additional form and class; you will not reference either of these, but both are used by the VisualChartdesigner.Section 3: Setting up Your DataThe data which appears in the chart comes from the fields in a cursor (or table, or equivalent). The alias of the cursor is stored in the required property SourceAlias:

.SourceAlias = History

The data in this cursor is not accessed directly; instead, a new cursor is created using an SQL Select statement. This means any ordering or filtering on the original cursor is ignored. Each data series in the chart is contained in a single field. The order of the fields is not relevant, only their names. They may appear in any order, and there can be any number of additional (not-referenced) fields. In the example cursor below, only the columns YR2005 YR2009 contain data that will be charted; if drawn in a line chart, you would see five lines. Note that there are null values in these fields as well; these will not appear in the chart.Depending on what type of chart is being drawn, additional (optional) columns may also be included in the cursor. These columns are explained in detail in Section 4.

Sample cursor each data series in a separate fieldYour source data may not always be so cooperative as to be oriented so that each data series is in a field; you may have data where each data series is actually a row in a cursor (such as might be displayed in a grid).

The cursor below (SalesHistory2) contains the same data as the cursor on the previous page (SalesHistory), but with each data series in a separate row. (In fact, the cursor below is the original source for these examples; the cursor on the previous page was derived from it using the method described below.) Sample cursor each data series in a separate row

GetChartDataFromRows.PRG transforms a cursor that has its data series in separate rows into a cursor FoxCharts can use.

GetChartDataFromRows.PRG requires a secondary cursor as well to describe which fields in the source cursor contain data (or other relevant information). It is fully commented. The following converts the cursor above (SalesHistory2) using the cursor below (FieldInfo) as the secondary cursor, so that it can be used to create a chart.GetChartDataFromRows (Thisform.FoxCharts1, SalesHistory2, SideLegend, FieldInfo, SrcFldName, Legend)

Section 4: Getting Started: Simple Chart ExamplesCreating a rudimentary chart from a cursor (such as from the sample cursor, shown earlier) is a rather simple task. A small number of properties need to be set before calling a single method to create the chart.There are two different types of charts: those that use a single data series (pies, charts, and simple bars) and those that can use one or more data series (all the rest). The properties for these two different types of charts are quite similar, but are not identical, so they will be described separately.Each of the samples here uses a form BlankSample.VCX from the Samples folder. The form contains a single FoxCharts object, with all of its properties default. The code samples provided can be pasted into the forms custom method CreateChart after which the form can be run to create the samples.

Section 4.1: Pie, Doughnut and Simple Bar Charts

Section 4.1.1: Data-Related Properties

There are only a few properties necessary for the simplest of pie charts, as follows: SourceAlias = The name of the cursor (table) containing the data

ChartType = Type of chart: 1for Pies

2 for Doughnuts 7 for Single Bars 12 for Horizontal Single Bars ChartsCount = 1 (always only one data series) Fields(1).FieldValue = Name of field containing dataThere are also a few optional properties for pie charts. Each of these properties, if used, is the name of a field in the cursor: FieldLegend name of the data item; appears in Side Legend (see sample) FieldColor backcolor (only applies if .ColorType = 1 (Custom) or 3 (Gradient)) FieldDetachSlice indicates if slice is detached (pies and doughnuts only) FieldHideSlice indicates if slice is hidden (pies and doughnuts only)Section 4.1.2: Sample Code for Creating a Simple Pie ChartWith Thisform.FoxCharts1 As FoxCharts Of "FoxCharts.vcx"

* Set all the properties for the chart

* Name of the alias that contains the needed fields that will create the chart

.SourceAlias = 'SalesHistory'

* Numeric, the number of data series.

.ChartsCount = 1

* Numeric, the type or chart to create.

.ChartType = 1 && pie chart

* The name of the field for the data series

With .Fields(1)

.FieldValue = 'YR2008'

Endwith

* Name of the field that contains the main legends of the Pie or Doughnut charts

.FieldLegend = 'MonthName'

* Name of the field that contains the custom colors for the chart

.FieldColor = 'BackColor'

* Name of the field that indicates whether the slice will be detached

.FieldDetachSlice = 'DetachMe'

* The name of the field that indicates whether the slice will be hidden

.FieldHideSlice = 'HideMe'

* Create the chart

.DrawChart()

Endwith

Section 4.2: Points, Lines, and Bar Charts

Section 4.2.1: Data-Related Properties

There are only a few properties necessary for the simplest of line charts (or any of the other charts that can have one or more data series), as follows:

SourceAlias = The name of the cursor (table) containing the data

ChartType = Type of chart: 4for Points

5 for Lines

6 for Area

10 for Stacked Area 8 for Multiple Bars

13 for Horizontal Multiple Bars

9for Stacked Bars

14 for Horizontal Stacked Bars

11for Bars in 3D FieldAxis2 = The name of the field in the cursor containing the values to be displayed along the X-Axis (optional)

ChartsCount = the number of data series; setting this creates a collection named Fields, which is referenced below.

The Fields collection has one item for each data series. The properties of each of these items are as follows: Fields(N).Field = Name of field containing data for the N-th data series

Fields(N).Legend = The caption to be used in the side-legend for the N-th data series (optional)

Fields(N).Color = The RGB value to be used for the shape drawn for the N-th data series (optional); this only applies if ColorType = 1 or 3 Fields(N).Shape = Shape to be used for Point or Line Charts.

Section 4.2.2: Sample Code for Creating a Simple Line Chart

With Thisform.FoxCharts1 As FoxCharts Of "FoxCharts.vcx"

* Set all the properties for the chart

* Name of the alias that contains the needed fields that will create the chart

.SourceAlias = 'SalesHistory'

* Numeric, the type or chart to create.

.ChartType = 5 && = Lines

* Numeric, the number of data series..ChartsCount = 5

* Numeric, the depth in pixels, simulating a 3D effect (0 = plain)

.Depth = 0

* The name of the field containing the values to be displayed along the X-Axis..FieldAxis2 = 'MonthName'

* The fields for each of the data series, and their associated legendsWITH .Fields(1)

.FieldValue = 'YR2005'

.Legend = 'Sales 2005'

ENDWITH

WITH .Fields(2)

.FieldValue = 'YR2006'

.Legend = 'Sales 2006'

ENDWITH

WITH .Fields(3)

.FieldValue = 'YR2007'

.Legend = 'Sales 2007'

ENDWITH

WITH .Fields(4)

.FieldValue = 'YR2008'

.Legend = 'Sales 2008'

ENDWITH

WITH .Fields(5)

.FieldValue = 'YR2009'

.Legend = 'Sales 2009'

ENDWITH

Endwith

Section 5: Refining Your ChartSection 5.1: The Different Chart TypesThere are 16 different chart types. Samples of each are displayed below. The samples were all created using the VisualChartDesigner_Sample form in the Samples folder.Note that for each of the groups below, there are a few properties that apply only to that group. These are spelled out in detail in 5.9.Section 5.1.1: Pies and Doughnuts

ChartType 1 = Pie

ChartType 2 = DoughnutSection 5.1.2: Points and Lines

ChartType 4 = Points

ChartType 5 = Lines

Section 5.1.3: Bars

ChartType 7 = Single Bar

ChartType 12 = Horizontal Single Bar

ChartType 8 = Multiple Bars

ChartType 13 = Horizontal Multiple Bars

ChartType 9 = Stacked Bars

ChartType 14 = Horizontal Stacked BarsSection 5.1.3: Bars (Continued)

ChartType 3 = Full-Stacked Bars

ChartType 15 = Horizontal Full-Stacked Bars

ChartType 11 = Bars in 3D

Section 5.1.4: Area

ChartType 6 = Area

ChartType 10 = Stacked Area

ChartType 16 = Full-Stacked AreaSection 5.2: Depth adding the third dimensionThe illusion of a third dimension can be added to charts by using the Depth property.

This 3-D effect changes flat, uninteresting charts into charts that appear to sink into the screen. See, for example, the following chart:

Sample using Depth = 10

The Depth property is the number of pixels used in creating the depth illusion. It is integer-valued; its nominal range is between 0 and 50.

It is frequently used in conjunction with the AlphaChannel property, which controls the level of the transparency of the shape objects on the chart. See 5.3.2.While the Depth property is of great value in most charts, it can make both Point and Line Charts very difficult to read. These work better with no depth (Depth = 0).Section 5.3: Colors

Section 5.3.1: RGB ColorsAll of the objects seen in a chart have familiar RGB colors assigned to them. For those that are text-oriented (called Legends see Section 5.4), there are colors for both the foreground (text) and the background.

The color properties are: AxisColor the color used for the horizontal axes

BackColor the primary background color for the entire chart

BackColor2 the secondary background color for the entire chart; used to create color gradients for the chart background (more on this in a bit)

ScaleBackColor the color for the bars (either horizontal or vertical) that appear on all but pie and doughnut charts

ScaleLineColor the color for the lines (either horizontal or vertical) that appear on all but pie and doughnut charts

ScaleLineZeroColor the color for the line Y = 0 (that is, along the X-Axis); applies only if the chart shows both positive and negative values and the property ShowLineZero is .T. SelectedShapeColor the color used when the mouse pointer is moved over one of the chart shapes; applies only if the property ShowColorOnMouse is .T. ForeColor and Backcolor for each of the Legends see Section 5.4

Much more can be done with colors, however, to make them more appealing: transparencies, gradient colors, and brush types.The following chart will be used as an example throughout this section. It is a simple doughnut chart, created with a depth of 30 but no transparencies.

Section 5.3.2: TransparenciesTransparency is the term used to describe how much an object obscures whatever has been drawn behind it.

Transparency values, also called AlphaChannel, range from 0 (completely transparent) to 255 (completely opaque). This is similar in concept to the VFP BackStyle property, which has values of either 0 (transparent) or 1 (opaque).

A number of different FoxCharts colors have an associated transparency value:

AlphaChannel transparency for the shape objects on the chart; this is the transparency which has the most vivid effect; see below

AxisAlpha transparency for the X and Y axes

BackColorAlpha transparency for the background colors for the chart

ScaleBackAlpha transparency for lines and bars drawn for charts (other than pie and doughnut charts) ForeColorAlpha for Legends, for the foreground color.

BackColorAlpha for Legends, for the background color; usually left at 0Below is the same chart as the previous page, but with a value for AlphaChannel of 230.

Section 5.3.3: Colors for ShapesSection 5.3.3.1: Color Type Selection

There is a surprisingly large number of ways to assign the colors used for the shapes that appear in a chart. These are specified by the property ColorType. Its possible values are:

0 = Basic colors

1 = Custom (the default); colors are used based on the assignments to the various properties described in Section 4. 2 = Random 3 = Gradient; the first color used is Fields(1).color, and a gradient is applied ending with almost white.

4 thru 27: Pre-assigned color palettesThe chart on the previous page was drawn using ColorType = 14. Here is the same chart with ColorType = 21

Section 5.3.3.2: Gradient Colors

ColorType = 3, as noted above, produces gradient colors that is, colors which transition from one color to another. In this case, they transition from the main color (red) to almost white.

Section 5.3.3.3: Brush TypesBrush Types describe how the colors are brushed onto the shape objects. The property BrushType can take one of these values:

1 = Solid colors (what has been shown thus far)

2 = Gradient colors

3 = Monochrome

If gradient colors are used, the following properties apply:

GradientLevel describes destination color; 10 = white, -10 = blank

GradientInvertColors if .T. the main and destination colors are inverted

GradientPosition indicates where the highest intensity occurs GradientDirection direction of gradiency; top to bottom, left to right, etc. GradientType sigma bell or triangularThe chart below was drawn using a gradient brush (leaving all the secondary properties with their default values).

Section 5.3.4: Background ColorsThere are also colors that can be applied to the background of the chart to soften (and highlight) its appearance:

BackColor the primary background color for the entire chart

BackColor2 the secondary background color for the entire chart; used to create color gradients for the chart background (more on this in a bit); optional

BackGradientMode if two background colors are used, the direction of the gradient between them; top to bottom, left to right, top left to lower right, or top right to lower left

BackColorAlpha transparency for the background colors for the chartIf only one background color is used, that color is applied to the entire background.If two background colors are used, then the background transitions from one of the colors to the other, based on direction indicated by BackGradientMode.

The chart below was created with two background colors, a light blue and a light yellow, with a direction from top left to bottom right, and a transparency of 200.

Section 5.4: LegendsThere are eight distinct Legends that can be displayed on a FoxCharts chart. (See the example below.) They are individually configurable.

Each legend is an object (a label) in the FoxCharts container. However, they do not function like normal VFP labels. They only exist so properties can be set for them (explained in detail below); FoxCharts uses these properties when it creates the chart. Thus, method code and settings for any other properties are ignored.

There are a number of properties that apply to all legends that behave exactly as they would for normal properties; they will not be explained in detail here.

Alignment

FontSize

BackColor

FontBold

Caption

FontItalic

ForeColor

FontStrikeThru

Format

FontUnderline

FontName

FontCharSet

In addition, there are four custom properties: ForeColorAlpha ForeColor Transparency; see Section 5.3.2 BackColorAlpha BackColor Transparency; see Section 5.3.2. Normally zero Rotation Rotation angle (0-360) for the legend. Measured in degrees, positive for clockwise, negative counterclockwise. Used in conjunction with the Alignment property; normal usage is a small positive value with Alignment =0 (drops down to the right) or a small negative value with Alignment =1 (comes up from the lower left). Most frequently used with the legends along the XAxis (XAxis2Legend) when there is not enough room for all legends if displayed horizontally. RotationCenter Rotation around the center of the legend

Additional specifics for each legend: SideLegend The text displayed is set differently for pie/donuts (property FieldLegend; see Section 4.1.1) and the rest of the chart types (property .Fields(N).Legend; see Section 4.1.2). There are three related properties: ShowSideLegend Logical; if .F., SideLegends are not displayed

LegendPosition Controls where the SideLegend is displayed; possibilities are on left or right, top or bottom, horizontal or vertical

LegendHideWhenNull Logical; for pies, doughnuts, and simple bars, indicates whether the legend is not displayed if the value is .Null. Shapelegend The word shape here applies to all the various shapes that can be displayed: slices, points, bars, etc. There are three related properties:

ShowValuesonShapes Logical; if .F., ShapeLegends are not displayed

PieShowPercent Logical; if .T., percents are displayed instead of values ShapeLegendExpression If non-empty, a character expression to be executed; returns the new ShapeLegend text. See Section 8.6

XAxis Does not apply to pies and doughnuts

XAxis2Legend The text displayed is obtained from the source cursor, in the field identified by .FieldAxis2. If there are too many legends to display, they can either be rotated (see above) or some of them can be left blank; e.g., only filling in every other or every third legend. Does not apply to pies and doughnuts YAxis Does not apply to pies and doughnuts

Scalelegend The text displayed is obtained from scaling, which is explained in detail in the next section. Does not apply to pies and doughnuts. There is one related property:

ShowScale Logical; if .F., ScaleLegends are not displayedFor each of the legends, the chart will expand to fill the unused space if the legend is blank or does not apply.

Section 5.5: ScalingScaling refers to the determination of which values are displayed on the vertical axis (Y-Axis). This includes the minimum and maximum values displayed, as well as the number of legends displayed and the interval between the legends. The default is that all of these values are calculated automatically. The properties below are used to override this default calculation.

ShowScales if .F., scales are not displayed ScaleDivider All displayed values in the ScaleLegend are divided by this value. Normally the value is one; other values (presumably powers of ten) allow for easier display of large values (All values in $Millions)

ShowValueZero Forces display of the X-Axis (line Y=0). Normally .T., a setting of .F. allows display of a chart that does not include a line for zero

Scale Step size between horizontal bars (see section 5.6.3). If zero, this value is calculated automatically, and is chosen so that the increment between successive scale values will be a power of ten times one of 1, 2, 2.5, or 5. BarsperScale Number of horizontal bars (see Section 5.6.3) per each legend.

MinNumberScaleLegends Minimum number of scale legends to display (if Scale is calculated automatically) MinValue Minimum value to be displayed; if .F., this will be calculated automatically. The minimum legend displayed will be a multiple of the Scale property that is less than or equal to this value. MaxValue Maximum value to be displayed; if .F., this will be calculated automatically. The maximum legend displayed will be a multiple of the Scale property that is greater than or equal to this value.

Scaling example

Notes: The sample above was created using MinValue of 250,000, MaxValue of 750,000 and of MinNumberScaleLegends of 4.

Nothing prevents setting values for MinValue or MinValue that do not include all the values being displayed; a line chart, in particular, can show values that go completely off the normal chart area, even off the visible page, as in the example above.The formatting of the legends on the vertical axis is described in Section 5.4Section 5.6: Lines, Bars, Axes, and Tick MarksThis section refers to the lines, bars, axes, and tick marks which can be drawn within all charts (except for pies and donuts). ShowAxis if .F., no lines, bars, or axes are displayedSection 5.6.1: Lines ScaleBackLinesType Numeric, indicating which lines (if any) are drawn: horizontal (default), vertical, neither, or both

ScaleLineColor Numeric, RGB value for the color

AxisAlpha Numeric, transparency (this value is used for both lines and axes) ScaleBackLinesWidth Width, in pixels ScaleBackLinesDash Line style, in pixels (solid, dotted, etc)There are separate settings for line Y=0 (displayed when the chart shows both positive and negative values) ShowLineZero: To force separate color for the X-Axis ScaleLineZeroColor: Numeric, RGB value for the color for the X-Axis

Both Horizontal and Vertical lines, dotted lines (ScaleBackLinesDash = 1)Section 5.6.2: BarsBars here means the alternating background shaded areas in a chart ScaleBackBarsType Numeric, indicating which bars (if any) are to drawn: horizontal (default), vertical, neither, or both ScaleBackColor Numeric, RGB value for the color

ScaleBackAlpha Numeric, transparency (this value is used for both lines and bars)

Both Horizontal bars, color = (255, 255, 0), ScaleBackAlpha = 200Section 5.6.3: Axes AxisColor Numeric, RGB value for the color

AxisAlpha Numeric, transparency (this value is used for both lines and axes)Section 5.6.4: Tick Marks

ShowAxis2Tics if .F., Tick Marks are not displayed TicLength Length, in pixels

MinValue of -200,000, ScaleLineZeroColor of (255,0,0), TicLength of 12

Section 5.7: ToolTipsTooltips in FoxCharts emulate native VFPs tooltips, in that they display a pop-up control as the mouse passes over a shape in the chart.

The tooltips in FoxCharts are implemented completely differently however; there is a ToolTip control (a label) in the FoxCharts container, and you can modify the normal properties that apply to a label, including the font name and size, background color, etc.

At runtime, FoxCharts creates a form level label for its tooltips and transfers all the appropriate properties to it. Thus, care must be used in determining what properties can be modified; see the Help file for more details.

This requires that ThisForm.ShowTips = .T. Method ShapeToolTip allows further customization; see the Help file for details. You can also use your own ToolTips class, or even the VFPX Ctl32 BalloonTips class. If so, you have to manage the tooltips by yourself. Start by disabling the current tooltips setting ShowTips to .F., and put your custom code in ShapeMouseEnter and ShapeMouseLeave events. For examples of this, see the Help fileSection 5.8: MarginsFive properties control the empty space around the perimeter of a chart. All of these properties are expressed in pixels. Margin the number of pixels left blank around the entire chart

MarginTop additional margin to be added to the top of the chart

MarginLeft additional margin to be added to the left of the chart

MarginRight additional margin to be added to the right of the chart; more likely to be used than the others, as the Side Legends can butt up against the right margin of the chart MarginBottom additional margin to be added to the bottom of the chart

Section 5.9: Chart-Specific Properties

Section 5.9.1: Pies and Doughnuts PieCompensateAngles if .T., a wide ellipse; else, see PieForceCircle

PieForceCircle if .T., a circle; else a normal ellipse PieLegendDistance The relative distance of the shape legend in the slice to the radius of the circle; 0 = center of the pie; 1 = edge of the pie PieShowPercent Logical, indicates whether the values displayed in the shapes are percents. Only applies if ShapeLegends is .T.

PieDetachSliceonClick Logical, allows detachment of a slice on a mouse click PieDetachSliceonLegendClick Logical, allows detachment of a slice on mouse click over the associated side legend PieDetachPixels The number of pixels that a slice is detached PieDetachAnimationSteps The number of steps taken when a slice is detached, producing an animation effect PieGradCenterDistance The relative distance of the center of center point when the gradient brush is applied; 0 = center of the pie; 1 = edge of the pie. Used together with .PieGradCenterAngle PieGradCenterAngle The angle of the center of center point when the gradient brush is applied; 0 to 360; 0 = right; 90 = down, 180 = left, 270 = up. Used together with .PieGradCenterDistance PieEnhancedDrawing Enables enhanced drawing mode, with all edges drawn separately, providing a better visual effect.

PieDirection Indicates the direction that slices are drawn; 0 = clockwise, 1 = counterclockwise.

Section 5.9.2: Lines and PointsThe following properties only apply if .Depth = 0. LineCaps Logical, indicates whether line caps are shown. LineCaps are the shapes that are displayed at each data point. PointShapeWidth The width of the line caps, in pixels PointCapsShape Shape used for each line

0 = Different shapes for each line

1 to 10 = Same shape for each line (circles, squares, etc.)

Section 5.9.3: Bars ShowPercentages Logical, indicates whether the values displayed in the shapes are percents. Only applies if ShapeLegends is .T.

BarsSpacesBetween the number of pixels between bars

BarType The type of bar used: 0 = Rectangular

1 = Cylinder

2 = Triangle

BarsLegendType Legend position:

0 = Default

1 = Vertical, top to bottom

BarsLegendDirection Legend direction:

0 = Horizontal

1 = Vertical, top to bottom

2 = Vertical, bottom to top

Section 5.9.4: Area Area3DTop Logical, indicates whether a line will be drawn on the top of the 3D Area chart. AreaDrawBorders Logical, draws borders around each Area piece.Section 6: Printing Your Chart

Four different mechanisms are provided to allow you to use your chart (by saving or printing) after it is created.

Section 6.1: Printing Directly, Using GDIPlusX FunctionsLOCAL loBmp as xfcBitmap

loBmp = Thisform.Foxcharts1.oBmp

loBmp.ToPrinter(tnStretch, tcPrinterName, tnOrientation, tnAlignment) The parameters are described in detail in the Help file. Section 6.2: Saving the Chart to a FileThisform.Foxcharts1.SaveToFile (tcFileName)

There are a number of image formats available. The format is determined by the extension of the file name. The recommended formats are PNG and EMF. Other supported formats include JPEG, GIF, and TIFF.Section 6.3: Embedding in a Report (FRX)A chart created by FoxCharts can be used directly in a report by adding an image to the report and setting its properties appropriately.

Drop an "Picture/OLEBoundControl" on the report designer surface. In the Properties dialog that appears, select Expression or variable name for the Control Source Type. In the "Control source" TextBox, put the image object name: oFoxChart.

The report designer needs to access the image object, so the object must be a Private or Public variable. Immediately before calling the report, use code similar to this:

SET REPORTBEHAVIOR 90

PRIVATE oFoxChart

oFoxChart = ThisForm.Foxcharts1.ChartCanvas

REPORT FORM Section 6.4: Printing with the Designer using Vectorial Chart in EMF

This option is very similar to the previous option, except the image is stored in an EMF image file, which allows perfect chart images in reports, as EMF images are redrawn each time to the desired size. Instead of storing an image, an EMF image file stores a list of function calls issued to the Windows graphics layer GDI in order to display an image on screen.

The procedure for using an EMF file is identical to that in section 6.3, except use oFoxChart.DrawReport() as the control source.

The report designer needs to access the image object, so the object must be a Private or Public variable. Immediately before calling the report, use code similar to this:

SET REPORTBEHAVIOR 90

PRIVATE oFoxChart

oFoxChart = ThisForm.Foxcharts1REPORT FORM

For more on EMF images, see http://en.wikipedia.org/wiki/Enhanced_MetafileSection 7: Using the Visual Chart DesignerThe process of creating a great-looking, modern chart is an iterative process. There are a seemingly infinite number of combinations of chart types, colors and color palettes, transparencies, gradients and brush types, scaling and other properties to be considered. There are approximately one hundred different properties that can be set. Some properties work only in combination. Others apply only under certain circumstances. Achieving an attractive final result may take dozens (hundreds?) of iterations.

Beyond this, there are matters of personal taste. In particular, choices of desirable colors can vary widely from individual to individual.

Thus, it is extremely ironic that to produce a chart, the most visual of results, all the available tools have been completely non-visual whether setting properties in code (as has been done throughout this paper), or by using PEM Editor or its outdated predecessor, the Property Window.

The Visual Chart Designer (hereinafter referred to as VCD) was born to fill this vacuum. It is designed to:

run when a chart has already been drawn and is visible on the screen allow you to change the properties of the chart and see the effect of the change immediately. Almost all properties can be changed; those few excluded are primarily the data-related properties discussed in Section 3 view a list of all properties (and their values), or all properties that are non-default, or all properties that have changed since a given cut-off point copy the list of properties to the clipboard (optionally with their descriptions) in a format that allows them to be pasted directly into the method that creates the chart. Not surprisingly, this is the method used to create all of the samples provided in this paper.The effects of this are two-fold:

The developer can concentrate his/her time on creating the data (Section 4) and making a reasonable start on the remainder of the properties. Then, he can run the chart, use VCD to modify the settings as needed, export the list of changed properties to the clipboard, and paste them back into the form to re-create the chart exactly as desired.

This can also be provided for capable end users. This capability allows them to fine-tune reports to their own needs and tastes. In a sufficiently robust system, one could save these settings for easy retrieval, by user.The example below shows VCD in action. The example is the VisualChartDesigner_Sample form in the Samples folder. The Visual Chart Designer form itself (on the bottom) is opened by clicking on the Chart Options button.

Changing any of the properties in VCD, on any of the nine tabs in the pageframe, causes the chart to be re-drawn immediately. In addition, there are tooltips on each object which list the name of the property that is controlled, its value, and its description (as you would see in PEM Editor or the Property Window)

The Properties tab can be visited at any time to see a list of the FoxCharts properties. The list can optionally include the description for each property and/or the appropriate With / EndWith structure. The list can then be saved to the clipboard for later pasting.

The distinction between non-default properties and changed properties may not be immediately clear, but is quite important.

Non-Default Properties is the standard definition of all properties that have been changed, ever.

Changed Properties means all properties that have been changed since the last time a cut-off was set. Cut-offs are set by using the method SaveChartProperties(). (See section 8.1). They are also set by using the Clear Changed Properties button above.

A typical use of Changed Properties is to include it immediately after the call to DrawChart() in the form creating the chart. Thus, only the properties changed thereafter in VCD would appear in the list of Changed Properties.VCD can be added to any existing chart by adding a single control to the FoxCharts container: cmdChartOptions of VISUALCHARTDESIGNER.VCX

This control also has a property, lDevelopmentOnly, which will make it invisible and disabled when not in development mode.Section 8: CustomizationThere are a number of different opportunities for customization available. Each of the methods is described in detail in the Help file and/or in their comments. There are also examples of some of these in the Samples folder.Section 8.1: Obtaining Current Chart Properties SaveChartProperties sets a cut-off point so that a later call to GetChartProperties (below) with a parameter for Changed Properties will return only those properties that have changed in the interim.

GetChartProperties returns a list of chart properties; this method is what is called on the Properties tab of the Visual Chart Designer. All of the controls on that tab are used to create the parameters passed to this method.Section 8.2: Changing Scaling Values and Legends GetScaleValue returns the list of values displayed as the scale legends. The default method returns values in identical steps. The comments indicate how to create scale legends where the steps are not all the step size. (See form JN_Sample3 in the Samples folder.)

GetScaleLegend Paired with GetScaleValue to return the scale legends; can also be used to over-ride individual scale legends with selected text; Zero for the number 0, for instance.

Section 8.3: Drawing Custom Images AfterChart: An event that occurs immediately after the chart is drawn, but still before the image object is updated. Use this when you want to draw something specific in your chart not related to the chart properties, such as a watermark or your company's logo. This functionality is for users that are familiar with GdiPlusX. In order to draw in the Chart canvas, you will need to use the GdiPlusX drawing commands, such as "DrawImage". GdiPlusX support is not in the scope of this white paper (nor the Help file, for that matter). Please refer to GdiPlusX at the VFPX web site for more detailed information, or post your questions in the VFPX forums at Codeplex.

Section 8.4: Click and DblClickWhen these events occur, a number of properties are pre-populated into the FoxCharts container; full details and examples can be found in the Help file.

Section 8.5: Mouse movement over a Chart Shape ShapeMouseEnter occurs when the mouse enters an object

ShapeMouseLeave occurs when the mouse leaves an object

ShapeMouseMove occurs when the mouse moves over an object

ShapeShapeToolTip occurs before the default tooltip of FoxCharts is displayed

When any of these events occur, a number of properties are pre-populated into the FoxCharts container; full details and examples can be found in the Help file.

Section 8.6: Shape LegendsProperty ShapeLegendExpression, if not empty, specifies an expression which will be executed to replace the default ShapeLegend text. This allows full customization of the text to be displayed in (or near) chart shapes. It may be any valid VFP expression.A full description of ShapeLegendExpression can be found in the Help file.

Contact InformationThis document was written by Jim Nelson.

Jim.R.Nelson@GMail.Com(805) 498-9195 (Voice)

(720) 837-3536 (Cell)