Commits

Steve Losh committed c9f1384

terminal docs.

Comments (0)

Files changed (3)

docs/4-reference.markdown

 
 * `:utf-8`
 
+### Consoles
+
+When creating a Terminal or Screen, you can optionally specify a specific kind
+of Terminal or Screen to create.
+
+If it's not supported (e.g.: trying to create a Swing Terminal on a system
+without X) then who knows what will happen.  Make sure you know what you're
+doing if you use anything other than `:auto`.
+
+* `:auto` - Let Lanterna try to guess the appropriate kind of console to use.
+  If there's a windowing environment present the Swing console will be used,
+  otherwise an appropriate text console will be used.
+* `:swing` - Force a Swing-based console.
+* `:text` - Force a text-based (i.e.: non-Swing) console.  Lanterna will try to guess the
+  appropriate kind of console (UNIX or Cygwin) by the OS.
+* `:unix` - Force a UNIX text-based console.
+* `:cygwin` - Force a Cygwin text-based console.
+
 Terminals
 ---------
 
 ### lanterna.terminal/get-terminal
+
+    :::clojure
+    (get-terminal)
+    (get-terminal kind)
+    (get-terminal kind options)
+
+Get a terminal object.
+
+`kind` is a [console constant](#consoles) describing the type of terminal you
+want.  If unspecified it defaults to `:auto`.
+
+Options can contain one or more of the following mappings:
+
+* `:cols` - Width of the desired terminal in characters (default `80`).
+* `:rows` - Height of the desired terminal in characters (default `24`).
+* `:charset` - Charset of the desired terminal.  This should be a [charset
+  constant](#charsets) (default `:utf-8`).
+* `:resize-listener` - A function to call when the terminal is resized.  This
+  function should take two parameters: the new number of columns, and the new
+  number of rows.
+
+The `:rows`, `:cols`, and `:charset` options are really just a suggestion!
+
+The text-based terminals will ignore rows and columns and will be the size of
+the user's window.
+
+The Swing terminal will start out at this size but can be resized later by the
+user, and will ignore the charset entirely.
+
+God only know what Cygwin will do.
+
+Your application needs to be flexible and handle sizes on the fly.
+
 ### lanterna.terminal/start
 
     :::clojure
 Also moves the cursor one character to the right.
 
 ### lanterna.terminal/put-string
+
+    :::clojure
+    (put-string terminal s)
+
+Draw the string at the current cursor location.
+
+The cursor will end up at the position directly after the string.
+
+    :::clojure
+    (put-string terminal s x y)
+
+Draw the string at the specified cursor location.
+
+The cursor will end up at the position directly after the string.
+
 ### lanterna.terminal/set-fg-color
+
+    :::clojure
+    (set-fg-color terminal color)
+
+Set the foreground color for text drawn by subsequent
+[`put-character`](#lanternaterminalput-character) and
+[`put-string`](#lanternaterminalput-string) calls.
+
+Color is a [color constant](#colors) like `:red`.
+
 ### lanterna.terminal/set-bg-color
+
+    :::clojure
+    (set-bg-color terminal color)
+
+Set the background color for text drawn by subsequent
+[`put-character`](#lanternaterminalput-character) and
+[`put-string`](#lanternaterminalput-string) calls.
+
+Color is a [color constant](#colors) like `:red`.
+
 ### lanterna.terminal/set-style
+
+Broken right now, sorry.
+
 ### lanterna.terminal/remove-style
+
+Broken right now, sorry.
+
 ### lanterna.terminal/reset-styles
+
+Broken right now, sorry.
+
 ### lanterna.terminal/get-key
+
+    :::clojure
+    (get-key terminal)
+
+Get the next keypress from the user, or `nil` if none are buffered.
+
+If there is one or more keystroke buffered, that key will be returned (and
+popped off the buffer of input).  The returned key will be a [key code
+constant](#key-codes).
+
+If there are no keystrokes buffered, `nil` will be returned immediately.
+
+If you want to wait for user input, use
+[`get-key-blocking`](#lanternaterminalget-key-blocking) instead.
+
 ### lanterna.terminal/get-key-blocking
+
+    :::clojure
+    (get-key-blocking terminal)
+
+Get the next keypress from the user.
+
+If there is one or more keystroke buffered, that key will be returned (and
+popped off the buffer of input).  The returned key will be a [key code
+constant](#key-codes).
+
+If there are no keystrokes buffered the function will sleep, checking every 50
+milliseconds for input.  Once there is a character buffered it will be popped
+off and returned as normal.
+
+If you want to return immediately instead of blocking when no input is buffered,
+use [`get-key`](#lanternaterminalget-key) instead.
+
 ### lanterna.terminal/add-resize-listener
 
+    :::clojure
+    (add-resize-listener terminal listener-fn)
+
+Create a listener that will call the supplied function when the terminal is
+resized.
+
+The function must take two arguments: the new number of columns and the new
+number of rows.
+
+You probably don't need this because you can specify a resize listener function
+when you call [`get-terminal`](#lanternaterminalget-terminal).  It's here if you
+*do* need it though.
+
 Screens
 -------
 

docs/index.markdown

 
 [Lanterna]: https://code.google.com/p/lanterna/
 [lanterna-docs]: https://code.google.com/p/lanterna/wiki/DevelopmentGuide
+
+I Want a Hello, World!
+----------------------
+
+Okay, fine:
+
+    :::clojure
+    (require '[lanterna.screen :as s])
+
+    (def scr (s/get-screen))
+
+    (s/stop screen)
+
+    (s/put-string scr 10 10 "Hello, world!")
+    (s/put-string scr 10 11 "Press any key to exit!")
+    (get-key-blocking)
+
+    (s/stop screen)
+
+But really, please read the docs if you actually want to use this.  They're not
+that long.

src/lanterna/terminal.clj

   kind can be one of the following:
 
   :auto   - Try to guess the right type of terminal based on OS, whether
-  there's a windowing environment, etc
+            there's a windowing environment, etc
   :swing  - Force a Swing-based terminal.
   :text   - Force a console (i.e.: non-Swing) terminal.  Try to guess the
-  appropriate kind of console (UNIX/Cygwin) by the OS.
+            appropriate kind of console (UNIX/Cygwin) by the OS.
   :unix   - Force a UNIX console terminal.
   :cygwin - Force a Cygwin console terminal.
 
   Options can contain one or more of the following keys:
 
-  :cols    - Width of the desired terminal in characters. (default 80)
-  :rows    - Height of the desired terminal in characters. (default 24)
-  :charset - Charset of the desired terminal.
-  Can be any of (keys lanterna.constants/charsets).
-  (default :utf-8)
+  :cols    - Width of the desired terminal in characters (default 80).
+  :rows    - Height of the desired terminal in characters (default 24).
+  :charset - Charset of the desired terminal.  Can be any of
+             (keys lanterna.constants/charsets) (default :utf-8).
+  :resize-listener - A function to call when the terminal is resized.  This
+                     function should take two parameters: the new number of
+                     columns, and the new number of rows.
 
   NOTE: The options are really just a suggestion!
 
    (move-cursor terminal x y)
    (put-character terminal ch)))
 
-(defn put-string [terminal s]
-  (dorun (map (partial put-character terminal)
-              s)))
+(defn put-string
+  "Draw the string at the current cursor location.
+
+  If x and y are given, moves the cursor there first.
+
+  The cursor will end up at the position directly after the string.
+
+  "
+  ([terminal s]
+   (dorun (map (partial put-character terminal)
+               s)))
+  ([terminal s x y]
+   (move-cursor terminal x y)
+   (put-string terminal s)))
 
 
 (defn set-fg-color [terminal color]