See the License.txt file for License, Disclaimer and Copyright information.

David Berneda

100% compatibility with existing saved Forms containing TeeCharts is vital and

should work fine.

Simply open the Form containing your charts and save it again. It will be

automatically converted to use the new properties of TeeChart 4. Please backup projects before migrating them.

No special action required

Please backup your original version 3 project before upgrading to Version 4.

You will need to 're' "Add to Project" the TeeChart Pro AX Control to add the new properties and methods for TeeChart Pro version 4 classes.

This may require you to re-add these lines to the TChart.h file (for some projects this will apply to other TeeChart Classes) which are removed after importing the new class definition. An example is included below. This will be slightly different (CLSIDs) in your project so you should not use the example directly.

=============================

#if !defined(AFX_TCHART_H__FDFDC795_03EF_11D2_B7B6_DDA81BDA2709__INCLUDED_)

#define AFX_TCHART_H__FDFDC795_03EF_11D2_B7B6_DDA81BDA2709__INCLUDED_

#if _MSC_VER >= 1000

#pragma once

#endif // _MSC_VER >= 1000

// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_TCHART_H__FDFDC795_03EF_11D2_B7B6_DDA81BDA2709__INCLUDED_)

==============================

Some properties are now obsolete or have been replaced, but they still exist for compatibility with TeeChart 3.0 version.

Some methods have been deleted or moved or replaced. These are not-frequently used methods, and an alternative way to do the same is described here.

The editor dialog now pops up in few tenths of a second both at design-time and run-time, and uses initially around 20Kb. Memory is dynamically allocated while the user navigates across the editor tabs because each tab is loaded the first time it's requested.

This subcomponent draws a back "wall" in the same way the LeftWall and BottomWall do:

The Frame (TPen ) and BackColor (OleColor ) properties still exist for compatibility, but now they should be replaced with Wall.Back.Pen and Wall.Back.Color respectively:

By default, the Walls.Back.Brush.Style property is set "bsClear", to make the default Chart back rectangle transparent. Now the Walls.Back.Pen (the old Chart1.Frame) is set to Visible according to the Walls.Visible property. So, if Visible is set to False, the back rectangle is no longer displayed.

Chart1.Walls.Left.Size = 8

Chart1.Walls.Left.Dark3D = False

This property determines if the right and top sides of walls would be painted with a darker color or with the normal wall background Color.

It is used only in 3D mode and when the wall Size property is greater than zero.

This Chart sub-component includes the properties used to control the 3D aspect.

It has the following properties:

The normal Canvas, using Windows GDI calls, allow 3D Rotation and Elevation of 90 degree (from 270 to 360) only. This is because there is no calculation of what to draw first and what next, depending on those angles.

With the OpenGL Canvas, full rotation and elevation is provided.

When Orthogonal is True in 3D mode, rotation and elevation are disabled.

Zoom is for 3D mode or 3D Orthogonal. Not for 2D mode (to not loose speed).

The "ZoomText" property controls if, when Zoom is applied to a chart, it’s fonts will be zoomed or not. When ZoomText is True (the default), all font sizes are changed according to the zoom quantity. When False, the current selected font sizes aren’t changed.

(This applies to all fonts like Legend, Marks, Axis labels, Title, etc).

Other already existing related properties are: Chart1.Aspect.View3D, Chart1.Walls.Visible, and Chart1.Aspect.Chart3DPercent. Functionality of them is maintained in this new version.

Chart1.Aspect.Zoom = 80 ' %

Chart1.Aspect.Rotation = 330 ' degrees

Chart1.Aspect.Elevation = 330 ' degrees

Chart1.Aspect.Orthogonal =False

Chart1.Aspect.View3D = True

Chart1.Walls.Visible = True

Chart1.Aspect.Chart3DPercent = 75 ' % depth

The Gradient has now three new styles:

gdFromCenter

gdFromTopLeft

gdFromBottomLeft

This new Axis, which is not visible by default, is used to display either the Series Titles or a 3D Series Z values in the "depth" dimension, along the right-bottom side of the Chart.

Chart1.Axis.Depth.Visible = True

The Surface Series now displays Z coordinates using this Axis. The DepthAxis has almost the same properties and methods as the other axes, like Increment, Minimum and Maximum, Label attributes, Ticks, Grids and so on.

