Typist v3.1 (Java) User's Guide

Table Of Contents

This document contains the following sections:

  1. Introduction
  2. Using Online Help
  3. The Control Window
  4. The Tutorial Window
  5. The Exercise Window
  6. The Keyboard Window
  7. The Statistics Window
  8. Building The Program
  9. Running The Program
  10. Adding New Lessons
  11. Adding New Keyboards
  12. Localization
  13. Java Runtime Notes
  14. Bugs and Omissions
  15. General Information
  16. GNU GPL


Typist is a program to provide you with instruction and practice in using a computer keyboard.

If you can not touch type, Typist contains all the tutorials and practice text you will need in order to master this skill. And if you can already touch type, then you can use the program to sharpen your keyboard skills, and improve your typing speed and efficiency.

Typist contains lessons and practice text for the standard QWERTY keyboard, the Dvorak (simplified) keyboard, and the PC numeric keypad. On each typing exercise, it measures your speed, and can provide you with information about which keys or fingers need additional practice.

Using Online Help

You can use the Help Window to display online help while running Typist. At the top of the window you can select from the topics that the help window offers. Selecting a topic brings the help information for that area into the window's text display.

Select File->Close Window on the menu bar for this window to close it.

The file Typist31.html contains an HTML version of the online help text.

The Control Window

This is the main window for Typist. The menu bar allows you to activate the other windows that Typist can display -- the Tutorial Window, the Exercise Window, the Keyboard Window, the Statistics Window, and the online Help Window. Additionally, it also offers a Help pulldown item: Use Help->About to get information about Typist and its licensing, and Help->On Typist to obtain the online Help Window.

Typist offers a number of alternative and complementary lesson series. The Control Window allows you to select which lesson series is currently active, and within a lesson series allows you to select a particular lesson.

Beneath the window's menu bar is a toolbar. Using the toolbar, you can select the lesson series that is active, and move forwards and backwards through the lessons in that series using the Prev and Next buttons.

The central area of the Control Window is the lessons list. This shows each lesson that the currently active series contains. To run any lesson individually, select it from this list. Lessons can be of three basic types:

Tutorials are displayed in the Tutorial Window. Drills and Speed Tests are displayed in the Exercise Window.

The Tutorial Window

This window shows the text of the most recently selected Tutorial. Use the scroll bars to read the text. The window may be left up as a reminder of the lesson if you wish.

This window also maintains a list of several past tutorials you have viewed. Use the History menu on the menu bar to review them.

The Exercise Window

This is the window that you type into for practice, and displays both Drills and Speed Tests.

In a Drill, the window contains two text areas. The upper text area shows the target text that you should type, with the expected next character highlighted. The lower text area shows what you have typed at the keyboard so far, with error characters picked out as '*'s, and end of line errors as '<'s. In a Drill, backspace characters are ignored; backspace will not delete the last typed character.

In a Speed Test, the window has only one text area. Again, the expected next character is highlighted. For a Speed Test, you need to overtype the characters in this text area. If you enter an incorrect character, Typist puts a '*' at the location of the error. You can use backspace to back up and correct typing errors in Speed Tests.

For both types of exercise, Typist times each keystroke, and at the end of the exercise, it displays information about how many errors you made when typing the exercise, and your typing speed and adjusted speed in Words Per Minute (WPM). Your raw typing speed is calculated as the number of keystrokes you made, divided by five (the notional average word is taken as being five characters), divided again by the time in minutes taken to complete the exercise. The adjusted WPM is calculated in the same way, except that one word is taken away for each single character typing error you made.

When timing keystrokes, Typist does not count the first character of an exercise. Also, if you pause for a few seconds between characters, it will not count the next character after the pause as part of the exercise. It does this to try to maintain sensible keystroke timing information where you might take breaks in mid-exercise.

By default, Typist will try to behave like a word processor. It treats a space character as correctly typed at the end of a line, and will condense multiple spaces are condensed down into a single space. If you hit Return at the end of a line, the cursor moves forward to the next significant character to be typed, skipping over blank lines and paragraph indentation. Typist will not insist that you type the hyphen at the end of lines that end in one, but will wrap for you. To switch off any or all of these word processing features, use the Options menu on the menu bar.

