Update copyright to 2017
[fanfix.git] / README.md

Jexer - Java Text User Interface library

This library implements a text-based windowing system reminiscient of Borland’s Turbo Vision system. (For those wishing to use the actual C++ Turbo Vision library, see Sergio Sigala’s C++ version based on the public domain sources released by Borland. )

Jexer currently supports three backends:

Additional backends can be created by subclassing jexer.backend.Backend and passing it into the TApplication constructor.

License

This project is licensed under the MIT License. See the file LICENSE for the full license text.

Acknowledgements

Jexer makes use of the Terminus TrueType font made available here .

Usage

Simply subclass TApplication and then run it in a new thread:

```Java import jexer.*;

class MyApplication extends TApplication {

public MyApplication() throws Exception {
    super(BackendType.SWING); // Could also use BackendType.XTERM

    // Create standard menus for File and Window
    addFileMenu();
    addWindowMenu();

    // Add a custom window, see below for its code.
    addWindow(new MyWindow(this));
}

public static void main(String [] args) {
    try {
        MyApplication app = new MyApplication();
        (new Thread(app)).start();
    } catch (Throwable t) {
        t.printStackTrace();
    }
}

} ```

Similarly, subclass TWindow and add some widgets:

```Java class MyWindow extends TWindow {

public MyWindow(TApplication application) {
    // See TWindow's API for several constructors.  This one uses the
    // application, title, width, and height.  Note that the window width
    // and height include the borders.  The widgets inside the window
    // will see (0, 0) as the top-left corner inside the borders,
    // i.e. what the window would see as (1, 1).
    super(application, "My Window", 30, 20);

    // See TWidget's API for convenience methods to add various kinds of
    // widgets.  Note that ANY widget can be a container for other
    // widgets: TRadioGroup for example has TRadioButtons as child
    // widgets.

    // We will add a basic label, text entry field, and button.
    addLabel("This is a label", 5, 3);
    addField(5, 5, 20, false, "enter text here");
    // For the button, we will pop up a message box if the user presses
    // it.
    addButton("Press &Me!", 5, 8, new TAction() {
        public void DO() {
            MyWindow.this.messageBox("Box Title", "You pressed me, yay!");
        }
    } );
}

} ```

Put these into a file, compile it with jexer.jar in the classpath, run it and you’ll see an application like this:

The Example Code Above

See the files in jexer.demos for many more detailed examples showing all of the existing UI controls. The demo can be run in three different ways:

More Screenshots

Several Windows Open Including A Terminal

Yo Dawg...

System Properties

The following properties control features of Jexer:

jexer.Swing

Used only by jexer.demos.Demo1. If true, use the Swing interface for the demo application. Default: true on Windows platforms (os.name starts with “Windows”), false on non-Windows platforms.

jexer.Swing.cursorStyle

Used by jexer.io.SwingScreen. Selects the cursor style to draw. Valid values are: underline, block, outline. Default: underline.

Known Issues / Arbitrary Decisions

Some arbitrary design decisions had to be made when either the obviously expected behavior did not happen or when a specification was ambiguous. This section describes such issues.

Roadmap

Many tasks remain before calling this version 1.0. See docs/TODO.md for the complete list of tasks.