It also works for DateTime "Z" coordinates.

Rotated Surface with 3 axis ( Left, Bottom and Depth axis ) :

The "DepthAxis" can also be "Inverted", but cannot be logarithmic.

Now Axis labels can be displayed as multi-line text instead of a single line of text.

Lines are separated using ascii char #13).

Example for series labels:

TChart1.Series(0).Add 1234, "Hello" & chr$(13) & "Baby" , vbRed

TChart1.Series(0).Add 2000, "Good" & chr$(13) & "Day" , vbBlue

Example for DateTime labels:

The following will show the bottom axis labels in two lines of text, one

showing the month and day, and the second line showing the year:

Feb-28 Mar-1 ..

1999. 1999 ..

TChart1.Series(0).AddXY DateValue( "Feb-28-98" ), 100, "", clTeeColor

TChart1.Series(0).AddXY DateValue( "Mar-1-98"), 200, "", clTeeColor

TChart1.Series(0).AddXY DateValue( "Mar-2-98"), 150, "", clTeeColor

TChart1.Series(0).XValues.DateTime = True

TChart1.Axis.Bottom.Labels.DateTimeFormat = "dd/mm/yy hh:mm:ss" ' <-- space

If you set the Axis.LabelsMultiLine property to True, then the axis will

automatically split labels in lines where it finds an space.

TChart1.Axis.Bottom.Labels.MultiLine = True

Will use the formatting divided in two:

'mm/dd' for the first line

'hh:mm' for the second line

At run-time you can always split the label into lines programatically,

using the OnGetAxisLabel event:

Private Sub TChart1_OnGetAxisLabel(ByVal Axis As Long, ByVal SeriesIndex As Long, ByVal ValueIndex As Long, LabelText As String)

TeeSplitInLines(LabelText,' ');

end sub

The global "TeeSplitInLines" procedure converts all spaces in "LabelText" to

line separators (returns).

The axis LabelsAngle property ( label rotation in degree angles 0, 90, 180 or 270 ), can

also be used with multi-line axis labels.

All axis now have the "GridCentered" boolean property, which, when True, will draw

the grid lines between every label and the previous one, instead of drawing the grid line

at the same label position.

By default is False. Setting it to True is very useful to separate intervals:

Chart1.Axis.Bottom.GridCentered = True

Centered bottom axis black Grid lines:

Now Series can define their HorizAxis and VertAxis properties to show both axes (left and right) and (top and bottom)

TChart1.Series(0).HorizAxis = aBothHorizAxis

TChart1.Series(0).VertAxis = aBothVertAxis

Both axes will scroll or zoom as well.

Now all Axis have this new property to control where should the axis be located.

In this example, the axis is moved 50% of the total Chart width, so it is shown at the chart center:

Chart1.Axis.Left.PositionPercent = 50

The new "PositionPercent" property applies to all axis, the default ones (Left, Top, Right, Bottom) and the custom user-created ones. "PositionPercent" can also be a negative number, or a positive number greater than 100. This allows moving the axes outside the Chart rectangle:

Chart1.Axis.Left.PositionPercent = -10

Chart1.Panel.MarginLeft = 15

Chart1.Axis.Left.StartPosition = 20

Chart1.Axis.Left.EndPosition = 50

All Series associated to the "stretched" axis strech their drawings as well.

These properties are also expressed in percent of the total default axis space.

They also apply to horizontal axes and to all custom-created axes (see below).

This powerful new feature allows "extra" axes to be created and associated to any Series, and to any Series type (Line, Bar, Point, etc).

Together with the above "PositionPercent" and "stretching" new properties, now it’s possible to have unlimited axes floating anywhere on the chart.

Axes have a new property which controls the logarithmic base ( 2, 10, etc) used to plot values and calculate label values:

Chart1.Axis.Left.Logarithmic = True

Chart1.Axis.Left.LogarithmicBase = 2

Only positive values are accepted.

In TeeChart Pro 3.0, logarithmic axes did not display labels with the expected logarithmic style (10,100,1000 and so on...)

New in this version, axes plot labels that correspond to each exponent of the logarithmic base ( by default the base is 10 )

It’s necessary for this automatic labelling to have the axes Increment property set to zero (the default Increment). Otherwise, labels will be calculated as with non-logarithmic style.

