TeeChart Pro 2013
New and Improved Features
This technical document describes all changes made to TeeChart component library (FireMonkey and VCL versions) since the release of May-21st 2013.
Internal canvas classes (GDI and GDI+) have been modified extensively. The default graphic canvas for new charts added at design-time is now GDI+ (TGDIPlusCanvas class) instead of GDI (TTeeCanvas3D class).
Switching from one canvas to another can be done at design-time and run-time through the TChart editor dialog (3D -> Render tab), or manually by code:
TeeGDIPlus; Chart1.Canvas :=
uses TeCanvas; Chart1.Canvas := TTeeCanvas3D.Create
An alternative is to use the TeeGDIPlus component:
TeeGDIPlus1.Active := True;
Using the TeeGDIPlus component allows persisting settings, like antialiasing and default text quality.
GDI+ offers several features that cannot be done with GDI (or are done better):
· Color alpha (transparency)
Any color (pen, font, gradient, brush, etc) is now treated as a proper 32bit color with RGB and Alpha components.
The only limitation is pseudo-colors can’t be used (clBtnFace, clWindow, etc).
Setting a color alpha transparency can be done at design-time using the chart editor dialogs.
Using IDE Object Inspector is also possible, but in VCL there is a limitation that TColor is a signed integer, and so values greater than MaxInt (2^31-1) cannot be manually typed (the Object Inspector raises an exception).
Setting colors by code:
Chart1.Legend.Pen.Color := RGBA( 64,64,64, 128) ; // 128 = semi-transparent
· Line Antialias
GDI+ has line antialias, which produces much better looking charts, without jagged diagonal and curved lines and polygon boundaries.
There’s a speed penalty when using antialias that is not a problem unless you’re plotting many many points and/or performing animations.
If not using a TeeGDIPlus component, Antialiasing can be changed at runtime by code like:
TGDIPlusCanvas(Chart1.Canvas).AntiAlias := False
· Filled Pens
The base TTeePen class has a new Fill property (of type TTeeBrush) that is only functional when using the GDI+ canvas. Wide borders and lines (of width 2 or more) can now be filled with textures and gradients.
Series1.Pen.Fill.Gradient.Visible := True
· Multi-color gradients
The GDI+ canvas allows gradients with more than 3 colors.
The base TTeeGradient class has a new Colors collection property. Each color item in the collection has Offset and Transparency properties:
Chart1.Gradient.Colors.Add( 0.3, clGreen, 50) // 0.3 means 30%, 50% is transparency
· Smooth texturing
GDI+ uses brush images to fill polygons, rectangles and rounded rectangles with better speed and output results than GDI.
Rotating, translating and scaling elements (like chart titles, legend, series, etc) are enabled using GDI+ transform methods.
When filling polygons with gradients or textures, or when drawing rounded-corner rectangles, clipping should be done manually in GDI (which is not 100% perfect), while in GDI+ this is done automatically and better.
In GDI canvas, “smooth” shadows are painted using an intermediary bitmap with a “blur” filter applied. This is a very slow operation, although the output is quite good.
In GDI+, there’s another approach to draw smooth shadows that is way much faster with a little loss in quality. Shadows are done using gradients and transparency.
There’s one thing that is much faster to paint in GDI than GDI+: non-solid pen lines.
Due to this, a big decision has been taken: axis grid lines are now solid instead of dotted:
Chart1.Axes.Left.Grid.Style := psSolid;
Grid lines can easily be changed again to be non-solid, using the axis editor dialog or Object Inspector.
With all the new changes, the GDI+ canvas is now faster than GDI in many occasions, as soon you use any effect like transparency, gradient fills, or shadows.
GDI is still faster than GDI+ when you dont need antialiasing and any fancy effect, for example when plotting FastLine or Surface series with many many points, but the difference between them is now much smaller, and you can always set back to GDI canvas.
· TTeeGradient Colors collection property
Gradients can be now configured to use multiple colors in FireMonkey and also in VCL with GDI+ canvas (the limit was three colors maximum with VCL GDI).
Each color item has Color, Offset and Transparency properties.
· New Fill property (of type TTeeBrush) for VCL GDI+ and FMX, to paint line interiors using gradients or texture images:
· New class methods to set and get the “Alpha” transparency (from 0 to 255) of a given color:
ColorAlpha(const AColor: TColor): Byte; // Returns “Alpha” byte from color
ColorFrom(const AColor: TColor; Alpha:Byte): TColor; // Sets “Alpha” to color
· New method to draw a round rectangle in 3D (GDI+ only)
RoundRectWithZ(const R:TRect; Horiz,Vert,Z : Integer)
· New ITeePath interface and TeeCanvas CreatePath method to fill and/or stroke “paths” using the current Pen and Brush/Gradient properties.
font quality for GDI+. When a font
object “Quality” property is “default” (gpfDefault), the Canvas FontQuality is
For GDI+ canvas, the default font quality is now automatic, depending on the font size it is selected as “ClearType” (small fonts up to size 20), and “Best” for bigger font sizes. This gives the best combination of qualities and avoids “blurring” text.
You can always force a specific quality per-Canvas (global to all fonts), and also to a specific font object (ie: Chart1.Legend.Font.Quality)
The TTeeAnimate and TAnimation classes have been completely rewritten to provide smooth animations using a separate thread, and with more precision.
Animations are now configured in milliseconds instead of number of frames, using the Duration property.
The TTeeAnimate.Speed property defines the desired maximum number of frames per second (by default 60).
Frames that can’t be painted are skipped.
· New TAnimation Timing property.
Defines the interpolation function used to calculate each animation frame.
Values are: Linear, Sine, Square, Cubic. (Back, Bounce and Elastic)
· New TimingStyle property to customize the timing acceleration: atIn, atOut, atInOut
· New StartTime property, in milliseconds.
· DurationFrames function returns the expected number of frames, according to Animate.Speed property (the desired maximum number of frames per second).
· TwoWay boolean property (performs the animation and the inverted animation in the same amount of time)
· Inverted boolean property. The animation performs as opposite.
Existing animations in previous versions (Expand
and SeriesAnimation) no longer use TTimer components, they internally use the
same TTeeAnimate system instead.
A generic “Animation” tool allows creating custom animations, composed of multiple items (individual animations with different properties) and a timeline.
Multiple Animation tools can be added and played simultaneously, each one with specific duration and settings.
Generic animations include NumberAnimation (to animate any integer, datetime or float property) and ColorsAnimation (to make color transitions, for any color property).
New Animations gallery with demos, and editor dialogs for all animation classes.
Animation classes include: Custom, Transform, Series, Expand and Random Points.
· New support to animate all visible Series on a chart, by setting the Series property to nil to indicate all series should be animated.
Changing the global visual aspect of charts has been improved extensively.
· Improved Themes Editor dialog with a visual gallery of available themes applied to the target chart:
· New “Flat” theme, a minimal theme using “Roboto Th” font (the Android 4.x default font)
· New methods at TThemesList class to apply any existing chart formatting as a theme for any other chart. In other words, any chart can be used as a “theme” for any other chart.
Only formatting is applied. That includes pens, brushes, gradients, fonts, etc.
Also any chart saved as a native *.tee file can be later reused as a “theme”, and it will appear at the Themes Gallery.
· Redesigned series gallery dialog, with a much better “sub” gallery to visualize different combinations for a single series style.
Sub-Gallery for Pie Series:
· New TeeFunction gallery, with example demos of each function type.
· When changing a series style using the gallery, styles that can’t be applied appear disabled, now this is done internally using a gray-scale filter, which looks better and simplifies the code a good amount.
· Improved Series display, for example now the Maps series (TWorldSeries class) show the map at the gallery:
· New “Templates” tab at Gallery, with pre-defined Charts already using Series, Functions, Tools, etc.
For new Charts, a single click automatically adds a ready-to-use Chart:
· New option to export Chart Series data to JSON format.
Available also at runtime:
j:= TSeriesDataJSON.Create(Chart1); s:= j.AsString;
· OpenDocument Export format
The new TeeODS unit contains a class to export charts to OpenDocument (*.odt) spreadsheet format.
· XAML export format now includes the optional “Transform” elements.
· Transparency property
The Transparency property (from 0 to 100%) has been moved to the base Series class (TChartSeries) and implemented for all series styles.
· New Series.Marks AutoPosition boolean property (default True).
· New protected Transform property (of type TTeeTransform)
boolean property (default
When True, marks aren’t displayed if their associated point is not inside the chart axes space (ChartRect).
· Fill2D property (boolean, default False)
This new property, when True, draws the same filled arrows in 2D than in 3D.
Previously, in 2D mode arrows were always displayed with thin (no filled) lines.
Bar / HorizBar Series
· Automatic calculation of left and right margins
Bubble series now resizes the horizontal axis minimum and maximum values to accomodate for the first (left) and last (right) bubble points sizes, according to their radius.
This is controlled with the Pointer.InflateMargins property (default True).
Note: This only applies when the Bubble horizontal axis scales are also automatic.
Candle (OHLC) Series
· Automatic Candle width
The AutoSize boolean property (default True) calculates the appropiate (best fit) Candle width according to the available horizontal space and the number of candles to visualize.
· Removing gaps (weekends, bank holidays, etc)
When adding Candle data passing the “X” horizontal value as DateTime, the axis will display gaps (holes) for periods where there is not data (for example weekends).
The best solution to this problem, when possible, was to pass the “X” coordinate as a sequential integer number, thus making candles adjacent.
There is a new Candle method now to add data without the need to pass the “X” value:
Candle1.Add( Date, Open, High, Low, Close)
This method will internally convert Date to string, and pass a sequential “X” value.
Another different way to remove gaps is setting this new property to True:
Candle1.RemoveGaps := True
· HighLowColor property (default “cbUseColor”). When “cbSameAsCandle”, the High-Low line is painted using the same color as the candle, and the properties of the HighLowPen property.
· BorderColor property (similar to the above) to paint the candle border using the Pen properties and the same color as the Candle.
· Fixed bug in Clicked method.
The TClockHand class defines how to draw the clock hands with several properties, including border and background attributes, visibility and the percentages of radius, width, height, ending arrow.
· BoxTransparency property (default 70%)
This property draws the Darvas boxes with transparency, and its independent from the Candle Transparency property.
Double Horiz. Bar Series
Horizontal Bar Series
Line, Area, Point Series (and derived series from TCustomSeries)
· New Pointer.Items property
Series Pointers can now be customized individually, for example:
Series1.Pointer.Items.Color := clRed
Series1.Pointer.Visible := False
When a pointer item has been modified, changes to the global Series1.Pointer property will not be used.
To reset a pointer item to its default values, set to nil:
Series1.Pointer := nil
To remove all custom pointer items completely, call Clear:
· New TSeriesPointer FullGradient boolean property (default False)
· New psDonut style for TSeriesPointer.Style property.
Line and Area Series
DrawStyle property (default dsSegments).
Only for 2D
and 3D orthogonal view modes. When DrawStyle is “dsAll”, the line or area is
displayed using a Canvas PolyLine / Polygon call instead of drawing each
When DrawStyle is “dsCurve”, and only for GDI+ canvas, the line is displayed using a smoothing spline algorithm.
When DrawStyle is not “dsSegments”, this allows for example configuring the Pen.Gradient so the whole line uses the gradient colors, instead of using the gradient colors for each segment (segments between each line point), and also using the Pen.JoinStyle property to draw the connections between points.
Pie and Donut Series
· New property Series1.PieMarks.Rotated (boolean) to display rotated marks (work also with PieMarks.InsideSlice:=True):
· New value for MultiPie property (Series1.MultiPie := mpConcentric) to display multiple pie series as concentric donuts, in 2D and 3D.
· New PieMarks.EmptySlice boolean property (default False). When True, series marks for empty pie slices (of value 0) will be displayed.
Polar, PolarGrid, Radar, Clock, WindRose and Rose Series
· New AngleLabels property, merges and replaces all CircleLabelsXXX properties.
New AntiOverlap property automatically calculates the best increment between circle labels.
· Horizontal Axis Ticks and MinorTicks are now displayed, when Visible.
· Several display improvements (using floating point coordinates to avoid pixel-rounding errors)
· Values at Legend are inverted to vertically align with pyramids.
· Multiple Pyramid series display now at the same “Z” depth position.
· Implemented Transparency support
· Improved calculation of left and right margins when the Volumen Pen is big (wide).
Surface, ColorGrid, TriSurface, etc:
Series1.StartColor := TTeeCanvas.ColorFrom( clRed, 128); // Alpha from 0 to 255
· New CircleBrush property to paint backgrounds using gradients and textures.
(This applies to Circled derived series like Polar, Radar, Rose, Clock, etc)
World Maps Series
· New EurAsia map (combines Europe and Asia)
· New Wall RoundSize property.
Walls (specially the back wall) can now be displayed as rounded rectangles.
· Filters property.
Image filters can be applied to a TChart itself (using the internal canvas buffer Bitmap).
The Chart Editor dialog (General -> Mouse tab) has been enhanced with more options to control what happens when the mouse wheel is dragged.
This function calculates the “center of gravity” XY point of its source
series point XY positions.
Centroid position is the average position of all points in the array.
· New tool TRepaintMonitor is an annotation that paints the current “Frames per second” speed when the chart is being animated or repainted lots of times.
· New AllowDrag new property, bands can be dragged using the mouse.
· New OnDragging event. Called while dragging the ColorBand using the mouse.
· New OnResizing event. Called while dragging the ColorBand Start or End edge lines using the mouse.
· New NoLimitDrag boolean property (default True) to allow dragging the color band outside the axis min <--> max limits.
(and also Start and End lines of TColorBandTool) new property: Annotation. To
display text located at line.
New AnnotationValue boolean property, when True it displays the current line value using axis formatting, using the Annotation properties.
· New AxisAnnotation property, to display the current cursor position near the axis.
· New FullRepaint property (default False). When True, the whole chart is repainted while dragging the cursors.
· New RotateGradient property. When the arrow gradient is visible, gradient is rotated following the Arrow.Angle property.
· New Align property, to align the scroller to bottom/right (“saAfter”), or to top/left (“saBefore”), or “saCustom” for custom positioning of the scroll pager sub-chart.
· New NoLimitDrag boolean property (default False) to restrict scroll to main chart axis minimum and maximum.
· New automatic vertical alignment, when using it with “Horizxxx” series like HorizArea or HorizBar.
· New AddSeries and RemoveSeries methods, to customize which series should appear at the scroller chart, now allowing displaying multiple series (as you wish).
· Data changes in the main series are now reflected in the scrollpager chart series.
· New Pointer property, to draw an indicator near the legend palette. It is not visible by default, and has a “Value:Double” property you can set to the desired position in palette range:
For example, using a Surface series1, and a SurfaceNearestTool OnSelectCell event:
procedure TMainForm.ChartTool3SelectCell(Sender: TObject);
if LegendPalette1.Pointer.Visible then
When moving the mouse over the series, this event is triggered and the legend palette will paint the pointer indicator using the selected cell Value and Color.
· New OriginPen property (TTeeHiddenPen) to optionally draw a line at Origin
SubAxes can be added and customized at design-time using the IDE Object Inspector (using the collection editor on any Axis SubAxes property) or using the TeeChart Editor dialog.
At runtime, example:
var MyAxis : TChartAxis;
For example, in the sub-axis chart above, the year labels (2013, 2014, etc) are set to Texts.Position := lpAfterTick.
The default Position is “lpAtTick” (exactly centered at the label tick position).
· New GlobalTransparency property
This property controls the total Legend transparency, including symbols and texts.
The already existing Transparency property is only used when filling the legend background.
· Many editor dialogs have been restructured and improved. There are many more “visual” galleries to customize properties.
· Many modal dialogs have been replaced with embedded versions (modal dialogs aren’t suitable for touch devices).
· New EditTool method (at TeeEditTools unit) to show a modal dialog to edit a single tool component.
· TeePicture Filters editor dialog now includes a live color histogram chart updated when changing filter parameters.
· All these changes in editor dialogs are reused in TMaker and TTree component editors.
· Transform (GDI+ canvas only)
A new protected property intended to be used by the new TransformAnimation, but that can also be manually configured.
Transform includes subproperties for translation, scaling and rotation.
All elements (Title, Legend, Series, etc) will apply their Transform by passing it to GDI+ canvas.
Gradients with semi-transparent colors (GDI+ canvas only) can be painted over pictures (for example Chart1.BackImage, or any other element like Chart1.Legend.Picture).
The following new features apply to all elements derived from this class (Annotations, Chart Legend, Chart Titles, Series Marks, Organizational series items, Numeric Gauge Markers, TreeMap series items, and many other derived classes).
· TeePointerDrawLegend global method.
Some minor fixes to improve displaying pointers with big wide border pens.
· Area series fix, transparency in 3D for the last Area segment.
· Bar, HorizBar series: Cylinder improvements (more smooth look) and better positioning of Marks inside Bars (MarksOnBar property).
· New TFilterItems OnChange event (to notify for example at Filters Gallery dialog to repaint the preview filtered image).
· TTeePen new Fill property (VCL GDI+ and FireMonkey only)
· TTeeBrush Image property is now of type TTeePicture instead of TPicture (TTeePicture provides image filtering, like contrast, blur, etc)
· TTeeFont.SizeFloat property (VCL only, GDI+) enables fine graining of font sizes.
· TTeeFont.Brush property, supersedes Gradient and Picture properties.
· New image filters: Sobel and Sepia.
· New TBackImage Bottom and Right properties, to draw Chart1.BackImage at a custom rectangle.
· New TTeeCanvas StretchQuality property (default sqHigh), to eliminate slow calls to SmoothStretch in GDI+.
· New Chart1.SetChartRect(const R:TRect) method. To customize the axes rectangle boundaries.
· The units TeeToolsGalleryDemos and TeeAnimationsGalleryDemos have been moved from design-time package (DCLTEExx) to the runtime package (TeeProxx)
· Some methods parameters have been prefixed with the “const” attribute (iOS related).
· The Canvas BeginEntity method now accepts an optional “Transform” parameter.
· TChartPen renamed to TTeePen (TChartPen still available)
· TChartBrush renamed to TTeeBrush (TChartBrush still available)
· TAxisGridPen, changed default pen style to “psSolid” and width to “0” (thin solid lines)
· TTeeZoom.Pen.Width changed default to 3 pixels, for better visibility on big screens.
· TSeriesAnimationTool has been moved from TeeTools unit to TeeAnimations unit.
· New FontQuality protected property for GDI canvas, to change the global default font quality for all fonts. (This is similar to GDI+ canvas AntiAliasText property).
· Improved TButtonColor, TButtonPen and TButtonGradient painting symbol when Caption is empty.
· Default Font Size for iOS applications, changed from 15 to 11.
· All TChartAxis “LabelsXXX” properties are now grouped into a new Texts subproperty of type TAxisLabels.
· Croatia country added to “Europe 28” map. (Renamed from “Europe 27”).
· Improved display of rotated multi-line Text shapes (Marks, Annotation tools, etc).
· More improvements to TeeHTML methods (to display tagged html text inside shapes).
· TSurfaceSeries, HideCells property now defaults to True instead of False.
· TTeeCanvas.PyramidTrunc parameters changed from Integer to Double.
· TCustomBarSeries AutoMarkPosition, replaced with Marks.AutoPosition property.
· TPieSeries AutoMarkPosition, replaced with Marks.AutoPosition property.
· TTeeFont.Gradient.Outline deprecated, replaced with TTeeFont.Outline.Gradient.
· TTeeCanvas Pen, Font and Brush are no longer inherited from VCL/FMX TCanvas.
· $IFDEF MONITOR_REPAINTS removed. Replaced with TRepaintMonitor tool.
· TTeeShadowEditor global InsertTeeShadowEditor function replaced wih class function TTeeShadowEditor.InsertForm.
· TTeeEmbossEditor unit and class removed as it was redundant. Use TTeeShadowEditor.
· The protected TChartSeries method “PrepareForGallery” no longer has the IsEnabled parameter.
· ColorToRGB is no longer internally used. All Colors are considered 4 bytes in RGBA format.
· Only a single TCanvas3D.TextOut overload method is now virtual.
· TAnnotationTool CalcTextSize protected virtual method deprecated. See new TTextShape.CalcBounds.
· TTextShape DrawRectRotated method renamed to simple “Draw” (several overloads)