--- a/clojure-lanterna/index.html Sat Jul 07 12:49:56 2012 -0400
+++ b/clojure-lanterna/index.html Sat Jul 07 15:22:58 2012 -0400
@@ -14,6 +14,13 @@
<div class="markdown">
<p>clojure-lanterna is a thin wrapper around the <a href="https://code.google.com/p/lanterna/">Lanterna</a> Java library to make
it more Clojure-friendly.</p>
+<p><strong>It's still pre-1.0, so expect brokenness and backwards incompatibility. Once
+it hits 1.0 you can be confident I'll stop breaking your shit all the time.</strong></p>
+<p><strong>License:</strong> GNU Lesser GPL (yes, you can link with code under another license!)<br />
+<strong>Documentation:</strong> <a href="http://sjl.bitbucket.org/clojure-lanterna/">http://sjl.bitbucket.org/clojure-lanterna/</a><br />
+<strong>Issues:</strong> <a href="http://github.com/sjl/clojure-lanterna/issues/">http://github.com/sjl/clojure-lanterna/issues/</a><br />
+<strong>Git:</strong> <a href="http://github.com/sjl/clojure-lanterna/">http://github.com/sjl/clojure-lanterna/</a><br />
+<strong>Mercurial:</strong> <a href="http://bitbucket.org/sjl/clojure-lanterna/">http://bitbucket.org/sjl/clojure-lanterna/</a></p>
<h2 id="what-is-it">What is It?</h2>
<p><a href="https://code.google.com/p/lanterna/">Lanterna</a> is a Java library for interacting with terminals. It's kind of
like curses, except it's pure Java so it'll run anywhere. It lets you move the
@@ -45,7 +52,25 @@
<p>Have fun! Consult the <a href="./reference/">Reference</a> document if you need more
detailed information about something. Most functions also have docstrings.</p>
</li>
-</ol><h2>Table of Contents</h2><ol class="toc"><li><a href="installation/">Installation</a></li><li><a href="terminals/">Terminals</a></li><li><a href="screens/">Screens</a></li><li><a href="reference/">Reference</a></li></ol>
+</ol>
+<h2 id="i-want-a-hello-world">I Want a Hello, World!</h2>
+<p>Okay, fine:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">require</span> <span class="o">'</span><span class="p">[</span><span class="nv">lanterna.screen</span> <span class="ss">:as</span> <span class="nv">s</span><span class="p">])</span>
+
+<span class="p">(</span><span class="k">def </span><span class="nv">scr</span> <span class="p">(</span><span class="nf">s/get-screen</span><span class="p">))</span>
+
+<span class="p">(</span><span class="nf">s/stop</span> <span class="nv">screen</span><span class="p">)</span>
+
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">10</span> <span class="mi">10</span> <span class="s">"Hello, world!"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">10</span> <span class="mi">11</span> <span class="s">"Press any key to exit!"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">get-key-blocking</span><span class="p">)</span>
+
+<span class="p">(</span><span class="nf">s/stop</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>But really, please read the docs if you actually want to use this. They're not
+that long.</p><h2>Table of Contents</h2><ol class="toc"><li><a href="installation/">Installation</a></li><li><a href="terminals/">Terminals</a></li><li><a href="screens/">Screens</a></li><li><a href="reference/">Reference</a></li></ol>
</div>
<footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.
Documentation created with <a href="http://sjl.bitbucket.org/d/">d</a>.</p>
--- a/clojure-lanterna/reference/index.html Sat Jul 07 12:49:56 2012 -0400
+++ b/clojure-lanterna/reference/index.html Sat Jul 07 15:22:58 2012 -0400
@@ -2,7 +2,400 @@
</script></head><body class="content">
<div class="wrap">
<header><h1><a href="..">clojure-lanterna</a></h1></header><div class="markdown">
-<h1 id="reference"><a href="">Reference</a></h1></div>
+<h1 id="reference"><a href="">Reference</a></h1><p>Here's the deep dive.</p>
+<p>If you haven't read the <a href="../terminals/">terminal</a> and <a href="../screens/">screen</a>
+documentation you should read those to wrap your brain around the structure of
+things first.</p>
+<div class="toc">
+<ul><li><a href="#constants">Constants</a><ul><li><a href="#colors">Colors</a></li>
+<li><a href="#styles">Styles</a></li>
+<li><a href="#key-codes">Key Codes</a></li>
+<li><a href="#charsets">Charsets</a></li>
+<li><a href="#consoles">Consoles</a></li>
+</ul></li>
+<li><a href="#terminals">Terminals</a><ul><li><a href="#lanternaterminalget-terminal">lanterna.terminal/get-terminal</a></li>
+<li><a href="#lanternaterminalstart">lanterna.terminal/start</a></li>
+<li><a href="#lanternaterminalstop">lanterna.terminal/stop</a></li>
+<li><a href="#lanternaterminalin-terminal">lanterna.terminal/in-terminal</a></li>
+<li><a href="#lanternaterminalmove-cursor">lanterna.terminal/move-cursor</a></li>
+<li><a href="#lanternaterminalput-character">lanterna.terminal/put-character</a></li>
+<li><a href="#lanternaterminalput-string">lanterna.terminal/put-string</a></li>
+<li><a href="#lanternaterminalset-fg-color">lanterna.terminal/set-fg-color</a></li>
+<li><a href="#lanternaterminalset-bg-color">lanterna.terminal/set-bg-color</a></li>
+<li><a href="#lanternaterminalset-style">lanterna.terminal/set-style</a></li>
+<li><a href="#lanternaterminalremove-style">lanterna.terminal/remove-style</a></li>
+<li><a href="#lanternaterminalreset-styles">lanterna.terminal/reset-styles</a></li>
+<li><a href="#lanternaterminalget-key">lanterna.terminal/get-key</a></li>
+<li><a href="#lanternaterminalget-key-blocking">lanterna.terminal/get-key-blocking</a></li>
+<li><a href="#lanternaterminaladd-resize-listener">lanterna.terminal/add-resize-listener</a></li>
+</ul></li>
+<li><a href="#screens">Screens</a><ul><li><a href="#lanternascreenget-screen">lanterna.screen/get-screen</a></li>
+<li><a href="#lanternascreenstart">lanterna.screen/start</a></li>
+<li><a href="#lanternascreenstop">lanterna.screen/stop</a></li>
+<li><a href="#lanternascreenin-screen">lanterna.screen/in-screen</a></li>
+<li><a href="#lanternascreenredraw">lanterna.screen/redraw</a></li>
+<li><a href="#lanternascreenmove-cursor">lanterna.screen/move-cursor</a></li>
+<li><a href="#lanternascreenput-string">lanterna.screen/put-string</a></li>
+<li><a href="#lanternascreenget-key">lanterna.screen/get-key</a></li>
+<li><a href="#lanternascreenget-key-blocking">lanterna.screen/get-key-blocking</a></li>
+<li><a href="#lanternascreenadd-resize-listener">lanterna.screen/add-resize-listener</a></li>
+</ul></li>
+</ul></div>
+<h2 id="constants">Constants</h2>
+<p>clojure-lanterna uses Clojure keywords where you need to supply constants. It
+will handle the filthy details of converting them to the appropriate Java enum
+elements when needed so you don't need to worry about it.</p>
+<h3 id="colors">Colors</h3>
+<p>Lanterna (and thus clojure-lanterna) supports the 8 common terminal colors, as
+well as a "default" color:</p>
+<ul><li><code>:black</code></li>
+<li><code>:white</code></li>
+<li><code>:red</code></li>
+<li><code>:green</code></li>
+<li><code>:blue</code></li>
+<li><code>:cyan</code></li>
+<li><code>:magenta</code></li>
+<li><code>:yellow</code></li>
+<li><code>:default</code></li>
+</ul><h3 id="styles">Styles</h3>
+<p>Lanterna (and thus clojure-lanterna) supports 4 common styles:</p>
+<ul><li><code>:bold</code></li>
+<li><code>:reverse</code></li>
+<li><code>:underline</code></li>
+<li><code>:blinking</code></li>
+</ul><h3 id="key-codes">Key Codes</h3>
+<p>When you get a key of user input from clojure-lanterna it will be one of two
+things: a Character like <code>\a</code> or <code>\$</code> representing what the user typed, or
+a keyword for special keys like Delete or Page Up.</p>
+<p>Note that the Tab key is returned as <code>:tab</code> and not <code>\tab</code>.</p>
+<p>Here are the keywords for special keys that may be returned:</p>
+<ul><li><code>:escape</code></li>
+<li><code>:backspace</code></li>
+<li><code>:left</code></li>
+<li><code>:right</code></li>
+<li><code>:up</code></li>
+<li><code>:down</code></li>
+<li><code>:insert</code></li>
+<li><code>:delete</code></li>
+<li><code>:home</code></li>
+<li><code>:end</code></li>
+<li><code>:page-up</code></li>
+<li><code>:page-down</code></li>
+<li><code>:tab</code></li>
+<li><code>:reverse-tab</code></li>
+<li><code>:enter</code></li>
+</ul><p>There are also two other special keywords:</p>
+<ul><li><code>:unknown</code> - The user typed something Lanterna couldn't figure out.</li>
+<li><code>:cursor-location</code> - I'm not sure about this. I think it's an internal
+ Lanterna thing.</li>
+</ul><h3 id="charsets">Charsets</h3>
+<p>Currently there's only one charset clojure-lanterna constant defines. Open an
+issue as a feature request if you want others -- I'll be happy to add the
+constants.</p>
+<ul><li><code>:utf-8</code></li>
+</ul><h3 id="consoles">Consoles</h3>
+<p>When creating a Terminal or Screen, you can optionally specify a specific kind
+of Terminal or Screen to create.</p>
+<p>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 <code>:auto</code>.</p>
+<ul><li><code>:auto</code> - 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.</li>
+<li><code>:swing</code> - Force a Swing-based console.</li>
+<li><code>:text</code> - 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.</li>
+<li><code>:unix</code> - Force a UNIX text-based console.</li>
+<li><code>:cygwin</code> - Force a Cygwin text-based console.</li>
+</ul><h2 id="terminals">Terminals</h2>
+<p>The terminal layer is the lowest-level layer. Read the <a href="../terminals/">terminal
+documentation</a> for an overview.</p>
+<h3 id="lanternaterminalget-terminal">lanterna.terminal/get-terminal</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-terminal</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">get-terminal</span> <span class="nv">kind</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">get-terminal</span> <span class="nv">kind</span> <span class="nv">options</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get a terminal object.</p>
+<p><code>kind</code> is a <a href="#consoles">console constant</a> describing the type of terminal you
+want. If unspecified it defaults to <code>:auto</code>.</p>
+<p>The <code>options</code> map can contain any of the following mappings:</p>
+<ul><li><code>:cols</code> - Width of the desired terminal in characters (default <code>80</code>).</li>
+<li><code>:rows</code> - Height of the desired terminal in characters (default <code>24</code>).</li>
+<li><code>:charset</code> - Charset of the desired terminal. This should be a <a href="#charsets">charset
+ constant</a> (default <code>:utf-8</code>).</li>
+<li><code>:resize-listener</code> - 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.</li>
+</ul><p>The <code>:rows</code>, <code>:cols</code>, and <code>:charset</code> options are really just a suggestion!</p>
+<p>The text-based terminals will ignore rows and columns and will be the size of
+the user's window.</p>
+<p>The Swing terminal will start out at this size but can be resized later by the
+user, and will ignore the charset entirely.</p>
+<p>God only know what Cygwin will do.</p>
+<p>Your application needs to be flexible and handle sizes on the fly.</p>
+<h3 id="lanternaterminalstart">lanterna.terminal/start</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">start</span> <span class="nv">terminal</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Start the given terminal. Terminals must be started before they can be used.</p>
+<p>Consider using <a href="#lanternaterminalin-terminal"><code>in-terminal</code></a> instead if you
+don't need detailed control of the starting and stopping.</p>
+<h3 id="lanternaterminalstop">lanterna.terminal/stop</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">stop</span> <span class="nv">terminal</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Stop the given terminal. Terminals must be stopped after you're done with them,
+otherwise you risk corrupting the user's console.</p>
+<p>Don't try to do anything to the Terminal after you stop it.</p>
+<p>I'm not sure if you can "restart" a terminal once it's been stopped. TODO: Find
+out.</p>
+<p>Consider using <a href="#lanternaterminalin-terminal"><code>in-terminal</code></a> instead if you
+don't need detailed control of the starting and stopping.</p>
+<h3 id="lanternaterminalin-terminal">lanterna.terminal/in-terminal</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">in-terminal</span> <span class="nv">terminal</span> <span class="o">&</span> <span class="nv">body</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Start the given terminal, perform the body of expressions, and stop the terminal
+afterward.</p>
+<p>This is a macro.</p>
+<p>The stopping will be done in a try/finally block, so you can be confident it
+will actually happen.</p>
+<p>Use this if you don't need detailed control of the terminal starting and
+stopping process.</p>
+<h3 id="lanternaterminalmove-cursor">lanterna.terminal/move-cursor</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">move-cursor</span> <span class="nv">terminal</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Move the cursor to a specific location on the screen.</p>
+<h3 id="lanternaterminalput-character">lanterna.terminal/put-character</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">put-character</span> <span class="nv">terminal</span> <span class="nv">ch</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Draw the character at the current cursor location.</p>
+<p>Also moves the cursor one character to the right, so a sequence of calls will
+output next to each other.</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">put-character</span> <span class="nv">terminal</span> <span class="nv">ch</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Draw the character at the specified cursor location.</p>
+<p>Also moves the cursor one character to the right.</p>
+<h3 id="lanternaterminalput-string">lanterna.terminal/put-string</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">put-string</span> <span class="nv">terminal</span> <span class="nv">s</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Draw the string at the current cursor location.</p>
+<p>The cursor will end up at the position directly after the string.</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">put-string</span> <span class="nv">terminal</span> <span class="nv">s</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Draw the string at the specified cursor location.</p>
+<p>The cursor will end up at the position directly after the string.</p>
+<h3 id="lanternaterminalset-fg-color">lanterna.terminal/set-fg-color</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">set-fg-color</span> <span class="nv">terminal</span> <span class="nv">color</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Set the foreground color for text drawn by subsequent
+<a href="#lanternaterminalput-character"><code>put-character</code></a> and
+<a href="#lanternaterminalput-string"><code>put-string</code></a> calls.</p>
+<p>Color is a <a href="#colors">color constant</a> like <code>:red</code>.</p>
+<h3 id="lanternaterminalset-bg-color">lanterna.terminal/set-bg-color</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">set-bg-color</span> <span class="nv">terminal</span> <span class="nv">color</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Set the background color for text drawn by subsequent
+<a href="#lanternaterminalput-character"><code>put-character</code></a> and
+<a href="#lanternaterminalput-string"><code>put-string</code></a> calls.</p>
+<p>Color is a <a href="#colors">color constant</a> like <code>:red</code>.</p>
+<h3 id="lanternaterminalset-style">lanterna.terminal/set-style</h3>
+<p>Broken right now, sorry.</p>
+<h3 id="lanternaterminalremove-style">lanterna.terminal/remove-style</h3>
+<p>Broken right now, sorry.</p>
+<h3 id="lanternaterminalreset-styles">lanterna.terminal/reset-styles</h3>
+<p>Broken right now, sorry.</p>
+<h3 id="lanternaterminalget-key">lanterna.terminal/get-key</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-key</span> <span class="nv">terminal</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get the next keypress from the user, or <code>nil</code> if none are buffered.</p>
+<p>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 <a href="#key-codes">key code
+constant</a>.</p>
+<p>If there are no keystrokes buffered, <code>nil</code> will be returned immediately.</p>
+<p>If you want to wait for user input, use
+<a href="#lanternaterminalget-key-blocking"><code>get-key-blocking</code></a> instead.</p>
+<h3 id="lanternaterminalget-key-blocking">lanterna.terminal/get-key-blocking</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-key-blocking</span> <span class="nv">terminal</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get the next keypress from the user.</p>
+<p>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 <a href="#key-codes">key code
+constant</a>.</p>
+<p>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.</p>
+<p>If you want to return immediately instead of blocking when no input is buffered,
+use <a href="#lanternaterminalget-key"><code>get-key</code></a> instead.</p>
+<h3 id="lanternaterminaladd-resize-listener">lanterna.terminal/add-resize-listener</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">add-resize-listener</span> <span class="nv">terminal</span> <span class="nv">listener-fn</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Create a listener that will call the supplied function when the terminal is
+resized.</p>
+<p>The function must take two arguments: the new number of columns and the new
+number of rows.</p>
+<p>You probably don't need this because you can specify a resize listener function
+when you call <a href="#lanternaterminalget-terminal"><code>get-terminal</code></a>. It's here if you
+<em>do</em> need it though.</p>
+<h2 id="screens">Screens</h2>
+<p>The screen layer is an abstraction that provides buffering on top of the
+terminal layer. Read the <a href="../screens/">screen documentation</a> for an overview.</p>
+<h3 id="lanternascreenget-screen">lanterna.screen/get-screen</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-screen</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">get-screen</span> <span class="nv">kind</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">get-screen</span> <span class="nv">kind</span> <span class="nv">options</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get a screen object.</p>
+<p><code>kind</code> is a <a href="#consoles">console constant</a> describing the type of screen you
+want. If unspecified it defaults to <code>:auto</code>.</p>
+<p>The <code>options</code> map can contain any of the following mappings:</p>
+<ul><li><code>:cols</code> - Width of the desired screen in characters (default <code>80</code>).</li>
+<li><code>:rows</code> - Height of the desired screen in characters (default <code>24</code>).</li>
+<li><code>:charset</code> - Charset of the desired screen. This should be a <a href="#charsets">charset
+ constant</a> (default <code>:utf-8</code>).</li>
+<li><code>:resize-listener</code> - A function to call when the screen is resized. This
+ function should take two parameters: the new number of columns, and the new
+ number of rows.</li>
+</ul><p>The <code>:rows</code>, <code>:cols</code>, and <code>:charset</code> options are really just a suggestion!</p>
+<p>The text-based screens will ignore rows and columns and will be the size of
+the user's window.</p>
+<p>The Swing screen will start out at this size but can be resized later by the
+user, and will ignore the charset entirely.</p>
+<p>God only know what Cygwin will do.</p>
+<p>Your application needs to be flexible and handle sizes on the fly.</p>
+<h3 id="lanternascreenstart">lanterna.screen/start</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">start</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Start the given screen. Screens must be started before they can be used.</p>
+<p>Consider using <a href="#lanternascreenin-screen"><code>in-screen</code></a> instead if you don't need
+detailed control of the starting and stopping.</p>
+<h3 id="lanternascreenstop">lanterna.screen/stop</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">stop</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Stop the given screen. Screens must be stopped after you're done with them,
+otherwise you risk corrupting the user's console.</p>
+<p>Don't try to do anything to the screen after you stop it.</p>
+<p>I'm not sure if you can "restart" a screen once it's been stopped. TODO: Find
+out.</p>
+<p>Consider using <a href="#lanternascreenin-screen"><code>in-screen</code></a> instead if you don't need
+detailed control of the starting and stopping.</p>
+<h3 id="lanternascreenin-screen">lanterna.screen/in-screen</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">in-screen</span> <span class="nv">screen</span> <span class="o">&</span> <span class="nv">body</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Start the given screen, perform the body of expressions, and stop the screen
+afterward.</p>
+<p>This is a macro.</p>
+<p>The stopping will be done in a try/finally block, so you can be confident it
+will actually happen.</p>
+<p>Use this if you don't need detailed control of the screen starting and stopping
+process.</p>
+<h3 id="lanternascreenredraw">lanterna.screen/redraw</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">redraw</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Redraw the given screen.</p>
+<p>This is how you actually flush any changes to the user's display.</p>
+<h3 id="lanternascreenmove-cursor">lanterna.screen/move-cursor</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">move-cursor</span> <span class="nv">terminal</span> <span class="nv">x</span> <span class="nv">y</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Move the cursor to a specific location on the screen.</p>
+<p>You'll need to <a href="#lanternascreenredraw"><code>redraw</code></a> the screen to actually see it
+happen.</p>
+<p>The cursor will stay where you move it, even if you later draw some text in
+a different place and redraw. If you want it to move, you need to call this
+function again.</p>
+<h3 id="lanternascreenput-string">lanterna.screen/put-string</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">put-string</span> <span class="nv">screen</span> <span class="nv">x</span> <span class="nv">y</span> <span class="nv">s</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">put-string</span> <span class="nv">screen</span> <span class="nv">x</span> <span class="nv">y</span> <span class="nv">s</span> <span class="nv">options</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Put a string on the screen buffer, ready to be drawn at the next
+<a href="#lanternascreenredraw"><code>redraw</code></a>.</p>
+<p><code>x</code> and <code>y</code> are the column and row to start the string.</p>
+<p><code>s</code> is the actual string to draw.</p>
+<p>The <code>options</code> map can contain any of the following mappings:</p>
+<ul><li><code>:fg</code> - Foreground color of the text. Must be a <a href="#colors">color constant</a>
+ (default <code>:default</code>).</li>
+<li><code>:bg</code> - Background color of the text. Must be a <a href="#colors">color constant</a>
+ (default <code>:default</code>).</li>
+<li><code>:styles</code> - Styles to apply to the text. Must be a set containing zero or
+ more <a href="#styles">style constants</a> (default <code>#{}</code>). <strong>CURRENTLY BROKEN, SORRY</strong></li>
+</ul><h3 id="lanternascreenget-key">lanterna.screen/get-key</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-key</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get the next keypress from the user, or <code>nil</code> if none are buffered.</p>
+<p>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 <a href="#key-codes">key code
+constant</a>.</p>
+<p>If there are no keystrokes buffered, <code>nil</code> will be returned immediately.</p>
+<p>If you want to wait for user input, use
+<a href="#lanternascreenget-key-blocking"><code>get-key-blocking</code></a> instead.</p>
+<h3 id="lanternascreenget-key-blocking">lanterna.screen/get-key-blocking</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">get-key-blocking</span> <span class="nv">screen</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Get the next keypress from the user.</p>
+<p>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 <a href="#key-codes">key code
+constant</a>.</p>
+<p>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.</p>
+<p>If you want to return immediately instead of blocking when no input is buffered,
+use <a href="#lanternascreenget-key"><code>get-key</code></a> instead.</p>
+<h3 id="lanternascreenadd-resize-listener">lanterna.screen/add-resize-listener</h3>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">add-resize-listener</span> <span class="nv">screen</span> <span class="nv">listener-fn</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Create a listener that will call the supplied function when the screen is
+resized.</p>
+<p>The function must take two arguments: the new number of columns and the new
+number of rows.</p>
+<p>You probably don't need this because you can specify a resize listener function
+when you call <a href="#lanternascreenget-screen"><code>get-screen</code></a>. It's here if you <em>do</em>
+need it though.</p>
+ </div>
<footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.
Documentation created with <a href="http://sjl.bitbucket.org/d/">d</a>.</p>
<p><br/><a id="rochester-made" href="http://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p>
--- a/clojure-lanterna/screens/index.html Sat Jul 07 12:49:56 2012 -0400
+++ b/clojure-lanterna/screens/index.html Sat Jul 07 15:22:58 2012 -0400
@@ -2,7 +2,158 @@
</script></head><body class="content">
<div class="wrap">
<header><h1><a href="..">clojure-lanterna</a></h1></header><div class="markdown">
-<h1 id="screens"><a href="">Screens</a></h1></div>
+<h1 id="screens"><a href="">Screens</a></h1><p>The next layer of Lanterna is the screen layer. Think of screens as "<a href="https://en.wikipedia.org/wiki/Multiple_buffering#Double_buffering_in_computer_graphics">double
+buffering</a> for your console".</p>
+<p>Screens act as a buffer. You "draw" to the screen like you would normally draw
+directly to the terminal, but it doesn't appear to the user.</p>
+<p>When you're ready you tell the Screen to redraw. It will calculate the
+necessary changes and make them happen.</p>
+<p>This improves performance (TODO: elaborate) and makes it easy to avoid
+showing half-drawn UIs to your users.</p>
+<p>clojure-lantera's screen API is <em>very</em> similar to the terminal one. <strong>If you
+haven't read the <a href="../terminals/">Terminal documentation</a> you need to do that
+before you read this.</strong> This document moves very quickly because it assumes
+you've read the previous one.</p>
+<div class="toc">
+<ul><li><a href="#getting-a-screen">Getting a Screen</a></li>
+<li><a href="#writing-text">Writing Text</a><ul><li><a href="#colors">Colors</a></li>
+<li><a href="#styles">Styles</a></li>
+</ul></li>
+<li><a href="#moving-the-cursor">Moving the Cursor</a></li>
+<li><a href="#input">Input</a></li>
+<li><a href="#resizing">Resizing</a></li>
+<li><a href="#whats-next">What's Next?</a></li>
+</ul></div>
+<h2 id="getting-a-screen">Getting a Screen</h2>
+<p>Let's get started. Open up a REPL and pull in the namespace:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">require</span> <span class="o">'</span><span class="p">[</span><span class="nv">lanterna.screen</span> <span class="ss">:as</span> <span class="nv">s</span><span class="p">])</span>
+</pre></div>
+
+
+<p>Much like getting a Terminal, you get a Screen with <code>get-screen</code>:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="k">def </span><span class="nv">scr</span> <span class="p">(</span><span class="nf">s/get-screen</span> <span class="ss">:swing</span><span class="p">))</span>
+</pre></div>
+
+
+<p><code>get-screen</code> supports all the same types of console as <code>get-terminal</code>.</p>
+<p>You need to <code>start</code> and <code>stop</code> a Screen before/after use just like a Terminal:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/start</span> <span class="nv">scr</span><span class="p">)</span>
+<span class="c1">; ... do things ...</span>
+<span class="p">(</span><span class="nf">s/stop</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p>There's an <code>in-screen</code> helper too:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="k">let </span><span class="p">[</span><span class="nv">scr</span> <span class="p">(</span><span class="nf">s/get-screen</span> <span class="ss">:swing</span><span class="p">)]</span>
+ <span class="p">(</span><span class="nf">in-screen</span> <span class="nv">scr</span>
+ <span class="c1">; do things with scr</span>
+ <span class="p">))</span>
+</pre></div>
+
+
+<h2 id="writing-text">Writing Text</h2>
+<p>The screen layer uses a single function to draw to the screen: <code>put-string</code>.
+There is no single-character function like the terminal layer has.</p>
+<p><code>put-string</code> works like its Terminal counterpart:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">0</span> <span class="mi">0</span> <span class="s">"Hello, world!"</span><span class="p">)</span>
+</pre></div>
+
+
+<p>When you run this, nothing will happen. This is because Screens buffer their
+output. You need to redraw the screen to see any changes:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/redraw</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p><img alt="Screen" src="http://i.imgur.com/79Qr1.png"/></p>
+<p>You can of course queue up many updates before redrawing -- that's the whole
+point of a screen!</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">20</span> <span class="mi">10</span> <span class="s">"Hello, world!"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">27</span> <span class="mi">10</span> <span class="s">"Steve"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/redraw</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p><img alt="Screen with More" src="http://i.imgur.com/tLm16.png"/></p>
+<p>This will display "Hello, Steve!", which demonstrates that you can overwrite
+a single character as much as you want before a redraw and the correct result
+will be shown.</p>
+<p>Note that because we haven't touched the upper-left corner in this redraw our
+original "Hello, world!" is still there. Screens redraw <em>changes</em>, they don't
+start from scratch every time.</p>
+<p>If you want to remove old text you'll need to clear it out yourself by drawing
+over it with spaces.</p>
+<p>TODO: add a <code>clear-screen</code> function to make this suck less.</p>
+<h3 id="colors">Colors</h3>
+<p>Drawing colored text works a bit differently than the Terminal layer. Instead
+of specifying a color once and then everything you draw being that color, you
+specify the color in an option map alongside the string to draw:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">0</span> <span class="mi">12</span> <span class="s">"Red"</span> <span class="p">{</span><span class="ss">:fg</span> <span class="ss">:red</span><span class="p">})</span>
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">0</span> <span class="mi">13</span> <span class="s">"Green"</span> <span class="p">{</span><span class="ss">:fg</span> <span class="ss">:green</span><span class="p">})</span>
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">0</span> <span class="mi">14</span> <span class="s">"Yellow"</span> <span class="p">{</span><span class="ss">:fg</span> <span class="ss">:black</span> <span class="ss">:bg</span> <span class="ss">:yellow</span><span class="p">})</span>
+<span class="p">(</span><span class="nf">s/redraw</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p><img alt="Screen with Colors" src="http://i.imgur.com/uC1qk.png"/></p>
+<h3 id="styles">Styles</h3>
+<p>Currently broken, sorry.</p>
+<h2 id="moving-the-cursor">Moving the Cursor</h2>
+<p>Just like the terminal layer, you might want to move the cursor when using
+a Screen.</p>
+<p>There's a <code>move-cursor</code> function that works like the terminal one to do this:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">5</span> <span class="mi">5</span> <span class="s">"@"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/move-cursor</span> <span class="nv">scr</span> <span class="mi">5</span> <span class="mi">5</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/redraw</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p><img alt="Screen with Cursor Moved" src="http://i.imgur.com/gQ2FO.png"/></p>
+<p>Notice that you have to redraw the screen before the cursor will actually move.</p>
+<p>The cursor will stay where you put it, even after other updating and redraws:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">5</span> <span class="mi">5</span> <span class="s">" "</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/put-string</span> <span class="nv">scr</span> <span class="mi">6</span> <span class="mi">5</span> <span class="s">"@"</span><span class="p">)</span>
+<span class="p">(</span><span class="nf">s/redraw</span> <span class="nv">scr</span><span class="p">)</span>
+</pre></div>
+
+
+<p><img alt="Screen with Cursor Unmoved" src="http://i.imgur.com/XTd1I.png"/></p>
+<p>See how the cursor is still in the original spot (5, 5)? If you want it to move
+you need to tell it to move with <code>move-cursor</code>.</p>
+<h2 id="input">Input</h2>
+<p>Getting input works exactly like the terminal layer:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="nf">s/get-key</span> <span class="nv">scr</span><span class="p">)</span>
+<span class="c1">; => nil</span>
+
+<span class="p">(</span><span class="nf">s/get-key-blocking</span> <span class="nv">scr</span><span class="p">)</span>
+<span class="c1">; => :page-down</span>
+
+<span class="p">(</span><span class="nf">s/get-key</span> <span class="nv">scr</span><span class="p">)</span>
+<span class="c1">; => \S</span>
+</pre></div>
+
+
+<p>Go back and read the terminal docs if you don't understand those functions.</p>
+<h2 id="resizing">Resizing</h2>
+<p>Resizing works the same way as the terminal layer. Pass a resize listening
+function when you create your screen:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="k">def </span><span class="nv">screen-size</span> <span class="p">(</span><span class="nb">ref </span><span class="p">[</span><span class="mi">0</span> <span class="mi">0</span><span class="p">]))</span>
+
+<span class="p">(</span><span class="kd">defn </span><span class="nv">handle-resize</span> <span class="p">[</span><span class="nv">cols</span> <span class="nv">rows</span><span class="p">]</span>
+ <span class="p">(</span><span class="nb">dosync </span><span class="p">(</span><span class="nb">ref-set </span><span class="nv">screen-size</span> <span class="p">[</span><span class="nv">cols</span> <span class="nv">rows</span><span class="p">])))</span>
+
+<span class="p">(</span><span class="k">def </span><span class="nv">scr</span> <span class="p">(</span><span class="nf">s/get-screen</span> <span class="ss">:swing</span> <span class="p">{</span><span class="ss">:resize-listener</span> <span class="nv">handle-resize</span><span class="p">}))</span>
+</pre></div>
+
+
+<p>Go back and read the terminal docs for the full story.</p>
+<h2 id="whats-next">What's Next?</h2>
+<p>Now that you can use the screen layer for double-buffered console rendering
+you've got pretty much everything you need. Go make something!</p>
+<p>The <a href="../reference/">Reference documentation</a> has all the detailed information
+you'll probably find yourself looking for once you actually dive in and start
+building.</p>
+ </div>
<footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.
Documentation created with <a href="http://sjl.bitbucket.org/d/">d</a>.</p>
<p><br/><a id="rochester-made" href="http://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p>
--- a/clojure-lanterna/terminals/index.html Sat Jul 07 12:49:56 2012 -0400
+++ b/clojure-lanterna/terminals/index.html Sat Jul 07 15:22:58 2012 -0400
@@ -5,6 +5,16 @@
<h1 id="terminals"><a href="">Terminals</a></h1><p>The lowest layer of Lanterna (and thus clojure-lanterna) is a Terminal.</p>
<p>You can use terminals to do the stuff you normally think of using a curses
library for.</p>
+<div class="toc">
+<ul><li><a href="#getting-a-terminal">Getting a Terminal</a></li>
+<li><a href="#writing-text">Writing Text</a></li>
+<li><a href="#moving-the-cursor">Moving the Cursor</a></li>
+<li><a href="#colors">Colors</a></li>
+<li><a href="#styles">Styles</a></li>
+<li><a href="#input">Input</a></li>
+<li><a href="#resizing">Resizing</a></li>
+<li><a href="#whats-next">What's Next?</a></li>
+</ul></div>
<h2 id="getting-a-terminal">Getting a Terminal</h2>
<p>Let's try it out. Open up a REPL and pull in the namespace:</p>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">require</span> <span class="o">'</span><span class="p">[</span><span class="nv">lanterna.terminal</span> <span class="ss">:as</span> <span class="nv">t</span><span class="p">])</span>
@@ -132,8 +142,12 @@
</pre></div>
-<p>Normal alphanumeric keys are returned as simple Character objects. Special keys
-are returned as Clojure keywords like <code>:enter</code>, <code>:page-up</code>, and <code>backspace</code>.</p>
+<p>Normal alphanumeric keys are returned as simple Character objects like <code>\a</code>.</p>
+<p>Note that there's no special attribute to determine if the Shift key was
+pressed, but the Characters will be the correct ones. For example, if the user
+presses "Shift-a" the Character you get will be <code>\A</code> instead of <code>\a</code>.</p>
+<p>Special keys are returned as Clojure keywords like <code>:enter</code>, <code>:page-up</code>, and
+<code>:backspace</code>.</p>
<p>You can get a full list of the supported special keys by peeking in Lanterna's
constants namespace (or just consult the reference documentation):</p>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">require</span> <span class="o">'</span><span class="p">[</span><span class="nv">lanterna.constants</span> <span class="ss">:as</span> <span class="nv">c</span><span class="p">])</span>
@@ -207,7 +221,7 @@
<h2 id="whats-next">What's Next?</h2>
<p>Now that you've covered all of the major concepts of Lanterna's terminal layer,
-it's time to move on to the next layer: screens.</p>
+it's time to move on to the next layer: <a href="../screens/">screens</a>.</p>
</div>
<footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.
Documentation created with <a href="http://sjl.bitbucket.org/d/">d</a>.</p>