To restart an exercise from the beginning, use the Restart button. To pause an exercise, use the Stop button.

If you want it to, the Exercise Window can sound a audible beep on the system whenever you make a keying error. Use the Options menu on the menu bar to enable this. X-Windows users may find the following command useful; it shortens the beep to a small 'pip' on the X server, and can be useful where the normal terminal 'bell' is too annoying to use:

    xset b 100 1000 50

Microsoft Windows users have their own ways of setting up sound warnings.

Like the Tutorial Window, the Exercise Window maintains a list of several past exercises you have worked on. Use the History menu on the menu bar to re-run these exercises.

The Keyboard Window

The Keyboard Window shows a picture of your keyboard. When Typist is expecting you to type a key in an exercise, it indicates the key that it is waiting for in this window. It also indicates the finger that you should use to strike that key, and which Shift key you should press, if any.

The Keyboard Window can also show you your successful keystrokes, and any mistakes that you may make in an exercise. Use the Options menu on the menu bar to select the information you want the Keyboard Window to show you.

Note that this window only indicates fingering for the main keyboard. It does not show you which finger you should use for the numeric keypad. Also, the numeric keypad is not controlled by the keyboard layout you are using; Typist assumes it is the same for every keyboard type.

Although it is a useful learning aid, especially in the early stages of learning the keyboard, you should aim to practice without the Keyboard Window as soon as you can.

The Statistics Window

Each time you strike a key in an exercise, Typist notes the key that you struck, the one it was expecting you to strike, and the time it took you between the last key you struck and this one.

The Statistics Window displays a complete analysis of all of this timing information collected on exercises. Typist maintains keystroke statistics for individual keys, for each finger, and globally. You can use the View pulldown menu to decide which set of statistics you want to see in the window.

The Statistics Window shows each statistic as a pair of gauges, giving the percent accuracy and speed for the finger or key. If the accuracy or speed drop below certain threshold levels, the gauges will change color to orange or red, to indicate that these are areas in which you might consider some additional practice.

Press the Load button to bring the window up to date with current keystroke statistics. The window is automatically refreshed if you change which set of statistics is on view, when the window is displayed, and at the end of each typing exercise you complete. You can also use the autorefesh function to have the statistics refresh automatically. To control this feature, use the Options->Automatic Refresh Every Second pulldown menu item.

You can use the Reset button to set the complete collection of measurements back to their initial condition. To display adjusted WPM statistics, use the Options->Display Adjusted WPM pulldown menu item.

The statistics this window shows are the normal keystroke statistics, broken down by key and by finger. Note that Typist calculates WPM rates using timing information that is maintained regardless of whether you struck the right key or the wrong one -- this means that where accuracy is poor, WPM rates shown for individual keys and fingers can become misleading.

Building The Program

Typist (Java version) consists of a flat directory of Java source files, s handful of subdirectories containing data files (Java .properties files), and a single Makefile. If you have make on your system, then merely invoking the command should be sufficient to build the complete set of class files and the jar file that contains them and the properties files to form the complete application -- the Makefile does not contain any complicated or GNU-make dependent constructs.

If you do not have make available, try 'javac [-O] *.java'. The Java compiler is usually smart enough to automatically compile any source files for a needed class file, so building may not be too much of a problem. To create the jar file without make, you will need to create a temporary directory, copy all *.class and *.properties files from the top-level and all subdirectories of Typist into it, then try 'jar -cf JtNNcla.jar *.class *.properties', where NN is the release number of Typist that you are using, without the '.', (for example, '31' if using Typist 3.1).

You do not need to install the program in order to run it. If you do choose to install the program, however, as an application, the command to do this is 'make install_application'. Installing the program as an applet depends on the Web server you are using, so the Makefile can not automate it for you. Typically, all you should need to do is to copy the jar file and the HTML files into a subdirectory of your Web server's main documents directory (for example, htdocs on Apache). Please consult your Web server's documentation if you are unsure of how to do this.

