This document describes the enhancements and changes in ChartDirector 7.0 comparing to ChartDirector 6.4. For earlier versions of ChartDirector, please refer to the release notes archive.

• New Features
• Behaviour Changes
• Upgrade Considerations

---

---

TreeMap chart is a new chart type in ChartDirector. A treemap chart is similar to a pie chart. Whereas a pie chart divides a circle into slices, a treemap chart divides a rectangle into multiple rectangles. The child rectangles can be divided into yet more rectangles. So a treemap chart can be used to visualize a tree like data structure with multiple levels of divisions. Discrete Heat Map is a new layer type for XYChart. It consists of square or rectangular cells colored based on their data values. Like a contour layer, a discrete heat map layer contains a color axis that maps data values to colors. A circular bar meter is like a linear bar meter, but with the bar bends in a circular direction. By using an angular gradient, the colors along the bar can vary depending on the meter value. The center of the meter can be used to display the meter value in text. The PDF output feature of ChartDirector has been extended to allow generating a PDF with multiple pages. Each page can contain multiple charts as well as free form text, tables, drawings and images. That means ChartDirector can now generate complete PDF reports. With the new DataAccelerator object, ChartDirector can plot charts with a billion data points, with smooth zoom, scroll and track cursor support, and updating at thousands of data points per second in real time. ChartDirector GUI controls, such as the chart viewer controls and viewport controls in C++ and .NET, will now automatically detect if the application is high DPI aware, and will resize render the charts at the detected DPI. There are also APIs to force the charts to render at a given DPI. In responsive web design, the web page elements can change size and layout depending on whether it is viewed by a desktop or mobile device. This is typically achieved by using cascaded style sheets (CSS). However, browsers typically cannot resize HTML image maps. If the chart image is resized, it will no longer match the image map, and the hot spots and tooltips may not work correctly.

In previous versions of ChartDirector, Javascript code can be written to register the chart with the ChartDirector Javascript Chart Viewer. The image map will then be resize on the fly to fit the image. On ChartDirector 7.0, this is automatic and no code is required. ChartDirector GUI controls now support tooltips formatting with CDML (ChartDirector Mark Up Language). This allows rich formatting of the tooltips, semi-transparent tooltip container, and allows the tooltips to contain icons and images. CDML adds support for containers with rounded corners and configurable margins, and polyshape symbols. (See PolyShape section below.) ChartDirector can now draw labels along the contours in a contour chart or heat map. This allows contour values to be displayed directly on the contours, instead of having to lookup their values based on the underlying colors. ChartDirector can now computes the cross section between two points on a contour chart or heat map. The cross section is represented as the z values along a straight connecting the two points. ChartDirector now supports continuously varying tooltips on a contour chart or heat map to display the (x, y, z) values as the mouse moves. ChartDirector 7.0 introduces a new API ContourLayer.getZAtPixel for obtaining the z value at any (x, y) position on a contour chart or heat map. In a surface chart, the surface is defined with (x, y, z) coordinates. By default, the z coordinate also determines the surface color. ChartDirector now supports using an extra coordinate w for the surface color. For example, the w coordinate can represent the temperature on the surface. In this case, the color will be based on the temperature instead of the z coordinate. The projection of a surface chart on the XY plane is a contour chart. ChartDirector can now include the projection on the XY wall of the surface chart. ChartDirector now supports including custom line segments and rectangular zones on the surface or a surface chart. ChartDirector now supports drawing a custom image on the surface of a surface chart, The image can be semi-transparent so as not to block the underlying surface. The image can be generated on the fly by using another chart or the DrawArea object. This feature is useful for adding custom annotations on the chart. An example is to use a polar chart as the image to include semi-transparent circular zones on the chart. ChartDirector now supports continuously varying tooltips on a surface chart to display the (x, y, z, w) values as the mouse moves. ChartDirector 7.0 introduces a new API SurfaceChart.getValuesAtPixel for obtaining the (x, y, z, w) values any pixel position on a surfaced chart. The PDF and SVG formats are basically designed for 2D graphics. In previous versions of ChartDirector, for 3D surface charts, ChartDirector needs to use varous ways to emulate 3D graphics with the 2D graphics capability of SVG/PDF. The resulting SVG/PDF can become very large and complex that many SVG/PDF viewers and browsers have difficulty displaying them.