With Chart1.Axis.Left
 .Logarithmic = True
 .Increment = 0 ' the default
 .SetMinMax  1, 1E10  
 .Labels.ValuesFormat = "#e+0" ' exponential format
End with

Minor axis ticks are now displayed at logarithmic increments.

For example, in the above logarithmic example, setting MinorTickCount to 8 will display each tick at it’s correspondent logarithmic position:

Chart1.Axis.Left.MinorTickCount = 8

Chart1.Axis.Left.MinorTicks.Color =vbRed

Chart1.Axis.Left.MinorTickLength =6

Chart1.Axis.Left.Logarithmic=True

Chart1.Axis.Left.Inverted=True

Chart1.Axis.Bottom.Logarithmic=True

Chart1.Axis.Bottom.Inverted=True

Now the Legend has a Clicked function to determine which Legend Item index is under the

mouse (or any other XY pixel coordinates):

Private Sub TChart1_OnClickLegend(ByVal Button As TeeChart.EMouseButton, ByVal Shift As TeeChart.EShiftState, ByVal X As Long, ByVal Y As Long)

Dim tmp As Integer

tmp = TChart1.Legend.Clicked(X, Y)

If tmp <> -1 Then

MsgBox ("Clicked legend item: " & (TChart1.Legend.FormattedValue(0, tmp)))

End If

End Sub

When the Legend is aligned horizontally (top or bottom), now the number of rows can be specified:

Chart1.Legend.MaxNumRows:=3;

By default, MaxNumRows is 10 (ten), meaning the Legend will show at maximum 10 rows.

Setting it to 0 (zero) will make the Legend to show as many rows as necessary.

Legend now publishes a Brush property that can be used to fill the Legend background:

With Chart1.Legend

.Brush.Style = bsClear

end with

Now the Legend publishes a property that can be used to fill the Legend background with a Bitmap:

With Chart1.Legend

.BackImageLoad "myimage.bmp"

end with

This new Series type derives from a PointSeries, adding a "LinePen" Pen property to draw a Bezier line every 3 points.

A bezier line is a curve which passes over every 3 points of a Series.

There are several ways to calculate the bezier curve points. This Series uses the same method as Windows (GDI BezierTo function).

Open GL Charts benefit from full 360º rotation.

In previous versions, the "Period" property for several functions was interpreted as "Period +1".

This applies to Momentum, RSI, MovingAverage and ExpAverage functions.

That means, for example, a MovingAverage of Period 3 was using 4 points for each calculation.

This design consideration was not perfect, so now in TeeChart Pro 4, the "Period" property is handled as it should be. A Period of value 3 will use 3 points for each calculation.

ITeeFunction.BeginUpdate;

ITeeFunction.EndUpdate;

These methods can be used when adding or modifying many values at once at a source Series, to recalculate the function just one time, when finished adding points:

TChart1.Series(0).FunctionType.BeginUpdate

...

many modifications...

...

TChart1.Series(0).FunctionType.EndUpdate

In version 3, the function "Period" property was expressed always in number of points.

Now in this new version Period can be defined to be a range. This is very useful when using Date-Time series and want to express the "Period" of the function in a date-time step like "OneMonth" or "OneDay".

There is a new property "PeriodStyle" which controls how is "Period" expressed.

So you can now plot, for example, the "monthly average of sales" function just using a normal "Average" function on a date-time source series and setting the function period to "one month":

{ Place a Series1 and fill it with datetime data values at runtime (or from a database) }

TChart1.Series(1).SetFunction tfAverage

TChart1.Series(1).FunctionType.PeriodStyle =psRange

TChart1.Series(1).FunctionType.Period = TChart1.GetDateTimeStep dtOneMonth

TChart1.Series(1).DataSource = "Series0"

This will result in several points, each one showing the "average" of each month of data in Series0.

It’s mandatory that points in the source Series0 should be sorted by date when calculating functions on datetime periods.

The range can also be used for non-datetime series:

TChart1.Series(1).SetFunction tfAverage

TChart1.Series(1).FunctionType.PeriodStyle =psRange

TChart1.Series(1).FunctionType.Period=100

TChart1.Series(1).DataSource= "Series0"

This will calculate an average for each group of points inside every "100" interval.

