git://git.nikiroo.be / nikiroo-utils.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
TEditor 50% complete
[nikiroo-utils.git] / README.md
diff --git a/README.md b/README.md
index 4e71a9c60490da52f21588553934f9d7d2b1340f..7dc0bb4b32ebe78dd9af6f88a7b5310eac880605 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,8 +4,10 @@ Jexer - Java Text User Interface library
 This library implements a text-based windowing system reminiscient of
 Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision)
 system.  (For those wishing to use the actual C++ Turbo Vision
 This library implements a text-based windowing system reminiscient of
 Borland's [Turbo Vision](http://en.wikipedia.org/wiki/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.](http://tvision.sourceforge.net/) )
+library, see [Sergio Sigala's C++ version based on the sources
+released by Borland,](http://tvision.sourceforge.net/) or consider
+Free Pascal's [Free Vision
+library.](http://wiki.freepascal.org/Free_Vision))
 
 Jexer currently supports three backends:
 
 
 Jexer currently supports three backends:
 
@@ -14,7 +16,7 @@ Jexer currently supports three backends:
   sequences generated by the library itself: ncurses is not required
   or linked to.  xterm mouse tracking using UTF8 and SGR coordinates
   are supported.  For the demo application, this is the default
   sequences generated by the library itself: ncurses is not required
   or linked to.  xterm mouse tracking using UTF8 and SGR coordinates
   are supported.  For the demo application, this is the default
-  backend on non-Windows platforms.
+  backend on non-Windows/non-Mac platforms.
 
 * The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
   but to any general InputStream/OutputStream or Reader/Writer.  See
 
 * The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
   but to any general InputStream/OutputStream or Reader/Writer.  See
@@ -22,15 +24,20 @@ Jexer currently supports three backends:
   TCP socket.  jexer.demos.Demo3 demonstrates how one might use a
   character encoding than the default UTF-8.
 
   TCP socket.  jexer.demos.Demo3 demonstrates how one might use a
   character encoding than the default UTF-8.
 
-* 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.
+* Java Swing UI.  The default window size for Swing is 80x25 and 20
+  point font; this can be changed in the TApplication(BackendType)
+  constructor.  For the demo applications, this is the default backend
+  on Windows and Mac platforms.  This backend can be explicitly
+  selected for the demo applications by setting jexer.Swing=true.
 
 Additional backends can be created by subclassing
 jexer.backend.Backend and passing it into the TApplication
 constructor.
 
 
 Additional backends can be created by subclassing
 jexer.backend.Backend and passing it into the TApplication
 constructor.
 
+The Jexer homepage, which includes additional information and binary
+release downloads, is at: https://jexer.sourceforge.io .  The Jexer
+source code is hosted at: https://github.com/klamonte/jexer .
+
 
 
 License
 
 
 License
@@ -119,12 +126,12 @@ it and you'll see an application like this:
 ![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md")
 
 See the files in jexer.demos for many more detailed examples showing
 ![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md")
 
 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:
+all of the existing UI controls.  The available demos can be run as
+follows:
 
   * 'java -jar jexer.jar' .  This will use System.in/out with
 
   * 'java -jar jexer.jar' .  This will use System.in/out with
-    xterm-like sequences on non-Windows platforms.  On Windows it will
-    use a Swing JFrame.
+    xterm-like sequences on non-Windows non-Mac platforms.  On Windows
+    and Mac it will use a Swing JFrame.
 
   * 'java -Djexer.Swing=true -jar jexer.jar' .  This will always use
     Swing on any platform.
 
   * 'java -Djexer.Swing=true -jar jexer.jar' .  This will always use
     Swing on any platform.
@@ -134,6 +141,21 @@ different ways:
     protocol to establish an 8-bit clean channel and be aware of
     screen size changes.
 
     protocol to establish an 8-bit clean channel and be aware of
     screen size changes.
 
+  * 'java -cp jexer.jar jexer.demos.Demo3' .  This will use
+    System.in/out with xterm-like sequences.  One can see in the code
+    how to pass a different InputReader and OutputReader to
+    TApplication, permitting a different encoding than UTF-8.
+
+  * 'java -cp jexer.jar jexer.demos.Demo4' .  This demonstrates hidden
+    windows and a custom TDesktop.
+
+  * 'java -cp jexer.jar jexer.demos.Demo5' .  This demonstrates two
+    demo applications using different fonts in the same Swing frame.
+
+  * 'java -cp jexer.jar jexer.demos.Demo6' .  This demonstrates one
+    application performing I/O to two screens: an xterm screen and a
+    Swing screen.
+
 
 
 More Screenshots
 
 
 More Screenshots
@@ -153,15 +175,26 @@ The following properties control features of Jexer:
   jexer.Swing
   -----------
 
   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.
+  Used only by jexer.demos.Demo1 and jexer.demos.Demo4.  If true, use
+  the Swing interface for the demo application.  Default: true on
+  Windows (os.name starts with "Windows") and Mac (os.name starts with
+  "Mac"), false on non-Windows and non-Mac platforms.
 
   jexer.Swing.cursorStyle
   -----------------------
 
 
   jexer.Swing.cursorStyle
   -----------------------
 
-  Used by jexer.io.SwingScreen.  Selects the cursor style to draw.
-  Valid values are: underline, block, outline.  Default: underline.
+  Used by jexer.backend.SwingTerminal.  Selects the cursor style to
+  draw.  Valid values are: underline, block, outline.  Default:
+  underline.
+
+  jexer.Swing.tripleBuffer
+  ------------------------
+
+  Used by jexer.backend.SwingTerminal.  If true, use triple-buffering
+  which reduces screen tearing but may also be slower to draw on
+  slower systems.  If false, use naive Swing thread drawing, which may
+  be faster on slower systems but also more likely to have screen
+  tearing.  Default: true.
 
 
 
 
 
 
@@ -172,11 +205,10 @@ 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.
 
 obviously expected behavior did not happen or when a specification was
 ambiguous.  This section describes such issues.
 
-  - 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.
+  - The JVM needs some warmup time to exhibit the true performance
+    behavior.  Drag a window around for a bit to see this: the initial
+    performance is slow, then the JIT compiler kicks in and Jexer can
+    be visually competitive with C/C++ curses applications.
 
   - See jexer.tterminal.ECMA48 for more specifics of terminal
     emulation limitations.
 
   - See jexer.tterminal.ECMA48 for more specifics of terminal
     emulation limitations.
@@ -186,10 +218,14 @@ ambiguous.  This section describes such issues.
     input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
     SetConsoleMode()).
 
     input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
     SetConsoleMode()).
 
-  - TTerminalWindow launches 'script -fqe /dev/null' on non-Windows
-    platforms.  This is a workaround for the C library behavior of
-    checking for a tty: script launches $SHELL in a pseudo-tty.  This
-    works on Linux but might not on other Posix-y platforms.
+  - TTerminalWindow launches 'script -fqe /dev/null' or 'script -q -F
+    /dev/null' on non-Windows platforms.  This is a workaround for the
+    C library behavior of checking for a tty: script launches $SHELL
+    in a pseudo-tty.  This works on Linux and Mac but might not on
+    other Posix-y platforms.
+
+  - Closing a TTerminalWindow without exiting the process inside it
+    may result in a zombie 'script' process.
 
   - Java's InputStreamReader as used by the ECMA48 backend requires a
     valid UTF-8 stream.  The default X10 encoding for mouse
 
   - Java's InputStreamReader as used by the ECMA48 backend requires a
     valid UTF-8 stream.  The default X10 encoding for mouse
@@ -205,43 +241,14 @@ ambiguous.  This section describes such issues.
     check the current window size, performing the same function as
     ioctl(TIOCGWINSZ) but without requiring a native library.
 
     check the current window size, performing the same function as
     ioctl(TIOCGWINSZ) but without requiring a native library.
 
-  - jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of
-    cfmakeraw() when using System.in/out.  System.out is also
-    (blindly!)  put in 'stty sane cooked' mode when exiting.
+  - jexer.backend.ECMA48Terminal calls 'stty' to perform the
+    equivalent of cfmakeraw() when using System.in/out.  System.out is
+    also (blindly!) put in 'stty sane cooked' mode when exiting.
 
 
 
 Roadmap
 -------
 
 
 
 
 Roadmap
 -------
 
-Many tasks remain before calling this version 1.0:
-
-0.0.4
-
-- TStatusBar
-- TEditor
-- TWindow
-  - "Smart placement" for new windows
-
-0.0.5: BUG HUNT
-
-- Swing performance is better, triple-buffering appears to have helped.
-
-0.1.0: BETA RELEASE
-
-- TSpinner
-- TComboBox
-- TCalendar
-
-Wishlist features (2.0):
-
-- TTerminal
-  - Handle resize events (pass to child process)
-- Screen
-  - Allow complex characters in putCharXY() and detect them in putStringXY().
-- Drag and drop
-  - TEditor
-  - TField
-  - TText
-  - TTerminal
-  - TComboBox
+Many tasks remain before calling this version 1.0.  See docs/TODO.md
+for the complete list of tasks.
Small java utilities, mostly for personal use -- but feel free to have a look