ChartDirector 7.0 now uses hybrid rendering methods. The 3D parts are pre-rendered by ChartDirector while the text, lines and 2D parts of the chart are rendered using PDF/SVG graphics. The resulting PDF/SVG is much smaller and can be viewed by common PDF/SVG viewers and browsers. In previous versions of ChartDirector, for zooming support, the x and y directions zoom independently. It is common to find charts that only zoom in the x direction. For charts that zoom in both directions, the user can drag a rectangle to zoom into such that the x and y directions zoom by different factors.

ChartDirector 7.0 introduces a "keep aspect ratio" mode to keep the aspect ratio unchanged during zooming. This is useful for contour charts related to geographic maps of which the x and y directions must zoom by the same factor. ChartDirector now supports angular gradient color, which is a gradient which changes color depending on the bearing of the pixel relative to a center point. In previous versions of ChartDirector, color scales are used to define the colors based on the z values for contour and surface charts. ChartDirector 7.0 now extends this to support coloring objects based on the x and y values in XY charts. ChartDirector can now export the color scale of a color axis. The color scale can be used in other charts to ensure they have consistent colors. For example, if a cross section of a contour chart is to be visualized as an area chart, the color scale of the contour chart can be used as the y-scale color of the area chart to ensure consistent colors. ChartDirector 7.0 introduces a new Axis.syncScale API to synchronize the axis scale only. In contrast, the existing Axis.syncAxis API sychronizes both the axis scale and geometry.

Axis.syncAxis is designed to synchronize the y-axes or x-axes of the an XY chart, To ensure the scales are perfectly aligned, the axes are assumed to have the same length. If the source axis is configured with axis margins, the axis sychronized with it will automatically have the same margins.

Axis.syncAxis is not suitable for axes with different lengths, such as axes from different charts. Examples include sychronizing an axis of a large chart with an axis for a small thumbnail chart, or synchorinzing a color axis with a y-axis. For these cases, Axis.syncScale can be used instead. In previous versions of ChartDirector, for a scatter symbol, the size parameter refers to both width and height. Symbols with different width and height requires two arrays to specify the widths and heights individually for each symbol.

ChartDirector 7.0 introdues a new API xySize that can encode different width and height into a single size parameter. For example, it is now possible to specify an ellipse symbol by using a "circle" symbol with different width and height. A legend item in ChartDirector's legend box typically contains an icon, followed by text that describes what the icon means. ChartDirector 7.0 adds support for a pure text item. The text can be CDML (ChartDirector Mark Up Language) formatted. It can be used to add headings or empty lines to separate the legend items into sections, or to add legend items with icons in non-standard positions. ChartDirector allows using custom shapes for symbols. In previous versions of ChartDirector, a custom shape can be any polygon or ellipse. ChartDirector 7.0 adds support of compound shapes filled using the even-odd rule. For example, it is now possible to make a hexagon symbol with a transparent circular hole inside by combining a hexagon and a circle inside. The even-odd rule means the region inside the circle is not filled at all, so it becomes a transparent hole. In previous versions of ChartDirector for C++, Perl, Python, PHP and ASP/COM/VB, fonts are specified using their file names. ChartDirector 7.0 also allows fonts installed in the Windows or macOS operating system to be specified with their family names, followed by optional "Bold" and/or "Italic" keywords. Font file names remain supported as they are useful for private fonts or fonts embedded as resources in the executable. In previous versions of ChartDirector for C++, Perl, Python, PHP and ASP/COM/VB, only true type fonts (including open type fonts with true type outlines) are supported. ChartDirector 7.0 adds support for open type fonts with postscript outlines too. In previous versions of ChartDirector, the right position of the viewport has to be computed as the sum of viewport left and viewport width. Similarly, the bottom position has to be computed as the sum of viewport top and viewport height. ChartDirector 7.0 adds two methods to get the viewport right/bottom directly.

