Hanzi Helper version 1.0

http://hanzihelper.sourceforge.net
coljac@users.sourceforge.net

HanziHelper uses some functionality from the Dragon Character Training application for PalmOS. Please check out this project at http://dragon-char.sf.net. Thanks a lot to the developers of this project.

Intro

Hanzi Helper maintains a list of characters and lets you make practice sheets based on these characters or a subset of them. It's a way of remember what you should know and testing yourself, as well as practicing new characters you just learned. It lets you export the characters in a variety of formats, and includes a utility to convert chinese text files from one format to the other.

If you use this application, please consider letting the developer know what you thought of it. This way, you can be sure it'll be actively maintained.

Running

Hanzi Helper requires Java to run. Java is available for most operating systems including Windows, MacOS and Linux. You can get Java for free at http://java.com. A good way to test whether you already have java installed is to try and run the command "java -version". You need to have Java 1.4 or greater to run this application. (The Reminder app requires Java 5.)

If you downloaded hanziHelper.jar, and you have Java installed, you ought to be able to double-click on that file to run it. The first time it runs, it'll create a file called hanzihelper.properties that stores your settings. If this doesn't work, you'll need to tell your computer to run the command "javaw -jar hanziHelper.jar" from the command line or via a "shortcut".

Using the Application

This program does not include any Chinese text functionality of its own. To view Chinese characters, you will need to have a Chinese font installed, and to enter them into the application, you'll need a Chinese input method installed on your operating system (or cut-and-paste from somewhere else). The default font is "Arial Unicode MS" which is the universal font that is installed with Microsoft Office. You'll probably want to alter this. The screenshots were made using a font called "KaiTi_GB2312" in a file called "simkai.ttf" - this excellent font ships with Chinese WinXP but you can probably Google for it, or use the font of your choice. There is a font setup window available from the main "File" menu. Note that the font sizes set here are only used in the print section of the application (for now the fonts in the main display are of a fixed size).

From the main window, you can view the current list of characters. To add new characters, use File->Add from the menu or hit alt-A. You must enter Pinyin and Chinese, but the English is optional, as is the book information. Hitting enter from the English field or pressing the OK button will add your character to the list. By hitting enter, the form is reset so you can rapidly enter several characters in sequence. Pinyin entered with text tone numbers (e.g. zhong1wen2) are translated into unicode tone marks for display and printing. Similarly, Vs become ü/u: when rendered.

Entering multi-character words is ok. They will be split up on separate rows in the character view, but randomizing the list for printing will not separate the characters in a word.

When run for the first time, you'll want to create a "record" file. This is your list of characters. You can have multiple record files if you wish. To create a record file, use the "new" option from the file menu (file->new). The only files needed by the application are you character list, which is a UTF-8 encoded text file, and hanzihelper.properties, which records your settings such as paper size and fonts. You can edit these files externally if you want to.

The list can be filtered by book and chapter. Select "show filter" from the filter menu. The books available are presented as a drop-down list. Chapter information can be entered as a number, such as "3", or a range, such as "3-6". Once applied, the filter will function in the list view and for printing as well. Also, the characters can be highlighted from the main view. If any characters are highlighted, only highlighted characters will be sent to the printing part of the application. This allows you to pick a few characters or a range of characters to pring from your list. The same holds true when exporting the list.

Viewing a character's stroke order

Try right-clicking on a character. If the character is known to the application, a window will pop up showing the strokes in their correct order. Left clicking in this window will stop the character from drawing itself, and advance by one stroke. Right clicking will clear the window to start over again.

Printing

When you are ready to print practice sheets, select File->Print or hit ctrl-P in the main window. From here, select the style and text to print and you will be shown a preview. You can change the page settings, fonts and box sizes here. If you hit the "resize" button on the font dialog, it will iteratively figure out the biggest font size that will fit in the boxes.

The options have the following meanings:

Style 'one per row': A character will be printed in the left-most box only.
Style 'cram': A character will be printed in every second box, leaving room to copy it on the right.
Style 'rows': A character will be printed in every box, but only on every second row.
Style 'read': No gaps are left for copying.

The text options allow you choose whether the character itself or its pinyin or english translation is printed. Good for testing yourself.

The other options change the character of the boxes themselves or the fonts used for rendering text. Their use should be pretty straightforward.

Exporting

The application lets you export into a variety of formats. In most cases, you can export the whole character record or the highlighted subset. Some of these might cause unpredictable results, as many have not been used by any users apart from the developer. The supported formats are:

