Using International Characters in ChartDirector

ChartDirector supports all Unicode characters, which means it supports virtually all international characters, such as Chinese, Japanese, Greek, etc.

International Characters in Web Pages

Normally, a web server does not need any special configuration to support international HTML web pages. It is because the web server just passes the HTML code to the browser. It is the browser's responsibility to understand the international character encodings and display them.

For ChartDirector, the situation is different. ChartDirector charts are rendered on the server side. Therefore the web server and/or script interpreter may need to understand international character encodings and have the proper fonts installed.

International Characters in ASP/ASP.NET

Ensure ASP/ASP.NET Understands Your Character Encoding

By default, ASP/ASP.NET will interpret source code using the operating system's default code page. If you enter text strings directly in source code as literals, they should be entered in your operating system's default code page.

For example, if your operating system is using "Big5" as the default code page, your text strings should be entered in "Big5".

If you are not sure what is your operating system's default code page, you may find out using Control Panel/Regional Options.

If you need to use a code page that is not your operating system's default (e.g. you are using English Windows and wants to display Chinese using "Big5" encoding), you would need to:

Ensure the code page is installed in your system (by using Control Panel/Regional Options).
Use the @CodePage directive to tell ASP/ASP.NET to use the code page. For example:

<%@ language="vbscript" codepage="950" %>

In the above, 950 is the code page number for "Big5". The code page number for various chararter encodings is listed in Control Panel/Regional Options.

Note that the above is for text string literals in source code. If your text strings come from a database, ASP/ASP.NET always handle it as Unicode. There is no need to worry about code pages.

Use Proper Fonts

By default, ChartDirector uses the Arial and Arial Bold fonts. If these fonts do not contain the characters you want to use, you would need to use an alternative font.

For example, if you want to display traditional Chinese characters, you would need to use a font such as "mingliu.ttc" (for ASP) or "MingLiU" (for ASP.NET), assuming your operating system has installed that font.

Many ChartDirector API allows you to specify the font to use. For example, when you add a chart title using the BaseChart.addTitle method, the second argument allows you to specify the font to use. For labels on the axis, you can use the Axis.setLabelStyle method to specify the font. For example:

[In VB/VBScript]


		Call c.addTitle("Some Chinese Text", "mingliu.ttc", 15)

		Call c.xAxis().setLabelStyle("mingliu.ttc")

[In VB.NET]


		c.addTitle("Some Chinese Text", "MingLiU", 15)

		c.xAxis().setLabelStyle("MingLiU")

