ChartDirector 6.0 Release Notes

This document describes the enhancements and bug fixes in ChartDirector 6.0 comparing to ChartDirector 5.1.1. For earlier versions of ChartDirector, please refer to the release notes archive.

New Features

PDF Output
ChartDirector can now output charts in PDF. This is in addition to the existing formats - SVG, PNG, JPG, GIF and BMP.
Upgrade to Meters and Guages
Meters and guages in ChartDirector have undergone a major upgrade. New features include:
Viewport Control
In ChartDirector, zooming and scrolling is represented as resizing and moving of the viewport in the chart viewer. The viewport control is a new control introduced in the currrent version of ChartDirector to let the user visualize and interactively manipulate the viewport.

In typical usage, the viewport control will display a small "overall chart" that shows the full data range (eg. 10 years of data), while the chart viewer will display a large chart that shows part of the data (eg. the last 6 months). The vieport control will include a rectangle on the overall chart to show the position of the viewport (the part displayed in the chart viewer). The region outside the rectangle can be dimmed out to highlight the viewport region. The user can drag the rectangle to move the viewport (equivalent to scrolling), and to drag the rectangle border to resize it (equivalent to zooming). The user can also drag a new rectangular region on the overall chart to be used as the new viewport, or click on a point on the overall chart to center the viewport at that point.

The viewport control is two dimensional, which means it supports zooming and scrolling in both x and y directions. The viewport control is available for both desktop and web applications.
Realtime Zooming and Scrolling
ChartDiector zooming and scrolling is based on the concept of the viewport. The viewport represents the visible part of the full data range. The viewport position and size are numbers between 0 to 1, representing their ratios to the full data range.

In realtime charts, new data are constantly added, and old data may get purged. This means the full data range is always changing. Furthermore, when new data comes in, the chart may need to be updated in various ways. For example, if the user wants to keep track of the latest data, the chart should scroll when new data come in so as to keep displaying the latest data. On the other hand, if the user wants to examine older data, the chart should remain stationary. However, if the old data were purged, the chart should automatically scroll to display newer data.

In previous versions of ChartDirector, the developer would need to write code to achieve the desired effect. ChartDirector now includes APIs to update the viewport in various ways when the full data range changes, so as to simplify the implementation of realtime zoomable and scrollable charts.
Touch and Mobile Device Support for Web Applications
Whereas ChartDirector charts can always be displayed on mobile browsers, there used to be limitations in the user interaction features.

On desktop computers, ChartDirector uses mouse move for track cursors, and mouse drag for scrolling and zooming. In mobile devices, by default the mobile browser will map touch events to mouse events. In this case, a finger swipe can be considered as both a mouse move and a mouse drag, so these two events become indistinguishable. The mobile browser usually responds to a finger swipe by scrolling the entire web page, and this interferes with ChartDirector's usage of these events.

Many mobile specific web sites are designed not to display images in their original size, but to resize them to fit the screen. It means the chart may be resized differently when the screen is rotated. Things draw on the chart on the browser side, such as track lines, may not fit the chart correctly when the chart change size on the fly. Even plain HTML image maps would not work on resized images.

The ChartDirector Javascript library has now been updated to handle the peculiarities of mobile devices. Instead of relying on touch events mapped as mouse events, it now has dedicated events for touch interactions. It can detect chart size change and generate resize events so that the track cursors can be updated. The image map can also be adjusted dynamically to fit the chart size.
SVG Support in WebChartViewer
As most browsers support SVG in <IMG> tags nowadays, the ChartDirector WebChartViewer has been updated to support streaming of SVG, including partial updates (AJAX updates) and realtime streaming. User interactions features, such as image maps (pop-up tooltips and clickable hot spots), programmable track cursors, and zooming and scrolling are also supported.
SVG Performance Improvements
In ChartDirector 6.0, the graphics engine has been vectorized. As a result, it can generate SVG output six times as fast as in previous versions.
SVG Options
ChartDirector 6.0 has introduced an API for setting the output options of SVG and PDF. The new configurable options for SVG are:
  • XML and DOCTYPE tags: By default, the SVG charts generated by ChartDirector are self-contained. They start with the <?xml> tag and then the <!DOCTYPE svg> tag as required by the standard. This allows the SVG to be opened directly by various applications.

    However, in some usage, the SVG chart may not be intended as a separate document. For example, it may be inserted into another SVG to become part of latter. In this case, the XML and/or DOCTYPE tags may not be necessary. There is now an option to turn off these tags.
  • width and height attributes: One of the benefit of SVG is that it is "scalable", so the SVG generated by ChartDirector does not include the overall width and height attributes. This allows the viewer or container to freely scale the SVG. For example, in web applications, if the SVG is included in a <DIV> of a certain size, the SVG would be scaled to that size.

    However, in some usage, it is nevertheless desirable to assign a size to the SVG. There is now an option to set the width and height to specified values.
