Lanterna
Lanterna
is a Java library for writing GUIs in a text-only environment, very similar to the C library
ncurses, but with more functionality. Lanterna is structured into three layers:
- A low level terminal which gives you control over the terminal window as a kind of text area.
- The second level is a screen buffer, which makes writing similar to modifying a 2D array of characters.
- The third level is a GUI toolkit with windows, buttons, labels, and other components.
My examples focus on the second and third levels
by using Lanterna's screen and gui2
packages for the most part, along with some helper
functions stored in Utils.java and
SoundUtils.java.
The code
has been tested on MS Windows and Linux, and I've included a
few screenshots of the more graphically interesting examples,
most of which were snapped on Linux accessed from MS Windows
via a putty terminal.
Screen-based Examples
- Hello.java: Displays some messages, then waits for the user to quit by typing esc.
- ShowText.java: Any text that the user types appears in the window, with ENTER causing it to be cleared.
- Guess.java: A guess-the-number game.
- Hangman.java: A Hangman game, with
the added bonus of a hanged man being incrementally drawn as the
game progresses. Screenshot.
I found the text-drawing AsciiFlow online tool useful for creating the basic picture.
- ColorsGrid.java: A screenful of randomly colored cells keeps changing. The code also responds to terminal size changes by drawing more
or less cells, and reporting the new size in a message box.
Screenshot.
- Bounce.java: A 'ball' bounces around the window, with a tone played when it hits a 'wall'.
- Life.java: A version of John Conway's Game of Life. Screenshot.
- Matrix.java: A version of
The Matrix's text scrolling effect. Screenshot.
- Clock.java: An analog clock showing hour, minute, and second hands.
Screenshot.
- Fireworks.java:
Repeatedly shoots a firework from a random location on the 'floor', has it travel upwards, and then explode in a random color and a bang.
- SnakeGame.java: Move a snake around the window, eating food, and avoiding
bombs. Death ensues if it touches a wall or
itself. Screenshot.
The code also utilizes
- Snake.java and
SnakeDirection.java.
GUI-based Examples
- HelloGUI.java: A window using a Lanterna theme, with a label drawn in the middle of the screen, and a close box at the bottom left.
Screenshot.
- A potpourri of GUI components in Comps1.java, including a label, a textbox,
a password field, a read-only combo-box,
an editable combo-box, a button using a MessageDialog,
a separator line, and a close button.
Screenshot.
- More GUI components in
Comps2.java, including
checkboxes, textfields, buttons, a read-only text area
with scrollbars, and a progress bar.
Screenshot.
- DialogsTest.java:
Multiple dialog types, including
text input, a password dialog, a multi-line dialog,
a field that only accepts numerical input, file
dialogs for opening and saving, and an ActionList.
Screenshot.
- MenuTest.java: A window with three menus: "File", "Country", and "Help", utilizing
sub-menus and a user-defined component.
Screenshot.
- Calc.java: A calculator with
the usual buttons, and "1/x" and "√".
Screenshot.
The evaluation is carried out by the
mXparser library.
A few simple examples of how to use that library
independently are given in
EvalExprs.java.
- GUIOverTelnet.java:
Fires up a TelnetTerminalServer, and then waits for
a connection from a telnet client, which
is presented
with a GUI window containing a button, a multi-line textbox,
and a custom component.
Screenshot of the
client running on MS Windows, and a
Screenshot on Linux.
Other Downloads and Links
- Batch files to easily compile and run my code:
compile.bat and
run.bat
- Bash scripts to do the same thing on Linux:
compile.sh and
run.sh. These have to be
made executable with chmod a+x before their
first use.
- out.txt: Lanterna takes control of standard
input and output, and so when I've wanted to print
extra information, error messages, or debugging text, I've
sent it to stderr using System.out.err(). In
the run batch and Bash scripts,
Java's error stream is redirected into
out.txt, which is printed when Java finishes.
It's also possible to monitor the file using something
like tail -f.
- All the examples in one
zipped file (40 KB)
- My copies of the
Lanterna library (924 KB), which includes the
mXparser
library required by my
Calc.java example.
Unzip the file, and place the libs folder in the
same directory as the examples and batch/Bash files.
- The Lanterna documentation, and a Google Groups forum.
- Two sources of examples are Lanterna's
four
tutorial programs, and the test suite included in the
source code at
src\test\java\com\googlecode\lanterna\.
- The Lanterna API documentation.
Dr. Andrew Davison
E-mail: ad@coe.psu.ac.th
Back to the third-party libraries page
