A Java Windowing Toolkit for Text Terminals

1. Download the latest zipfile from http://sourceforge.net/projects/charva.

2. Change to a suitable directory ($HOME/work, say) and extract the contents using the command:

               unzip charva-x.y.z.zip
           

   This will create a directory tree called "charva" in the current directory. Set the environment variable CHARVA_HOME to the full pathname of this new directory.

3. Set the environment variable JAVA_HOME to the name of your JDK installation directory, for example:

               export JAVA_HOME=/usr/local/jdk1.4.2
           

4. At this stage, if you have JDK1.3, JDK1.4 or JDK1.5 installed, you can run the test program as described in step 8 below (precompiled libraries for Linux, compiled with J2SDK1.4.2, are included in the download package, as $CHARVA_HOME/c/lib/libTerminal.so and $CHARVA_HOME/java/dist/lib/charva.jar). I have tested Charva with RedHat Linux 7, 8 and 9, Fedora 3 and 4, CentOS 4, Windows 98, Windows 2000, and Windows XP. Others have ported Charva to various other flavors of Unix. If you are running some other version of Unix or have a different version of the JDK, you will have to build the libraries and the test program as described in the following steps. Operating-system-specific Makefiles are provided in the $CHARVA_HOME/c/src directory. The required DLL for Windows is provided in the $CHARVA_HOME/c/lib directory.

5. Make sure you have Apache Ant installed. Instructions for setting up Ant are available on its website.

6. Compile the Java classes, generate the JNI header file, and compile the "tutorial" program with the following commands:

               cd $CHARVA_HOME
               ant compile
               ant javah
               ant compile-test
           

7. Build the JNI (Java Native Interface) library libTerminal.so by entering the following commands (you need to have the ncurses-devel RPM, i.e. the ncurses header files, installed for this step to work):

               ant makeDLL
           

   (This has been tested on Linux: if it doesn't work for you, you can generate the shared library "manually" with the following commands):

               cd $CHARVA_HOME/c/src
               make -f os-specific-makefile

8. Run the tutorial program by entering the following commands:

               cd $CHARVA_HOME
               sh test.sh

   (If you are running Windows, use wintest.bat instead). Two different versions (a Swing version and a CHARVA version) of the tutorial program are provided in the tarball. The source code of the two programs is almost identical; they differ in only a few lines. To run the Swing version instead of the Charva version, type "sh test.sh swing" instead. Note that this program uses the standard Java Swing GUI, and therefore your X display must be up and running for this program to work.

• a traditional serial terminal, such as a VT100 or VT220, logged directly into the computer's serial port

• an "xterm" terminal emulator on an X-windows display (don't use the "gnome-terminal" application that comes with GNOME; it's buggy)

• a remote terminal emulator (such as PuTTY; don't even try the Telnet program shipped with Windows, it's broken) logged into the host computer via a Telnet or SSH session.

The tutorial program displays a frame with the usual menu-bar at the top. You can select a menu by pressing the LEFT or RIGHT cursor keys, then pressing ENTER on the selected menu. Each menu item pops up a dialog that demonstrates some feature(s) of CHARVA.

Moving from one field to the next within a dialog-box is done by pressing the TAB key. You should also be able to move from each field to the previous field by pressing the BACK-TAB key; but the mapping of the BACK-TAB key is not standard on all terminals. Many terminals map BACK-TAB to SHIFT+TAB; if in doubt, refer to the FAQ page.

You should be able to edit text input fields by using the BACKSPACE and DELETE keys, and navigate within textfields using the HOME, END, LEFT and RIGHT cursor keys.

If your terminal-emulator reports mouse-events, you should be able to move the focus to any component in the topmost frame (or dialog-box) by clicking on the component. Clicking on a JButton, JComboBox or JMenuItem invokes it. Clicking an item inside a JList moves the current row to the item; double-clicking the item selects/deselects it. Clicking inside a JTextField or JTextArea moves the caret (the text insertion point) to where the mouse was clicked.

If any of these keys or the mouse does not work, check whether the terminfo description of your terminal is correctly set up. Also see the FAQ page

You can view the API documentation of the CHARVA library by pointing your Web browser at $CHARVA_HOME/docs/api/index.html (on your local machine). You can also browse the API documentation online.

• On Linux and Solaris it is specified by the environment variable LD_LIBRARY_PATH

• On AIX the environment variable is LIBPATH

• On HP-UX the environment variable is SHLIB_PATH, and the filename must be libTerminal.sl

• On Win32 the library file is Terminal.dll and you specify the search path with the command-line option -Djava.library.path=directory_containing_Terminal.dll

You also need to put the JAR file (charva.jar) into your Java CLASSPATH. Look at the script $CHARVA_HOME/test.sh for an example of how to do this on Linux.

If you want to build a Charva application as a native executable that you can deploy on a system that doesn't have a Java interpreter, have a look at the file "Makefile.gcj.txt" in the c/src directory of the Charva distribution.

I would welcome your feedback about the usefulness and usability of the CHARVA package, and about errors or omissions in these web pages. Please send me your comments at rob@pitman.co.za