WebChartViewer Downloading Support
With PDF support in ChartDirector 6.0, web pages can be designed to allow people to download the charts in PDF, as well as in other formats such as PNG and JPG. To support this type of usage, the WebChartViewer has been enhanced to include support for downloading. Apart from sending the PDF or other image formats from memory to the browser (without having to save the PDF as a file first), the content can be marked as an attachment with a filename in the HTTP header. The downloading support works with realtime update and partial update (AJAX update) too. For example, the user can download a snapshot of the latest realtime chart by pushing a button on the web page. For partial updates (AJAX updates), the download request can include partial update parameters, such as the viewport position or other custom attributes, so that the server can create the proper chart to download based on these parameters.
Transparency Support for MFC CChartViewer and Qt QChartViewer
ChartDirector for C++ includes two chart viewers for the MFC and the Qt framework. Like all standard MFC controls in Visual Studio, the MFC CChartViewer used to be not truly transparent. Charts requiring transparent effects are simply drawn with the same background color as the form background. This works if the form background is of plain color, and that there is nothing behind the chart except the form background. The same applies to the Qt QChartViewer.

The MFC CChartViewer and Qt QChartViewer now support alpha channel transparency (that is, each pixel can have a different level of transparency). This allows charts with transparency to integrate seamlessly with an image form background, and other controls behind the chart viewer be visible.
Rounded Corners for Bars and Box-Whisker Symbols
The bars and box-whisker symbols can now have rounded corners, with the radii at the four corners of the bars or boxes independently configurable.
Shading Effects for Box-Whisker Symbols
The Box-Whisker layer now supports the same shading effects available for bar layers, such as the glass effect, soft lighting effect, bar lighting effect and cylinder effect.
Arrow symbol
ChartDirector has added support for a new built-in arrow symbol, with configurable angle, head size, stem width and length. This shape, when used with data symbol offset (see "Data Symbol Offset" below), is useful for annotation or highlighting of other data points. For example, a scatter layer can use this symbol to point to extraordinary data points in other layers. In a financial chart, a scatter layer can use this symbol to point to trading sessions in which special signals have occured (eg. the "buy" and "sell" signals).
Data Symbol Offset
In chart types that support data symbols (including XY charts, polar charts and 3D scatter charts), the symbols by default are centered on the data points. However, in some cases, it may be useful to put the symbols beside the data point instead of directly on them. An example is using an arrow symbol to point to another data point, in which case the arrow should be moved beside the data point instead of over it. The amount of movement depends on the symbol size and is usually expressed in pixels. Moving a symbol by adjusting its data coordinates may not be accurate for this type of usage, as it is often difficult to translate data coordinates into pixel coordinates. For example, the axis scale may not be known, the axis may be non-linear (eg. logarithmic), or the translation formula may be complicated, especially for polar or 3D charts.

To address this requirement, ChartDirector now has special APIs to configure data symbol offsets in terms of pixel coordinates.
Thick Frame
ChartDirector charts can now have a thick frame with rounded corners. Apart from the frame color, the frame can also have an outer edge color and an inner edge color. The outer edge is the outside boundary of the frame. In some cases, the frame and the outside background may have similar colors, such as a silver frame on a white background. The outer edge color can help to make the frame stand out. Similarly, the inner edge can be used to help to separate the frame from the internal background (the background of the chart itself).
getXCoor and getYCoor for 3D charts
The getXCoor and getYCoor are methods to obtain the image pixel coordinates given the data coordinates. Previously, they are only available for xy charts and polar charts. They are now extended to support 3D charts. This facilitates drawing custom things on 3D charts, such as adding custom lines or text on walls, or custom text and shapes to annotate or highlight specific points.

