clean readme
authorKevin Lamonte <kevin.lamonte@gmail.com>
Thu, 2 Apr 2015 13:19:13 +0000 (09:19 -0400)
committerKevin Lamonte <kevin.lamonte@gmail.com>
Thu, 2 Apr 2015 13:19:13 +0000 (09:19 -0400)
README.md
screenshots/readme_application.png [new file with mode: 0644]

index 31cf5230e59da7144681a739591ffda2ad4a59be..14eaa4087d37bcc296141ab83b3c3080da2fe5cf 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,17 +1,13 @@
 Jexer - Java Text User Interface library
 ========================================
 
 Jexer - Java Text User Interface library
 ========================================
 
-WARNING: THIS IS ALPHA CODE!  PLEASE CONSIDER FILING BUGS AS YOU
-ENCOUNTER THEM.
+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/) )
 
 
-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.
-
-Three backends are available:
+Jexer currently supports three backends:
 
 * 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
 
 * 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
@@ -30,20 +26,6 @@ Three backends are available:
   which is set in jexer.session.SwingSession.  For the demo
   application, this is the default backend on Windows platforms.
 
   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 can be seen in
-three ways:
-
-  * 'java -jar jexer.jar' .  This will use System.in/out on
-    non-Windows, or Swing on Windows.
-
-  * 'java -Djexer.Swing=true -jar jexer.jar' .  This will always use
-    Swing.
-
-  * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
-    number to run the TCP daemon on).  This will use the telnet
-    protocol to establish an 8-bit clean channel and be aware of
-    screen size changes.
-
 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.
@@ -75,30 +57,116 @@ here](http://files.ax86.net/terminus-ttf/) .
 Usage
 -----
 
 Usage
 -----
 
-Usage patterns are still being worked on, but in general the goal will
-be to build applications as follows:
+Simply subclass TApplication and then run it in a new thread:
 
 ```Java
 import jexer.*;
 
 
 ```Java
 import jexer.*;
 
-public class MyApplication extends TApplication {
+class MyApplication extends TApplication {
 
 
-    public MyApplication() {
+    public MyApplication() throws Exception {
         super(BackendType.SWING); // Could also use BackendType.XTERM
 
         // Create standard menus for File and Window
         addFileMenu();
         addWindowMenu();
         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) {
     }
 
     public static void main(String [] args) {
-        MyApplication app = new MyApplication();
-        (new Thread(app)).start();
+        try {
+            MyApplication app = new MyApplication();
+            (new Thread(app)).start();
+        } catch (Throwable t) {
+            t.printStackTrace();
+        }
     }
 }
 ```
 
     }
 }
 ```
 
-See the files in jexer.demos for more detailed examples.
+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](/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:
+
+  * '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.
+
+  * 'java -Djexer.Swing=true -jar jexer.jar' .  This will always use
+    Swing on any platform.
+
+  * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
+    number to run the TCP daemon on).  This will use the telnet
+    protocol to establish an 8-bit clean channel and be aware of
+    screen size changes.
+
+
+
+More 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.")
+
+
+
+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.
 
 
 
 
 
 
@@ -148,34 +216,17 @@ ambiguous.  This section describes such issues.
 
 
 
 
 
 
-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.3: FINISH PORTING
+0.0.3
 
 
-0.0.4: NEW STUFF
+- TListBox
+- TColorPicker
+
+0.0.4
 
 - TStatusBar
 - TEditor
 
 - TStatusBar
 - TEditor
@@ -190,27 +241,17 @@ Many tasks remain before calling this version 1.0:
 
 - TSpinner
 - TComboBox
 
 - TSpinner
 - TComboBox
-- TListBox
 - TCalendar
 - TCalendar
-- TColorPicker
 
 Wishlist features (2.0):
 
 - TTerminal
   - Handle resize events (pass to child process)
 - Screen
 
 Wishlist features (2.0):
 
 - TTerminal
   - Handle resize events (pass to child process)
 - Screen
-  - Allow complex characters in putCharXY() and detect them in putStrXY().
+  - Allow complex characters in putCharXY() and detect them in putStringXY().
 - Drag and drop
   - TEditor
   - TField
   - TText
   - TTerminal
   - TComboBox
 - Drag and drop
   - TEditor
   - TField
   - TText
   - TTerminal
   - TComboBox
-
-
-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.")
diff --git a/screenshots/readme_application.png b/screenshots/readme_application.png
new file mode 100644 (file)
index 0000000..6e3eed8
Binary files /dev/null and b/screenshots/readme_application.png differ