---

---

ChartDirector 7.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. ChartDirector 7.0 desktop GUI controls has built-in high DPI support enabled by default. If your existing application is high DPI aware, when running on a high DPI enabled computer, the charts may become sharper or larger depending on the GUI framework.

Modern operating systems can increase the size of its user interface by a configurable scale factor. This is often done because modern displays can have very high pixel density, making the standard user interface size visually too small.

Many applications are not aware of the high DPI scale factor and only draw their GUI in the standard size. The operating system will resize the GUI of these applications automatically. This makes the GUI larger, but not as sharp compared to applications that draw in the scale up size natively.

If an application is high DPI aware, it should obtain the high DPI scale factor at runtime and draw its GUI in the scale up size. The application must notify the operating system that it is high DPI aware (by caliing certain API or setting some flags) to avoid the operating system from resizing its GUI.

ChartDirector desktop controls, including controls for MFC, Qt, Windows Forms and WPF, will detect if the application is high DPI aware. If it is high DPI aware, these controls will draw the charts with the high DPI scale factor applied. The developer does not need to write extra code to resize the chart in high DPI mode.

Some GUI frameworks (Qt and WPF) will automatically resize non-high DPI images in high DPI aware mode. This means even with previous versions of ChartDirector, the charts are automatically resized. With ChartDirector 7.0, the charts will become sharper as they are natively high DPI.

Some GUI frameworks (MFC, and Windows Forms controls that is not configured to "StretchImage") will not automatically resize non-high DPI images. This means with older versions of ChartDirector, the charts may look smaller in high DPI aware mode. In ChartDirector 7.0, the charts will scale up to the correct size.

If your code already resizes the charts for high DPI support, the charts may become double resized when using ChartDirector 7.0 desktop controls. You may need to modify the code in one of the following ways:

• Call the setDPI method of the control to set the DPI to 96. The control will then draw the chart in its standard size without the scale factor.
• Or, modify your code so that it does not resize the charts for high DPI.

In responsive web design, the web page elements can change size and layout depending on whether it is viewed by a desktop or mobile device. This is typically achieved by using cascaded style sheets (CSS). In previous versions of ChartDirector for .NET, the chart image created will have a style attribute that specifies its size. As per HTML/CSS specification, the style attribute by default will override CSS. That means the chart image cannot be resized by CSS, unless the "!important" keyword is used in CSS to override the style attribute.

In ChartDirector 7.0, the chart image size will be specified using an alternative method that is overridable by CSS. If the CSS in your web page is applicable to the chart, it may have no effect in previous versions of ChartDirector, but will work in ChartDirector 7.0. Scalable Vector Graphics (SVG) can be rendered at any size by the viewing software (eg. the browser). In previous versions of ChartDirector, the SVG output does not have a definite size. The browser will render it as large as possible to fill its container. For example, if the SVG is inside a DIV tag, it will fill the DIV tag. This means the container determines the chart display size. This is different from raster images (PNG, JPG, GIF), which has a pixel size. If you replace a PNG with SVG, the display size of the chart may change from pixel size to container size.

SVG is useful in responsive web design as it maintains crispness regardless of resizing. ChartDirector 7.0 now includes a default size in SVG. This allows a SVG chart to replace a PNG, JPG or GIF chart without affecting web page layout. The SVG size can be overridden with CSS just like any other image. ChartDirector 7.0 uses a new text rendering engine with more accurate text positioning. The text length and text shape may change slightly. If an image map is used, it should be included in the web page that contains the image. The delayed image map feature will generate a web page without the image map, and load the image map using Javascript in the background. The web page can appear faster while user interaction features (eg. tooltips and hot spots) will be delayed.

Delayed image map was designed at a time when people were using 9600 bps dial-up modem to access the web and a typical web page is only a few KB in size. We have removed delayed image from our sample code and documentation for a long time. In ChartDirector 7.0, existing code that uses delayed image map will continue to run, but the image map will act like a normal image map and will not be delayed.