(Points with X >=0, X<100 will be used to calculate the first average, points with X >=100, X<200 will be used to calculate the second average and so on... )

Notice this is different than calculating an average for every 100 points.

When the function "Period" is greater than zero (so it calculates by groups of points),

the function results are added to the series by default at the "center" position of the Function Period.

Now there is a new property which controls "where" to place function calculations inside the full period space.

TChart1.Series(1).FunctionType.PeriodAlign = paCenter ' <-- by default is centered

The "paFirst" and "paLast" constants will plot calculations at the start and end "X" coordinates of each "Period".

Every blue point shows the "average" using all points between the first day and the last day of the month.

The "average" is plotted at the end of the month.

In version 3, the Trend was calculated using the CurveFitting algorithm.

This took a lot of CPU time. Now it calculates the Trend points using the standard formula, which results in a much faster calculation speed.

Now ODBC Datasource connectivity detects NULL field values properly, and adds null points to the Series using the Series.AddNull method and / or AddNullXY methods.

Shows the user the dialog associated to the Series, without the whole Chart editor:

Procedure EditOneSeries(ASeries:Integer);

Example:

EditOneSeries(0)

The other one shows the user a "Save to..." dialog asking for a native TeeChart file name and path ( ie: c:\chart1.tee ). You can use the returning string to save it.

Function SaveChartDialog:String;

Example:

Var tmpName : String;

tmpName = TChart1.SaveChartDialog

If tmpName <> "" then

TChart1.Export.SaveToFile( tmpName )

End if

This new method allows inserting null values when using XY coordinates:

TChart1.Series(0).AddXY 1.234, 5.678, "", vbRed

TChart1.Series(0).AddNullXY 2.2, 3.3, ""

TChart1.Series(0).AddXY 3.3, 8.8, "", vbRed

Now all Series classes maintain an internal list of Series Marks positions. This means you can, at run-time, modify the position of every point's Mark rectangle.

Note that, when Marks positions are customized, zooming or scrolling the Chart will not reposition those Marks.

Mark positions can be reverted back to automatic when desired.

( See included VB example of Mark dragging )

As with axes labels, now Marks can show text in multiple-lines.

TChart1.Series(0).Add 1234, "Hello" & Chr$(13) & "World!", vbRed

The Marks sub-component has now a new "Clicked" function method, which returns if a Series Mark is under the mouse cursor (or any XY pair of pixel coordinates):

Dim tmp as Integer

tmp = TChart1.Series(0).Marks.Clicked( x,y )

if tmp<>-1 then MsgBox("Clicked Mark of point: " + TChart1.Series(0).XLabel(tmp))

Now Gantt bars can be customized ( Color, Pen, Style, Brush pattern, etc ), by using the Gantt Series OnGetPointerStyle event:

Private Sub TChart1_OnGetSeriesPointerStyle(ByVal SeriesIndex As Long, ValueIndex:Integer):ESeriesPointerStyle;

if ValueIndex mod 2=0 then result=psRectangle

else result=psTriangle

end if

end sub

As the Pointer Style can now draw shapes in 3D, this also applies to Gantt Series. Gantt bars (or any shape) can be displayed like solids (cube, pyramid, etc).

All Series derived from Point Series, (like Line, Area, Bubble, Gantt, Candle, etc),

have now a new boolean property "Dark3D" ( default True ).It controls if the point segments will be colored using a darker color than the Series color, thus giving a better 3D view effect.

Shadowing can be enabled or disabled using the new Dark3D property:

TChart1.Series(0).asLine.Dark3D = False

This integer property controls the height of the line when Chart1.View3D is True:

TChart1.Aspect.View3D = True

TChart1.Series(0).asLine.LineHeight = 4

Mouse clicks are now detected correctly when "Stairs" property is True.

Now the Bitmap property of the BarBrush can be used to fill the Bar interiors with a bitmap pattern.

TChart1.Series(0).asBar.BarImageLoad "myImage.bmp"

With TeeChart Pro version 3, Bar width's were calculated in pixels.

Now in TeeChart Pro 4.0, Bar width's are calculated in axis scales, only when the new property "AutoBarSize" is set to True (by default is False).

TChart1.Series(0).asBar.AutoBarSize = True

