blinking cursor and SGR 1006 mode

[nikiroo-utils.git] / README.md

diff --git a/README.md b/README.md
index ce707711f14c465735302502487b991dd234b186..1e1bb544bbaa83f05eda45babc25eef10c57b1dc 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 Jexer - Java Text User Interface library
 ========================================
 
 Jexer - Java Text User Interface library
 ========================================
 

-WARNING: THIS IS ALPHA CODE!
+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
 
 This library is intended to implement a text-based windowing system
 loosely reminiscient of Borland's [Turbo


@@ -15,25 +16,35 @@ 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
 * 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.  This is the default backend on non-Windows platforms.
+  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.

 
 

-* Java AWT UI.  This backend can be selected by setting
-  jexer.AWT=true.  This is the default backend on Windows platforms.
-  AWT is VERY experimental, please consider filing bugs when you
-  encounter them.
+* 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.

 
 

-A demo application showing the existing UI controls is available via
-'java -jar jexer.jar' or 'java -Djexer.AWT=true -jar jexer.jar' .
+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
 -------
 
 
 
 
 License
 -------
 

-This project 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.

 
 
 
 
 
 


@@ -49,7 +60,7 @@ Usage
 -----
 
 Usage patterns are still being worked on, but in general the goal will
 -----
 
 Usage patterns are still being worked on, but in general the goal will

-be to build applications somewhat as follows:
+be to build applications as follows:

 
 ```Java
 import jexer.*;
 
 ```Java
 import jexer.*;


@@ -57,7 +68,7 @@ import jexer.*;
 public class MyApplication extends TApplication {
 
     public MyApplication() {
 public class MyApplication extends TApplication {
 
     public MyApplication() {

-        super();
+        super(BackendType.SWING); // Could also use BackendType.XTERM

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


@@ -66,7 +77,7 @@ public class MyApplication extends TApplication {
 
     public static void main(String [] args) {
         MyApplication app = new MyApplication();
 
     public static void main(String [] args) {
         MyApplication app = new MyApplication();

-        app.run();
+        (new Thread(app)).start();

     }
 }
 ```
     }
 }
 ```


@@ -91,62 +102,106 @@ ambiguous.  This section describes such issues.
     between blocking reads (which is necessary to get UTF8 translation
     correct) and file streams.
 
     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()).
+
+  - 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.
+
+  ECMA48 Backend
+  --------------
+
+  - Java's InputStreamReader requires a valid UTF-8 stream.  The
+    default X10 encoding for mouse coordinates outside (160,94) can
+    corrupt that stream, at best putting garbage keyboard events in
+    the input queue but at worst causing the backend reader thread to
+    throw an Exception and exit and make the entire UI unusable.
+    Mouse support therefore requires a terminal that can deliver
+    either UTF-8 coordinates (1005 mode) or SGR coordinates (1006
+    mode).  Most modern terminals can do this.
+
+  Use of 'stty'
+  -------------
+
+  - jexer.session.TTYSession calls 'stty size' once every second to
+    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().  The terminal is (blindly!) put back in 'stty sane
+    cooked' mode when exiting.
+
+
+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.
+
+

 
 Roadmap
 -------
 
 Many tasks remain before calling this version 1.0:
 
 
 Roadmap
 -------
 
 Many tasks remain before calling this version 1.0:
 

-0.0.2:
+0.0.2: STABILIZE EXISTING

 
 

-- Making TMenu keyboard accelerators active/inactive
-- AWT:
-  - Blinking cursor
-  - Block cursor
-  - Fix mouse artifacts

 - ECMA48Backend running on socket
 - ECMA48Backend running on socket

+
+0.0.3: FINISH PORTING
+

 - TTreeView
 - TTreeView

+  - Also add keyboard navigation

 - TDirectoryList
 - TDirectoryList

+  - Also add keyboard navigation

 - TFileOpen
 - TFileOpen

-- Decide on naming convention: getText, getValue, getLabel: one or all
-  of them?
-- Refactor:
-  - TKeypress:
-    - getCh() --> getChar()
-    - getAlt/getCtrl/getShift --> isAltDown / isCtrlDown / isShiftDown
-  - Other boolean getters --> isSomething

 
 

-0.0.3:
+0.0.4: NEW STUFF

 
 

+- Making TMenu keyboard accelerators active/inactive
+- TStatusBar

 - TEditor
 - TEditor

+- TWindow
+  - "Smart placement" for new windows

 
 

-0.0.4:
+0.0.5: BUG HUNT

 
 

-- Bugs
-  - TSubMenu keyboard mnemonic not working
-  - TDirectoryList cannot be navigated only with keyboard
-  - TTreeView cannot be navigated only with keyboard
-  - RangeViolation after dragging scrollbar up/down
+- TSubMenu keyboard mnemonic not working

 
 

-0.1.0:
+0.1.0: BETA RELEASE

 
 

-- TWindow
-  - "Smart placement" for new windows
-- ECMATerminal
-  - Mouse 1006 mode parsing
+- TSpinner
+- TComboBox
+- TListBox
+- TCalendar
+- TColorPicker

 
 Wishlist features (2.0):
 
 - TTerminal
   - Handle resize events (pass to child process)
 
 Wishlist features (2.0):
 
 - TTerminal
   - Handle resize events (pass to child process)

-  - xterm mouse handling

 - Screen
   - Allow complex characters in putCharXY() and detect them in putStrXY().
 - Screen
   - Allow complex characters in putCharXY() and detect them in putStrXY().

-- TComboBox
-- TListBox
-- TSpinner
-- TCalendar widget
-- TColorPicker widget

 - Drag and drop
   - TEditor
   - TField
 - Drag and drop
   - TEditor
   - TField


@@ -160,3 +215,4 @@ Screenshots
 
 ![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
 
 
 ![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.")