Most classes contain a main() method that tests the class in some way, the obvious exception being the Typist class that contains the 'real' main() method, and also the applet entry point for the program. The main() method in the HelpHTML class prints out the online help text as a single HTML User Guide document.

Running The Program

The single main runnable class file in Typist is:

This, and all the other classes, will normally be wrapped up inside a '.jar' file. To run Typist as an application, use a command something like 'CLASSPATH=./JtNNcla.jar java Typist', where 'NN' is the version of Typist you are using, for example, '31'. This will run the Typist class. You can add -k keyboard_type to specify the keyboard type. Use -h for a full list of arguments.

If you have installed the program using 'make install_application', you can run the program using the simple command 'jtypist', found in the directory /usr/local/bin.

Typist can translate between keyboard types for you as it runs. To do this you need to add the option -r real_keyboard_type. This can be confusing, so here is an example. Say you are using a US keyboard, and want to try out Typist in Dvorak mode; you can do this by adding the options '-k Dvorak -r US'. This tells Typist to map each keystroke from your US keyboard into its Dvorak equivalent. You should note, however, that Typist does not translate menu accelerator keys; in all cases, these need to be entered using the keys shown on the actual system keyboard.

If you have localized messages and help text, Typist will use them, obtaining the locale from the Java runtime's default locale setting. See Localization for details on how to specify a locale.

To run Typist as an applet, again use the Typist class. For an applet, you can set the keyboard type using the applet parameter kbtype -- see JtNNapp.html for an example of HTML applet tags to activate the program. Because Typist makes heavy use of frames and menu bars, the applet form is nothing more than a single pushbutton that starts the main program in a separate frame outside the browser.

Applet parameters include:

To run Typist as an applet, make sure you use the 'ARCHIVE=' attribute to the <APPLET> HTML tag. This is because Typist uses a lot of properties files.

The advantage of properties files is that they are easily changed without the the need for a Java compiler, meaning you can change the text of a lesson, the online help, a message, or a keyboard layout by simply editing the right properties file. The disadvantage is that in for applets, a browser will usually look for properties files on the local system, rather than get them from the HTTP server.

The result of this action in the browser is that the properties file is usually not found, and the applet fails. To avoid this, Typist is packaged into a jar archive, which is sent to the browser when the applet is started. The browser will then look in this archive for class and properties files, before going back to the HTTP server that it received the jar archive from.

Note that it is not necessary to use a Web server in order to run Typist as an applet. You can, for example, simply point a JVM-capable browser at the JtNNapp.html file using a 'file:/' URL.

Adding New Lessons

Typist allows you to add new lessons to the ones that it offers. To do this, you need to create a LessonSeries properties file. For example, if you want to create a lesson series Foo, the class file containing your lesson should be named LessonSeriesFoo.properties. You can then use the -s or -series flags, or the series applet parameter, to specify the series that you want Typist to offer. This is a comma-separated list, for example, 'T,R,Q,Foo'.

The LessonSeriesFoo.properties file is a standard Java properties file, and consists of entries of the form 'keyword=value', with comments in the file prefixed with a '#' character. For a lesson series, the following entries must be present:

The identifier for the series, 'Foo' in this case.
The series description displayed in the Control Window when you select this lesson series.
A space-separated list of all the lessons in this series. Typist offers the lessons in this order.

So for LessonSeriesFoo.properties, we might have:

    description=Example Lesson Series
    lesson_index=foo1 foo2

Each lesson in the series should have following definitions:

The name of the lesson as you want it to appear in the list of lessons for this series.
A single line of instruction that can be used to prefix an exercise. This definition is optional for an exercise, and ignored if present for a tutorial.
The text of the lesson; either the tutorial, or the practice text for typing if this is an exercise lesson. Use \n to indicate newlines, and \ at the end of lines to indicate that the line continues.

For example, the definition of lesson 'foo1' might be:

    foo1.title=Lesson foo1: Example tutorial
    foo1.text=Line one of tutorial text\n\
    Line two of tutorial text\n

Once you have created the LessonSeriesFoo.properties file, there is no need to to compile it - you may use it immediately. If you are running Typist as an application, you just need to make sure that your new file is somewhere on your CLASSPATH, and that the name does not clash with an existing lesson series properties file. Or if you are running Typist as an applet, you need to add your new properties file to the applet jar file.

