X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;f=README.md;h=24b437a65a4dee26b1392ddda1033bc40860f3d8;hb=7c870d89433346ccb5505f8f9ba62d3fc18fe996;hp=bbe38d640af88567e030fe45f93132870b34ad8c;hpb=128e5be1ffb65d047d8461ea1cfb65c22686ec91;p=fanfix.git diff --git a/README.md b/README.md index bbe38d6..24b437a 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,66 @@ Jexer - Java Text User Interface library ======================================== -This library is currently in design, but when finished it is intended -to implement a text-based windowing system loosely reminiscient of -Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision) -library. For those wishing to use the actual C++ Turbo Vision -library, see [Sergio Sigala's updated -version](http://tvision.sourceforge.net/) that runs on many more -platforms. +WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU +ENCOUNTER THEM. + +This library is intended to implement a text-based windowing system +loosely reminiscient of Borland's [Turbo +Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those +wishing to use the actual C++ Turbo Vision library, see [Sergio +Sigala's updated version](http://tvision.sourceforge.net/) that runs +on many more platforms. + +Two backends are available: + +* System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal + (tested on Linux + xterm). I/O is handled through terminal escape + sequences generated by the library itself: ncurses is not required + or linked to. xterm mouse tracking using UTF8 coordinates is + supported. For the demo application, this is the default backend on + non-Windows platforms. + +* Java Swing UI. This backend can be selected by setting + jexer.Swing=true. The default window size for Swing is 132x40, + which is set in jexer.session.SwingSession. For the demo + application, this is the default backend on Windows platforms. + +The demo application showing the existing UI controls is available via +'java -jar jexer.jar' or 'java -Djexer.Swing=true -jar jexer.jar' . + +Additional backends can be created by subclassing +jexer.backend.Backend and passing it into the TApplication +constructor. + License ------- -This library is licensed LGPL ("GNU Lesser General Public License") -version 3 or greater. See the file LICENSE for the full license text, -which includes both the GPL v3 and the LGPL supplemental terms. +This project is licensed LGPL ("GNU Lesser General Public License", +sometimes called the "Library GPL") version 3 or greater. You may +freely use Jexer in both closed source (proprietary) and open source +applications, however any changes you make to the Jexer code must be +made available to your users. + +See the file LICENSE for the full license text, which includes both +the GPL v3 and the LGPL supplemental terms. + + + +Acknowledgements +---------------- + +Jexer makes use of the Terminus TrueType font [made available +here](http://files.ax86.net/terminus-ttf/) . + Usage ----- -The library is currently under initial development, usage patterns are -still being worked on. Generally the goal will be to build -applications somewhat as follows: +Usage patterns are still being worked on, but in general the goal will +be to build applications as follows: ```Java import jexer.*; @@ -31,12 +68,7 @@ import jexer.*; public class MyApplication extends TApplication { public MyApplication() { - super(); - - // Create an editor window that has support for - // copy/paste, search text, arrow keys, horizontal - // and vertical scrollbar, etc. - addEditor(); + super(BackendType.SWING); // Could also use BackendType.XTERM // Create standard menus for File and Window addFileMenu(); @@ -45,70 +77,115 @@ public class MyApplication extends TApplication { public static void main(String [] args) { MyApplication app = new MyApplication(); - app.run(); + (new Thread(app)).start(); } } ``` +See the file demos/Demo1.java for detailed examples. + + + +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. + + TTerminalWindow + --------------- + + - TTerminalWindow will hang on input from the remote if the + TApplication is exited before the TTerminalWindow's process has + closed on its own. This is due to a Java limitation/interaction + between blocking reads (which is necessary to get UTF8 translation + correct) and file streams. + + - See jexer.tterminal.ECMA48 for more specifics of terminal + emulation limitations. + + - TTerminalWindow uses cmd.exe on Windows. Output will not be seen + until enter is pressed, due to cmd.exe's use of line-oriented + input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and + SetConsoleMode()). + + ECMA48 Backend + -------------- + + - Mouse support for BackendType.ECMA48/XTERM currently requires UTF-8 + coordinates (1005 mode). Terminals that support UTF-8 mouse coordinates + include xterm, rxvt-unicode, gnome-terminal, and konsole. Due to Java's + InputStreamReader requirement of a valid UTF-8 stream, one must assume + the terminal will always generate correct UTF-8 bytes. Mode 1006 (SGR) + will be supported in a future release. + + Roadmap ------- Many tasks remain before calling this version 1.0: -0.0.1: +0.0.2: STABILIZE EXISTING + +- TTerminalWindow + - Expose shell commands as properties +- Swing: + - Blinking cursor + - Block cursor +- ECMA48Backend running on socket +- TFileOpen +- Document any properties used + - Expose use of 'stty' + +0.0.3: FINISH PORTING -- TDirectoryList -- TMessageBox -- THScroller / TVScroller -- TText - TTreeView + - Also add keyboard navigation +- TDirectoryList + - Also add keyboard navigation -0.0.2: +0.0.4: NEW STUFF +- Making TMenu keyboard accelerators active/inactive +- TStatusBar - TEditor -- TFileOpen -- TTerminal +- TWindow + - "Smart placement" for new windows -0.0.3: +0.0.5: BUG HUNT -- Bugs - - TSubMenu keyboard mnemonic not working - - kbDel assertion failure in TMenu (MID_CLEAR) -- TEditor - - Word wrap - - Forward/backward word - - Search - - Replace - - Cut/Copy/Paste +- TSubMenu keyboard mnemonic not working +- ECMA48Terminal + - Mode 1006 mouse coordinates -0.0.4: +0.1.0: BETA RELEASE -- ECMATerminal - - Mouse 1006 mode parsing -- Bugs - - TDirectoryList cannot be navigated only with keyboard - - TTreeView cannot be navigated only with keyboard - - RangeViolation after dragging scrollbar up/down +- TSpinner +- TComboBox +- TListBox +- TCalendar +- TColorPicker Wishlist features (2.0): - TTerminal - Handle resize events (pass to child process) - - xterm mouse handling -- TWindow - - "Smart placement" for new windows - Screen - Allow complex characters in putCharXY() and detect them in putStrXY(). -- TComboBox -- TListBox -- TSpinner -- TCalendar widget -- TColorPicker widget - Drag and drop - TEditor - TField - TText - TTerminal - TComboBox -- AWTBackend + + +Screenshots +----------- + +![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") + +![Yo Dawg...](/screenshots/yodawg.png?raw=true "Yo Dawg, I heard you like text windowing systems, so I ran a text windowing system inside your text windowing system so you can have a terminal in your terminal.") +