---

---

ChartDirector 7.0 is designed to be code compatible with previous versions of ChartDirector. This means existing code should continue to run. Charts produced by ChartDirector 7.0 may look different from charts produced by previous versions of ChartDirector in the following ways:

• For desktop applications, ChartDirector controls now support high DPI awareness. If your application is high DPI aware, the charts may become sharper or larger in a high DPI enabled system.
• For web applications using ChartDirector for .NET, the charts can now respond to CSS size settings without requiring the "!important" keyword. That means CSS size settings applicable to the chart may now work.
• In previous versions of ChartDirector, the SVG output does not have a default size. Browsers typically will render the SVG based on the size of its container. SVG produced by ChartDirector 7.0 now has a default size compatible with that of PNG, JPG or GIF output. Browsers will render the SVG at that size unless another size is specified (eg. using CSS).
• The text rendered in ChartDirector 7.0 may have slight different length and shape compared to previous versions of ChartDirector
• In previous versions of ChartDirector for C++ on macOS, the "install name" of the ChartDirector dynamic library is the filename itself. That means at runtime, the application will search for the library in the "current directory". The install name can be modified with the "install_name_tool" in macOS.
  
  In ChartDirector 7.0, the install name has been modified to "@rpath/libchartdir.7.dylib". That means the application will search for the library using its runtime search path. This makes it easier to put the library inside an application bundle.
  
  If your build system does not use the "install_name_tool" to specify the install name, the application will now use its runtime search path instead of the current directory to locate the library. You must ensure the library is copied to a folder in the runtime search path, or configure the application's runtime search path to include the current directory.

ChartDirector 6.x licenses can upgrade to ChartDirector 7.x free of charge. ChartDirector 7.x will accept 6.x license keys.

If your license was issued before ChartDirector 6.x, you would need to purchase one or more license upgrades to use ChartDirector 7.x. Please refer to Purchasing ChartDirector Upgrade and Subscription for details. With the exception of ChartDirector for ASP/COM/VB, all ChartDirector editions are distributed as zip or tar.gz files. Different versions of ChartDirector can coexist by extracting them to different folders. They can be applied to different projects or web server instances.

For ChartDirector for ASP/COM/VB, because COM technology requires registration with the operating system, only one version of ChartDirector for ASP/COM/VB can be installed per operating system instance. The installer for ChartDirector for ASP/COM/VB will detect if there is another version installed and prompt you to uninstall it first. To upgrade to a new version of ChartDirector, simply reapply the steps in the Installation section of the ChartDirector documentation with the new version of ChartDirector, overwriting the older version. The followings are brief instructions for various editions of ChartDirector. You can upgrade an existing C++ project to use a new version of ChartDirector as follows:

• Replace the old ChartDirector header files with the new header files.
• Change your project to link to the new ChartDirector library.
• For MFC projects using the CChartViewer control, replace the old CChartViewer.cpp and CChartViewer.h with the new version.
• For Qt projects using the QChartViewer control, replace the old QChartViewer.cpp and QChartViewer.h with the new version.

For ChartDirector for .NET, replace the old ChartDirector assembly netchartdir.dll with the new version. If the project references ChartDirector with NuGet, update the NuGet reference to point to the new version. You may install multiple versions of ChartDirector in the Visual Studio toolbox by creating a new tab for the new version, and install the controls from the new assembly in that tab. For ChartDirector for ASP/COM/VB, running the installer will cause the new version to register itself with the operating system. All existing code will then use the new version. For ChartDirector for Java, replace the ChartDirector jar file with the new version. For ChartDirector for PHP, Perl and Python, replace the old ChartDirector DLLs or shared objects with the new version, and also update the script files "phpchartdir.php", "perlchartdir.pm" and "pychartdir.py". Depending on how you installed your existing ChartDirector, the script files may have been copied to the default module directory of your language interpreter, and/or to various script directories in your computer. Please ensure you update all of them.

If you are using PHP on a web server, depending on how your system is configured, you may need to restart the web server process or restart the PHP FastCGI Process Manager for any change to take effect.