Probably the easiest way to create a new lesson series is to begin with one of the existing ones, copy that to a new file, and edit that file to create the new lesson series.

Previous versions of Typist required you to create the new lesson series in a Java source file. This is no longer necessary, though Typist will still read this older format lesson series.

Adding New Keyboards

Typist also allows you to extend its range of keyboard maps. To do this, you need to create a new KBLayout properties file. You can then use the -k or -kb flags, or the kbtype applet parameter, to tell the program to use the new keyboard map. The new map can also be used with the -r or -realkb flags, or the realkbtype applet parameter, too.

For each keyboard character, the new layout needs to specify the finger that is assigned to the key, whether the key is shifted, the group the character is in for statistical purposes, and the keycode of the key that creates the character. Typist will create the Keyboard Window by using the following table to turn keycodes into key positions in the window:

    Row 1: 41, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13,   14
    Row 2:  15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27,  43
    Row 3:  58,  30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,     28
    Row 4:   42,  44, 45, 46, 47, 48, 49, 50, 51, 52, 53,        54
    Row 5:  29,    56,             57,              100,         97
Like lesson series, the keyboard map file is a standard Java properties file. For a keyboard map, the following entries may be present:

This is the identifier for this keyboard layout, as it appears in the Statistics Window and the Keyboard Window.
This entry is optional; if present it contains a space-separated list of other keyboard layouts that Typist should process before it processes the entries in this one. Includes is the way that Typist allows a keyboard map to extend or modify an existing map, so the new map need contain only the differences.
This is a space-separated list of all the entries in this layout.

Each keyboard map entry consists of a single string, with either one field, or five space-separated fields. The fields in an entry are

If only the first field is present in an entry, Typist will delete any entries for that character from the keyboard map. Otherwise it replaces any existing entry in the map for that character with the new entry; if there is no existing entry, it appends the entry to the map as a new entry.

A simple example keyboard map is the one used for the Microsoft ergonomic keyboard. This map modifies the standard US layout so that the '6' key is operated by the left hand instead of the right:

    id=Microsoft US
    entry_index=entry_0 entry_1
    entry_0=  ^   KC_7   SHIFTED    LH_INDEX   FIGURES
    entry_1=  6   KC_7   UNSHIFTED  LH_INDEX   NUMERIC

This file would be stored as KBLayoutMicrosoft.properties, and placed somewhere on your CLASSPATH where Typist is an application, or into the applet jar file where Typist is running as an applet.

Typist can also use the older style keyboard maps, where each was held in an individual Java source file, and compiled separately into class files.


Typist is written to allow localization of messages, GUI elements, online help text, lesson series, and keyboard maps. There are three main resources that you should begin with if you intend to create a localized version of the program:

The first of these contains the messages, GUI element labels, and GUI menu shortcuts - in short, all program text except the help text. To create a national language version of this class, copy the file to the new file MessageResource_<nn>.properties, where <nn> is the ISO code for the language you are translating into ('fr', for example), edit this file and translate each text message in it. Enter non-ASCII characters as Unicode, for example \u00E7 is small c, cedilla, and displays as 'ç'.

The second file contains color definitions for the various GUI elements that Typist uses. You may need to alter these definitions to match the expectation of users in your locale. Store the new colors resources in the file ColorResource_<nn>.properties.

You could also change the colors in the GUI to personalize Typist. For example, to change the background color of the text area in the Help Window, create a file ColorResource_en.properties (assuming you are in an English- speaking locale), and put the following entry in it:


Make sure that this new file is on your CLASSPATH. See the original ColorResource.properties file for details on how to set the colors for particular parts of the GUI, and the list of available color names. This file also contains details on the fonts used in the various GUI elements, if you want to change these too.

The third file is the help text for the program, also used to generate the HTML User Guide document. As with messages, copy the original file to HelpTextResource_<nn>.properties, and translate each help topic that the file contains.