[In C#]


		c.addTitle("Some Chinese Text", "MingLiU", 15);

		c.xAxis().setLabelStyle("MingLiU");

You can also specify the default font to use for all text with the BaseChart.setDefaultFonts method. For example:

[In VB/VBScript]
Call c.setDefaultFonts("mingliu.ttc", "mingliu.ttc Bold")

[In VB.NET]
c.setDefaultFonts("MingLiU", "MingLiU Bold")

[In C#]
c.setDefaultFonts("MingLiU", "MingLiU Bold");

International Characters in JSP/Java

Ensure Your Java Compiler Understands Your Character Encoding

Java text strings are always in Unicode and support any international character. However, your JSP/Java source code may not be in Unicode. It may be in ASCII, UTF8, Big5 or some other encoding. So a Java compiler may need to convert your source code into Unicode during compilation.

If the Java compiler converts your source code using the incorrect encoding, the text strings may become corrupted. For example, if your source code is in Big5, but the Java compiler thinks it is in ISO-8859-1, the text strings may become corrupted. For this reason, it is important to ensure the Java compiler knows what is your encoding.

For JSP, the standard method is to include a pageEncoding directive in the first line. For example, if you are using UTF8, you may use the following line:

<%@page import="ChartDirector.*" pageEncoding="UTF8"%>

For .java files that are compiled by the Java compiler directly, there is no standard on how to specify the encoding to the compiler. It depends on the compiler brand. For SUN Java compiler, the method is by using the -encoding flag (see link below):

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javac.html

For other brands of Java compiler, lease refer to your Java compiler documentation on how to specify the encoding to the compiler.

Use Proper Fonts

By default, ChartDirector uses the Arial and Arial Bold fonts. If these fonts do not contain the characters you want to use, you would need to use an alternative font.

For example, if you would like to display Korean, you may need to use a font such as "Gulim" (assuming your Java VM has installed that font - see below on what does this mean).

Many ChartDirector API allows you to specify the font to use. For example, when you add a chart title using the BaseChart.addTitle method, the second argument allows you to specify the font to use. For labels on the axis, you can use the Axis.setLabelStyle method to specify the font. For example:


		c.addTitle("Some Korean Text", "Gulim", 15);

		c.xAxis().setLabelStyle("Gulim");

You can also specify the default font to use for all text with the BaseChart.setDefaultFonts method. For example:

c.setDefaultFonts("Gulim", "Gulim Bold");

Ensure the Font is Available to the Java VM

On Windows and Mac OS X, all OS fonts are automatically available to Java. On other OS such as Linux or other UNIX like systems, it may not be obvious what fonts are available to Java.

A common issue on Linux or UNIX like systems, especially on headless systems (systems without GUI), is that the Java is not configured to support fonts at all. (It is often assumed that Java always supports fonts. This is only true on Windows and Mac OS X, but not necessarily true on other OS.)

On Linux or UNIX like systems, to support fonts, many Java VM requires either X-Windows server is running, or headless mode is enabled (using "-Djava.awt.headless=true") See the following link if you are not familiar with headless mode:

http://java.sun.com/j2se/1.4.2/docs/guide/awt/AWTChanges.html#headless

To check the fonts that are available to your Java VM, you may use the following code. The JSP version lists out the Java font names on screen. The Standalone Java version lists out the Java font names to the console.

[In JSP]


		<%@ page language="java" %>

		<html><body>

		<%

		String[] f = java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment()

		    .getAvailableFontFamilyNames();

		for (int i = 0; i < f.length; ++i) {

		    %><%=f[i]%><br>

		<% } %>

		</body></html>

[In Standalone Java]


		String[] f = java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment()

		    .getAvailableFontFamilyNames();

		for (int i = 0; i < f.length; ++i)

		    System.out.println(f[i]);

If the font you want to use is not recognized by Java, you would need to install the font to your Java system. The steps depends on the Java brand and version. Please refer to your Java documentation on how to install fonts in Java. The followings is an example for SUN Java 1.4.2.

http://java.sun.com/j2se/1.4.2/docs/guide/intl/font.html

International Characters in PHP/Perl/Python/C++

Use UTF8 Encodings

ChartDirector assumes all text strings are in UTF8 encodings. If you are entering text string literals in source code, you may simply save your source code in UTF8 encoding. Most text editors designed for programming use can support saving source code in UTF8.

If your text strings are from somewhere else (such as from a database), and it is not in UTF8, you would need to convert it to UTF8 before passing them to ChartDirector. Many languages have built-in libraries for these conversion, and many coversion libraries are available on the Internet. For example:

PHP	Use the iconv function.
Perl	Use the Text::iconv package.
Python	Change to a unicode text string using the unicode built-in function, then use the encode method of the resulting string object to encode to UTF8.
C++ on Windows	Use the Win32 function MultiByteToWideChar to convert to wchar_t (unicode), then use WideCharToMultiByte to convert to UTF8.
C++ on Linux/UNIX	You may try to use the libiconv library, which is quite common in Linux or UNIX like systems.

Use Proper Fonts

By default, ChartDirector uses the Arial and Arial Bold fonts. If these fonts do not contain the characters you want to use, you would need to use an alternative font.

For example, if you want to display traditional Chinese characters, you would need to use a font such as "mingliu.ttc".

Please refer to the ChartDirector Documentation in the section "ChartDirector Reference / Data Types / Font Specification" for how to install extra fonts for use by ChartDirector.

Many ChartDirector API allows you to specify the font to use. For example, when you add a chart title using the BaseChart.addTitle method, the second argument allows you to specify the font to use. For labels on the axis, you may use the Axis.setLabelStyle method to specify the font. For example:

[In PHP]


		$c->addTitle("Some Chinese Text", "mingliu.ttc", 15);

		$c->xAxis->setLabelStyle("mingliu.ttc");

[In Perl]


		$c->addTitle("Some Chinese Text", "mingliu.ttc", 15);

		$c->xAxis()->setLabelStyle("mingliu.ttc");

[In Python]


		c.addTitle("Some Chinese Text", "mingliu.ttc", 15)

		c.xAxis().setLabelStyle("mingliu.ttc")

[In C++]


		c->addTitle("Some Chinese Text", "mingliu.ttc", 15);

		c->xAxis().setLabelStyle("mingliu.ttc");

You may also specify the default font to use for all text with the BaseChart.setDefaultFonts method. For example:

[In PHP]
$c->setDefaultFonts("mingliu.ttc", "mingliu.ttc Bold");

[In Perl]
$c->setDefaultFonts("mingliu.ttc", "mingliu.ttc Bold");

[In Python]
c.setDefaultFonts("mingliu.ttc", "mingliu.ttc Bold")

[In C++]
c->setDefaultFonts("mingliu.ttc", "mingliu.ttc Bold");