Supermemo: This is in a text format suitable for conversion to a Supermemo for Palm OS database.
Q & A: This is a text format with questions and answers on separate lines (e.g. Q: 我, A: I). This format is good for importing into a variety of flash-card programs, such as Supermemo for Windows.
Excel XML: This creates an XML file that can be opened by Microsoft Excel. It contains a bunch of information about the character. I personally make a big binder of these, and use them to "get to know" a character when it's new to me.
Stroke images: Creates .png image files that show how to write the characters. Select a diretory.
Dragon char: Creates a .pdb binary file for use by Dragon Character Training on the Palm.
Plecodict flashcards: For importing into the PlecoDict software for PalmOS.
Simple text list: Your characters as one big long string. Useful for searching.
VTrain: Creates a text file using the default = | delimiters that can be imported into VTrain on Windows.

Converting files

As a bonus, the application includes the functionality to convert Chinese text files to and from a variety of formats. File->Convert opens up a window that prompts you for an input and output file to convert. You need to know what format the input file is in for it to work properly (there's really no such thing as a "plain text" file these days, only text files with an associated encoding). If unsure, experiment and see. The supported formats are:

UTF-8: A common Unicode format used around the web, that is compatible with ordinary plain text files.
UTF-16: A Unicode text format.
GB2312: The standard non-unicode way of representing simplified Chinese text.
Big5: The standard non-unicode way of representing traditional Chinese text.

The converter will also let you convert simplified to traditional and back again. Make sure that when performing such a conversion the destination file is an appropriate format (simplified text won't be readable in a Big5 file, and tradition in GB2312). The "Write BOM" check box is used when UTF-8 text is written. If selected, the converter adds a so-called "byte order mark" to the start of the text file. Some applications require this mark to be able to interpret UTF-8 text properly.

"Reminders"

As of version 0.8, the application also comes with a separate little app for "reminding" you of the characters in your list as you work. It does this by putting a small window in the corner of your screen, and cycling through the characters in the list at the speed of your choice. (See the web site for a screenshot.) I decided it's too annoying to use, but please be my guest. :)

Reminder is packaged as a separate executable jar file. It needs to be in the same directory as hanziHelper.jar when run. Because of some features like always-on-top windows, Reminder needs Java 5 to run.

The little window will initialize in the corner of your screen, but can be dragged around. When Reminder has the focus, the following keyboard commands are enabled:

Esc: Quit
F1: Change the time interval between characters
F2: Toggle "always on top"
R: Toggle random order
Space: Start/stop the rotation
Right/left: Next/previous char
Home: First char

Reminder uses the last record file open in the main application. Optionally, you can specify a filename as a command line parameter (e.g. "java -jar reminder.jar myRecord.rec").

Thanks for using Hanzi Helper!

Still to Come

Resize the reminder app window
Import CSV
Searching
Adding extra data to the records, including example sentences
Changing the font sizes on the main view
Changing the column headers
Flashcards

Version History

Version 1.0 January 2 2007

Miscellaneous improvements and bug fixes.
Added text-file conversion mini-app
When a new record is added, it should display that record propertly now
Fixed bug with paper size not set to A4 in page setup
Fixed bug where deleting a record from the sorted display deletes the record at the old, unsorted position
Extra exporting options including Excel, Vtrain, PlecoDict flash cards
Made reminder panel draggable

Version 0.9 Apr 18 2005

Java 1.4 support added back in (2 builds).
Enhanced reminder app (auto-starts rotation, characters can be taken out of rotation)
Stroke order animations added.
Records now editable.
Data files choosable and createable.
Main display table sortable.

Version 0.8 Feb 10 2005

First version of the reminder functionality works.
Fixed filtering bug when list is randomized.
Added multi-character word handling logic.
They mostly come out at night. Mostly.

Version 0.7 Oct 8 2004

Added books and chapter data to the character record.
Added ability to print without leaving gaps to practice.
Temporary fix: Added secret configuration parameter to make the guide lines lighter: set guides.color=lightgray
Record numbers are determined by order in the file instead of explicitly

Version 0.6 (2004)

Can disable header info, grid lines.
Print dialog is resizable and fits itself to screen automatically.
Print controls altered for space.
Sample data packaged with application.
Numbers removed from record file.
Can clear the record database.

Version 0.5 (2004)

Initial release.

Building from the sources

If you want to compile and try the latest version from the sources or the CVS, here is what to do.

HanziHelper is a Java application. To build from the sources, you need Java and Ant (http://ant.apache.org) installed. Then just run "ant" in the HH directory. The result will be build/hanziHelper.jar, which is an executable jar file. Run with "java -jar hanziHelper.jar" or double-click on its icon.