This allows resizing the Bars when the chart is zoomed, thus giving Bars the appearance of being close or far away from the user, when the chart is zoomed in or zoomed out.

Setting AutoBarSize to False will calculate the Bar widths in pixels the first time the Series is displayed, and this width will be permanent even if you zoom or scroll (as TeeChart 3.0 did before ).

Now the Fast Line Series also draw Marks, like LineSeries or any other Series does:

TChart1.Series(0).Marks.Visible = True

A new boolean property "AutoRepaint" controls if new points added to the FastLine will force a redisplay of the whole chart, or will just draw the new added points directly to the Canvas, with as much speed as possible.

When AutoRepaint is False, the Fast Line will draw new added points instead of redrawing the whole Chart and all points. ( Axis scales aren't changed when using this option )

This speeds up drawing a lot. Adding and drawing 15000 points takes one second on a Pentium 166 using Windows 95. ( 20000 points per second on a P200 with NT4 )

Candle Series has two new properties:

TChart1.Series(0).asCandle.Draw3D = True

TChart1.Series(0).asCandle.Dark3D = True

Note: 3D candles have effect only when Chart View3D is True, and only when the Candle Style property is "CandleBar".

Now the Bubble Series makes a better use of the Pointer.Draw3D property.

Triangles and Inverted Triangles are now drawn as 3D Pyramids when Pointer.Draw3D is True:

TChart1.Series(1).asBubble.Pointer.Draw3D = True

As with all other Series derived from PointSeries, Bubbles can now be displayed

as 3D pyramids or cylinders.

Now the Pie Series has a new List of values to determine the "Exploding" in percent ( 0..100%) for each individual Pie Slice.

This works both in 2D and 3D, and also allows Pie rotation.

The Pie automatically resizes to accomodate the space needed by the exploded slices:

TChart1.Series(0).asPie.ExplodedSlice.Value(0)=20 ' <-- 20% exploding for the first pie slice

This new property is a percent integer that is used to automatically explode the largest slice in the Pie:

TChart1.Series(0).asPie.ExplodeBiggest = 30 ' 30% exploding of the largest slice

Now Pie slices below a user define percent or value can be grouped into a single slice.

The options are:

TChart1.Series(0).asPie.OtherSlice.Style = ( can be poNone, poBelowPercent or poBelowValue )

TChart1.Series(0).asPie.OtherSlice.Value = ( any value or percent )

TChart1.Series(0).asPie.OtherSlice.Text = "Other" ' ( Label text for the "Other" slice, by default is "Other" )

As existing slices are not removed, this allows to change on-the-fly both at design and run-time the OtherSlice properties, without having to re-fill again the Series with values.

 Grouped slices also allow rotation and exploding.

You can also move each slice Mark to a custom position. See "Custom Mark positions" in this document.

Now Pie slices can be optionally sorted in Ascending or Descending order, using this property:

Series1.PieValues.Order := loAscending;

Possible values are loNone, loAscending or loDescending.

When Order is loNone (the default), slices are displayed in the same order they are added to the Pie Series.

Note: The slice colors are not preserved when switching the Pie Order. You should specify fixed Colors for each Pie slice to preserve them. (ie: TChart1.Series(0).Add( 123, 'Hello', clRed )

These PieSeries properties have no sense with the current 3d changes.

They have been removed:

Offset3D Chart1.View3DOptions.Elevation

Color3D ( now it is always True )

ShadowColor ( has no effect now, should use Dark3D property )

Shadowed3D ( "" "" "" "" )

CirclePen ( has no effect, should now use the PiePen Pen property )

As with the Pie Series removed properties, now the Polar Series does not include the "PiePen" property.

This was wrongly inherited from ICircledSeries in TeeChart Pro 3. New projects should use the "CirclePen" property instead of "PiePen."

The Polar Series also supports rotation and elevation when in 3D mode.

The PolarSeries "DrawRing" method has now an additional parameter:

Procedure PolarSeries.DrawRing(Const Value:Double; Z:Integer);

"Z" is the Z position where the ring will be displayed.

You can use PolarSeries "StartZ" or "EndZ" properties to draw rings at front and at back Z positions respectively:

TChart1.Series(0).asPolar.DrawRing 1234, TChart1.Series(0).asPolar.EndZ

Now the Brush and BackImageLoad can be used to place a Pattern/Back Image to fill the inside of the polar points:

The Polar Series has two new properties to control displaying of polar point Angles around the circle perimeter:

TChart1.Series(0).asPolar.CircleLabels = True ' <-- show labels !

{ set font attributes... }

With TChart1.Series(0).asPolar.CircleLabels.Font

.Color=vbBlue

.Size=10

.Style.Italic = True

.Style.Bold = True

end with

Cross, DiagCross, Star

Now the position ( Left, Top ) of a Shape can be specified as axis values, while the size of the Shape (Width and Height) can be specified in screen pixels:

TChart1.Series(0).asShape.XYStyle = xysAxisOrigin

TChart1.Series(0).asShape.X0 = DateValue( "1^st Jan 1999" ) '<-- in BottomAxis scales

TChart1.Series(0).asShape.Y0 = 1234.56 ' <--- in LeftAxis scales

TChart1.Series(0).asShape.X1 = 100 ' <-- 100 pixels Width

TChart1.Series(0).asShape.Y1 = 30 ' <--- 30 pixels Height

As with BarSeries you may now load a BackImage for the Shape.

When the Shape position is expressed in pixels (that is, when the Shape property "XYStyle" is "pixels" ), the Z position is automatically set to zero (in front).

The Surface has been rewritten so now supports Rotation, Elevation and Zoom (With OpenGL full 360º rotation and elevation) as with any other Series.

When elevation is maximum, we're seeing the surface from the top, thus seeing a "contour" map.
We can "fly" in between a surface from any angle (with OpenGL).

Perspective is also supported by Surfaces, although depending on which combination of zoom, rotation and elevation, it might be necessary to make the Perspective smaller so all surface cells are drawn correctly.

Now the Chart Legend uses the Surface Palette of colors to show the Legend items.

Every legend item corresponds to a Palette item. It shows the Color and the UpToValue property.

You can still use the Chart OnGetLegendText event to customize the legend item text.

TChart1.Series(0).asSurface.PaletteSteps=10

This new Legend style also applies to the new TContourSeries. Setting the PaletteSteps property to the same value as Contour "NumLevels", will use a different color for each Contour "level" at the Legend:

TChart1.Series(1).asSurface.PaletteSteps = TChart1.Series(1).asSurface.NumLevels

Using the new Chart1 DepthAxis sub-component (Axis.Depth), the Surface Z values are displayed along

the right-bottom side of the Chart box, in the "Z" (front to back) direction.

(See blue axis labels at Surface picture above).

This is compatible with setting the point color to "clNone" to draw holes too:

TChart1.Series(0).asSurface.AddXYZ 8, 0, 2 , "", clNone

Using the new Chart "DepthAxis" property, now it's possible to draw Surface series "from the back" by setting the DepthAxis "Inverted" property to True:

TChart1.Axis.Depth.Inverted = True

This also works now for horizontal axis:

TChart1.Axis.Bottom.Inverted = True

Now it's possible to configure a Surface Series to have up to a maximum of 500x500 cells.

Memory is dinamically allocated and deallocated.

This new Series is very similar to a PointSeries, adding Z values for each point:

TChart1.Series(0).asPoint3D.AddXYZ 123, 456, 789 , "Hello", vbRed

Unlike Surface or Contour Series, the Point3D Series does not impose any limit on the X,Y,Z coordinates or number of points. Think as it is the same as a normal Point Series, with each point located inside the chart axes in a different XYZ position.

in the same order they were added to the Series:

TChart1.Series(0).asPoint3D.LinePen.Color = vbRed

This new function calculates the Standard Deviation ( also "Complete" StdDeviation ) of the source Series point values.

This new Series type is very similar to a Polar series (actually, both Polar and Radar derive from a common CustomPolarSeries class ).

Every point in the Radar series is drawn at a different angle ( 360 degrees divided by total number of points ).

Like Polar Series, more than one Radar series can be plotted together in the same chart (better if all Radar series have the same number of points).

All properties of Polar Series also apply to Radar.

As with Polar series, Grid lines and labels are controlled by LeftAxis and BottomAxis axes.

The first Series controls the "CirclePen" property (shown in blue color above).

Both Polar and Radar can now fill the area bounded by points using the Brush property.