When translating the help text, there is a major difference from all the other properties for non-ASCII characters. This is because the help text is held as HTML. The way to specify non-ASCII characters in HTML is to use special HTML character 'entities', so in help text you should use the HTML &#xxx; form for character entities, rather than '\u00xx' Unicode, to be safe. HTML entities such as &eacute; will not work with Typist - it understands only the most basic named entities (such as &amp;, &quot;, &lt;, and &gt;), so you must use the &#xxx; numeric form. For example, for capital U, umlaut, use &#220; which displays as 'Ü'.

If you do however use Unicode characters in the help text, Typist will display them correctly. Problems are most likely with the HTML User's Guide in combination with browsers that do not understand Unicode.

You may also localize lessons in the same way as these three main resources. For example, to create a French version of lesson series Q, copy the file LessonSeriesQ.properties to LessonSeriesQ_fr.properties, and translate the lesson text in it. Use Unicode for non-ASCII characters in localized lesson series.

To run Typist in a particular locale, simply set a locale for your system or environment before running the program. In UNIX and Linux, you do this by setting a value for the LANG environment variable, for example:

    export LANG

Consult your system documentation for more information on locales. Using the -m or messages options will cause Typist to show you what locale it has found from the system environment.

The translatable sections of all properties files is marked by


When running Typist as an application, any localized message or text files that you create should be on your CLASSPATH. When running it as an applet you can add the localized files to the jar file that the web server delivers to the browser, or perhaps better, create a separate jar file containing just the localized properties files, and add it to the 'ARCHIVE=' list.

You should note that unless you have installed localized messages, help text, or lessons for your system, you will still see Typist operate in English, since this is the 'fallback' language, used where there are no messages or help text for a particular locale.

Note to translators - do not redefine the original properties files anywhere on your CLASSPATH unless you are sure of what you are doing. If some of these resources are absent for any reason, Typist will fail, and your JVM will probably tell you very little about why. The safe, and correct, way to override resources is by creating an '_<nn>' variant of the file. Use 'en' if your system is not set to any particular locale. See the Java documentation on the ResourceBundle class for more information.

Java Runtime Notes

Typist was developed on a combination of the 1.0.2 JDK and the 1.1.7 JDK. both running on Linux, but is now fully converted to use the Java 1.1 event model. The following notes apply to the the various Java runtimes tried so far:

JDK 1.0.2 on Linux
This JVM is not AWT 1.1 based, and is no longer supported.
JDK 1.1.7 on Linux
There are two annoying features that simply will not work with this runtime. The first is the Caps Lock key -- no matter what state keyboard Caps Lock is in, key press events passed in to the program never show uppercase letters; they are always lowercase. The second is that numeric keypad key presses do not, apparently, generate key press events at all, rendering the numeric keypad useless. There is a reasonable workround in place to handle Caps Lock in the program itself, but there is no workround possible for the numeric keypad problem, so this feature simply does not work. Hopefully the situation will improve with later releases. The remainder of the program functions correctly.
JDK 1.1.7B on SCO UnixWare 7
This behaves as JDK 1.1.7 above. Neither Caps Lock nor the numeric keypad will function correctly on this runtime. Also, I noticed some odd threads problems, that seemed to disappear when the program was recompiled on this platform. The remainder of the program functions correctly.
Kaffe 1.0b on Linux
Sadly, the program will not run in Kaffe 1.0b. The GUI appears, but for some reason it receives no key event input at all. A small amount of fiddling about with the GUI buttons and lists usually results in a core dump from Kaffe, sometimes accompanied by an assertion failure message.
Netscape Navigator Gold 3.04 on UnixWare
The JVM in this browser is not AWT 1.1 based, and is no longer supported.
Netscape Communicator 4.07 on Linux
Neither Caps Lock nor the numeric keypad work. And a special treat -- on closing the applet, the browser will complain about finding circular dependencies in forms children, or generally give some other Motif error messages. Additionally, the program's font control seems to be ignored wholesale by the browser, so that all text appears in Courier monospaced font, and none of the tooltips appear. If you can live with these, however, the rest of the program behaves itself.
Netscape Communicator 4.08 on UnixWare
Caps Lock works fine. In other respects, however, this has the same problems as Communicator 4.07 for Linux.
Netscape Communicator 4.5 on Windows
At last, a browser-based runtime that seems, at least so far, to run the complete applet without most of the mishaps described above.
Netscape Communicator 4.61 on Windows
Again, no obvious problems. Caps Lock works fine, and the program's workround, if activated when unnecessary, causes no ill effects. It is unknown if the numeric keypad works, though; this test was performed on a laptop that had no numeric keypad.
Netscape Communicator 4.61 on UnixWare
Apparently, Caps Lock has stopped working again, and the numeric keypad problem remains, as does the circular children dependency in forms children complaint. By and large, however, the program works.
Netscape Communicator 4.7 on Windows
As with Netscape Communicator 4.61 on Windows, the program behaves largely correctly. The only known non-working feature is the audible beep on typing errors, which does not sound, for some reason.