Behaviour Changes

ChartDirector 6.0 is designed to be code compatible with previous versions of ChartDirector. This means existing code should continue to run. However, the charts produced may look different in the following ways.
Updated Substitution Fonts for Linux, FreeBSD and Solaris
To draw charts with text, ChartDirector needs fonts. However, for Linux, FreeBSD and Solaris, there is no standard location for fonts. In fact, these systems are often set up with no GUI or fonts. To ensure ChartDirector can work and can display the sample charts, the ChartDirector distribution includes some substitute fonts. If the fonts used in the sample code (which only uses Arial and Times New Roman fonts) are not found, ChartDirector will use the substitute fonts instead. The substitute fonts are only basic fonts and are not true type fonts, but are sufficient for the sample charts.

ChartDirector 6.0 supports PDF output, and some of the sample code includes buttons to download the charts as PDF. The PDF support should use true type fonts. For this reason, the substitute fonts are now changed to true type fonts.

(Note: If the true type fonts are not found, the PDF support will substitute with the 14 fonts which must be built into the PDF viewer as according to PDF specification. These fonts only support characters defined in the Windows ANSI encoding.)

If the web site relies on substitution fonts, that is, the charting code uses fonts that do not exist on the server, the charts may look different due to the font change. The new substitute fonts are metric compatible with Arial and Times New Roman, which means their glyph sizes are the same. For the old substitution fonts, they are only of similar size to Arial and Times New Roman, but not exactly the same. As a result, the text length with the new fonts can be slightly different from that of the old fonts.
Depreciation of the enableVectorOutput Method
In previous versions of ChartDirector, for true vector graphics output, enableVectorOutput should be called immediately after the chart object has been created. If this method is not called, the SVG output will produce a raster image in SVG, rather than a true vector graphics image.

In ChartDirector 6.0, enableVectorOutput is no longer necessary. ChartDirector will output true vector graphics image in SVG by default. The enableVectorOutput is still available just to maintain compatibility with existing code, but has no other purpose.

If for some reason, the charting code was intentionally designed to not call enableVectorOutput to create a raster image in SVG, the output will change to a vector graphics image in ChartDirector 6.0. To revert to a raster image in SVG, the "bitmap" option can be set using the new setOutputOption method.

Bug Fixes

The followings are the list of bugs that are fixed in ChartDirector 6.0.
  • SVG output is incorrect for certain font names
    Font names that contain embedded spaces and non-CSS-identifiers are included in SVG output incorrectly. This causes the SVG not to render in most browsers. This issue is now fixed.
  • SVG output is incorrect for bar charts with glass effect and very short bars
    The issue is caused by the bar being too short to contain the glass effect, resulting in invalid coordinates for SVG. This issue is now fixed.
  • SVG output is incorrect if a pie chart has multiple non-NoValue sectors but only one non-zero sector.
    In the above case, the SVG does not output the only non-zero sector, which should be a full circle. This issue is now fixed.
  • SVG output colors incorrectly for pie charts with thick sector borders. The fill color and the thick border color of the sectors may get mixed up. This issue is now fixed.
  • The ADX financial indicator in FinanceChart can appear as empty in ChartDirector for Perl
    This only occurs in certain operating systems and Perl versions, and is due to inconsistent floating point representation in Perl and C++. The ADX is partly computed in C++, and partly in Perl. They are combined without taking into consideration of the possible inconsistency, resulting in this issue. This issue is now fixed.
  • Image map in bubble chart with x axis and y axis swapped is incorrect
    The image map for the bubble chart is generated without considering the axes are swapped. This results in the image map not properly matching the bubble positions. This problem is now fixed.
  • Rounding errors in millisecond formatting for axis labels
    For charts using a true date/time axis (as opposed to a label based axis) but with very short duration, ChartDirector may need to generate ticks in millisecond precision. It does so by computing a suitable axis end point, then repeated add an increment to generate the ticks. Due to the inexact nature of floating point computation, this may eventually accumulate enough error to affect the labels. For example, instead of 12:34:45.800, it may become 12:34:46.799. This issue is now fixed.
  • When using Axis.setFormatCondition to set up the monthly alignment format condition, ChartDirector may incorrect consider the condition as true when all ticks are at the first hour of the first day of a month.
    To determine if a tick is at the start of a month, ChartDirector checks if the day of month is 1 and the hour of day is 0. However, it does not check for the minutes, seconds or milliseconds. So an axis scale within the first hour of the first day of a month can satisfy this condition. This may result in monthly formatting being applied to non-monthly ticks, creating incorrect axis labels. This issue is now fixed. ChartDirector now considers a tick to be at the start of a month if it is the first day or a month and the time is 00:00:00.000.
  • TextBox.setTruncate does not work in CDMLTable
    TextBox.setTruncate has no effect in CDMLTable. This issue is now fixed.
  • StepLineLayer.setAlignment does not work in ChartDirector for PHP
    StepLineLayer.setAlignment has no effect in ChartDirector for PHP. This issue is now fixed.
  • ChartDirector may crash if the DrawArea is used to rotate the chart image by -90 degrees and image width is larger than the image height
    ChartDirector uses specially optimized code for low level rotation in multiple of 90 degrees. Unluckily, there is a bug for the case of -90 degrees. This issue is now fixed.

