ChartDirector 7.0 (PHP Edition)

Internationalization


Internally, ChartDirector uses Unicode to handle text. It fully supports international characters (that is, non-English and non-ASCII characters).

Externally, ChartDirector accepts Unicode characters as input using UTF8 encoding. UTF8 is an ASCII compatible standard for encoding Unicode characters.

What is Unicode and What is UTF8?

Whereas ASCII is a standard of representing common alphanumeric character as a number in the range 0 - 127, Unicode is a standard of representing characters from all known languages as a number. Because there are many known languages in the world, a lot of numbers are needed.

One common way of encoding Unicode is to use two bytes (16 bits) for a single Unicode character. However, this scheme is incompatible with ASCII.

On the other hand, the UTF8 standard employs a variable number of bytes to represent one Unicode character. If the character is in the range 0 - 191, it just employs one byte. Since an ASCII string consists of one byte character in the range 0 - 127, it is also a valid UTF8 string. Thus UTF8 is compatible to ASCII.

Writing Code in UTF8

If your code contains international characters (non-ASCII characters) that you would like to pass to ChartDirector, you should save your source code in UTF8 format.

As UTF8 is a very popular format, many text editors support saving in UTF8 format. For example, the Notepad from Windows 2000 supports saving file as UTF8.

If your code contains only ASCII characters, you can save it just as an ASCII file. It is because UTF8 is compatible with ASCII.

If your code does not contain international characters, but your data source (eg. data from a database) contains non-ASCII text strings, please convert them to UTF8 (if they are not already in UTF8) before passing them to ChartDirector.

ISO-8859-1 (Latin1) Western European Character Set

ChartDirector by default will assume text strings are of UTF8 format. However, if a string contains invalid UTF8 characters, ChartDirector will assume it is not UTF8, and will try to interpret it in ISO-8859-1 format.

ISO-8859-1 (also called Latin1 or Western European Character Set) is an extension of ASCII to include many Western European Characters in the range 128 - 255. This is the default encoding used in the English version of Windows.

Thus if you write some code that contains Latin1 characters, and you just save it as ASCII (or ANSI), it is quite probable ChartDirector can read it correctly. It is because a Latin1 string will probably contains invalid UTF8 characters, so ChartDirector will use the ISO-8859-1 interpretation for the string.

International Fonts

For ChartDirector to draw an international character in an image, it must use the proper fonts. By default, ChartDirector uses the Arial font. If the Arial font does not contain characters you want to display, you may need to specify an alternative font that contains the characters you need.

For example, if you want to display traditional Chinese characters, which are not supported in the Arial font, you will need to specify an alternative font, such as "mingliu.ttc".

You may change the default font by using BaseChart.setDefaultFonts or DrawArea.setDefaultFonts. ChartDirector API also allows changing the fonts in some particular text labels in the chart. For example, you may use the BaseChart.addTitle to specify the font for the chart title. Finally, you may use the ChartDirector Mark Up Language to specify the font used for any text.

Number and Date/Time Formats

In ChartDirector, the decimal point, thousand separator and the names used for months, weekdays, etc., are all configurable.

For example, instead of using "." as the decimal point, you may configure ChartDirector to use "," as the decimal point using BaseChart.setNumberFormat, or by using Parameter Substitution and Formatting.

Similarly, instead of using "Sun", "Mon", "Tue", ... etc, for the weekday names in date formatting, you may use BaseChart.setWeekDayNames to supply another set of names. The same applies to month names using BaseChart.setMonthNames, and to AM/PM representation using BaseChart.setAMPM.