You may need to be prepared for a voyage of discovery with your Java runtime. At the very minimum, if you see any odd failures or other strange behaviour with the program on a particular platform, and you have not done so already, try recompiling -- the Linux JDK used to build the distribution is probably not bug-free either, so this may be all it takes.

Bugs and Omissions

The Caps Lock key does not work correctly on some AWT 1.1 implementations. See Java Runtime Notes for at least some details on which ones have specific problems. There is a workround in the program for this, selectable from the Options menu of the Exercise Window.

The numeric keypad does not generate KeyEvents on some AWT 1.1 implementations. Again, see Java Runtime Notes for details of which JVMs are known to be affected. No workround exists for this problem.

The exercise GUI interface is not as slick as it could be. In particular the slavish use by Typist of TextArea components does not give as much control over things like text placement as might be desirable.

Using properties files to hold lesson series, keyboard maps, program messages, and help text should be OK, but this is a feature that has not had as much testing as the rest of the program. Typist should behave fine with the properties files that it comes with, but it may be less than helpful if you present it with localized files that contain errors, since its error handling may not have been completely exercised.

Using properties files to store program text causes no difficulties for the program when running as an application, but it does generate some difficulties when running as an applet. A typical browser will not load properties files in the same way as it loads class files, meaning that the complete applet code must be sent to the browser in one chunk as a jar file, using the 'ARCHIVE=' attribute to the <APPLET> tag.

This is somewhat of a nuisance, to say the least, because it destroys the ability of the program to delay text downloads from the server until they are actually needed. However, there is a compensating benefit, and that is that the archive can be compressed, whereas class files cannot; this will shorten download times. Also, retrieving a single jar file rather that several individual class files is also likely to be more efficient, since only one socket connection needs to be made. Overall, it probably works out to about the same download time for both the jar file and an initial set of individual classes.

The audible beep on error in the Exercise Window did not work with the Netscape Communicator 4.7 for Windows. Though not tested with other Windows versions of Netscape Communicator, it is likely that this is a generic issue with Windows browsers.

None of Typist's tooltips display when it is run as an applet in a browser. This is a pity, since they offer useful information, especially the tooltips shown on the Keyboard Window. These are used to indicate the complete set of characters that a key generates, handy for verifying keyboard layouts. There is no known workround for this problem.

Tooltips in the AppletViewer do appear, sort of. That is, they render, but are obliterated by the 'Warning' about the window being an applet window. Because of this, and the general failure to appear at all in browsers, the 'notips' option is normally used to just disable tooltips.

Typist is slow to start up.

General Information

This program is a Java reworking of a UNIX C++ reworking of a UNIX C/Curses reworking of an IBM PC reworking of an original DECUS VAX BASIC program. This Java version, Typist v3.1 was created by Simon Baldwin, simonb@sco.com.

Thanks to the original authors, whoever they were, to D. Jason Penney for the initial conversion into C/Curses, and to George Ferguson for posting it to the Internet.


Typist v3.1h (Java), Copyright (C) 2000 Simon Baldwin

This program comes with ABSOLUTELY NO WARRANTY; for details please see the file 'COPYING' supplied with the source code. This is free software, and you are welcome to redistribute it under certain conditions; again, see 'COPYING' for details. This program is released under the GNU General Public License.