Upgrade Considerations

Code Compatibility
ChartDirector 6.0 is designed to be code compatible with previous versions of ChartDirector. This means existing code should continue to run.
Behavioural Compatibility
Charts produced by ChartDirector 6.0 may be different from charts produced by earlier versions of ChartDirector in the following ways:
  • For the Linux, Solaris and FreeBSD editions of ChartDirector, the substitute fonts have been changed. For charts using fonts that do not exist in the machine (and therefore relying on substitute fonts), the text may look different and have a slightly different size or length.
  • In previous versions of ChartDirector, if enableVectorOutput is not called, the SVG output will create a raster image embedded in SVG, rather than a true vector graphics image. In ChartDirector 6.0, enableVectorOutput is no longer needed, as the SVG output will be true vector graphics by default. Code that intentionally output raster SVG by not calling enableVectorOutput will find that the SVG is changed to true vector graphics with ChartDirector 6.0.
License Compatibility
ChartDirector 5.x and later licenses can upgrade to ChartDirector 6.x free of charge. ChartDirector 6.x will automatically recognizes ChartDirector 5.x license keys.

If you are using an earlier ChartDirector license (on the date of purchase, the ChartDirector version was Ver 3.x or below), you would need to purchase one or more upgrades to use ChartDirector Ver 5.x. Please refer to Purchasing ChartDirector Upgrade and Subscription for details.
Upgrade Procedure
To upgrade ChartDirector, simply install the new version on top of the old version.

For ChartDirector for ASP/COM/VB, you may need to run the installer twice to upgrade ChartDirector. When the installer it first run, it will detect the existing ChartDirector and uninstall it. If the existing ChartDirector is being used by another process (such as the IIS web server), the installer may prompt you to reboot in order to complete uninstallation. After uninstallation is completed, please run the installer again to install ChartDirector.

ChartDirector for .NET are distributed as a zip file and does not require installation. Multiple versions of ChartDirector for .NET can coexist on the same computer, so you do need to remove the old version. In Visual Studio, you may drag multiple versions of the ChartDirector for .NET controls onto the Visual Studio toolbox (you may put different versions in different tabs to avoid mixing them up). If you prefer to replace the old version of ChartDirector for .NET with the new version, simply overwrite the old version with the new version.

For the PHP/Perl/Python editions of ChartDirector, please remember to update the files "phpchartdir.php", "" and "". These files are the language interfaces to ChartDirector. Their versions must match exactly with that of the ChartDirector DLL or shared object. Depending on how you installed your existing ChartDirector, these files might have be copied to the default module directory of your language interpreter, and/or to various scripting directories in your computer. Please ensure you update all of them.

If you are using PHP or mod_perl with Apache, you may need to restart the Apache server for the upgraded ChartDirector to take effect.