fix linux console clear. better debug window to test/widget.js. complete widget docs.

README.md

@@ -932,7 +932,8 @@ A radio button which can be used in a form element.
 
 #### Prompt (from Box)
 
-A prompt box containing a text input, okay, and cancel buttons.
+A prompt box containing a text input, okay, and cancel buttons (automatically
+hidden).
 
 ##### Options:
 
@@ -949,11 +950,13 @@ A prompt box containing a text input, okay, and cancel buttons.
 ##### Methods:
 
 - inherits all from Box.
+- __input/setInput/readInput(callback)__ - show the prompt and wait for the
+  result of the textbox.
 
 
 #### Question (from Box)
 
-A question box containing okay and cancel buttons.
+A question box containing okay and cancel buttons (automatically hidden).
 
 ##### Options:
 
@@ -970,11 +973,13 @@ A question box containing okay and cancel buttons.
 ##### Methods:
 
 - inherits all from Box.
+- __ask(question, callback)__ - ask a `question`. `callback` will yield the
+  result.
 
 
 #### Message (from Box)
 
-A box containing a message to be displayed.
+A box containing a message to be displayed (automatically hidden).
 
 ##### Options:
 
@@ -991,11 +996,15 @@ A box containing a message to be displayed.
 ##### Methods:
 
 - inherits all from Box.
+- __log/display(text, [time], callback)__ - display a message for a time
+  (default is 3 seconds). set time to 0 for a perpetual message that is
+  dismissed on keypress.
+- __error(text, [time], callback)__ - display an error in the same way.
 
 
 #### Loading (from Box)
 
-A box with a spinning line to denote loading.
+A box with a spinning line to denote loading (automatically hidden).
 
 ##### Options:
 
@@ -1012,6 +1021,9 @@ A box with a spinning line to denote loading.
 ##### Methods:
 
 - inherits all from Box.
+- __load(text)__ - display the loading box with a message. will lock keys until
+  `stop` is called.
+- __stop()__ - hide loading box. unlock keys.
 
 
 #### Listbar (from Box)
@@ -1023,6 +1035,9 @@ A horizontal list. Useful for a main menu bar.
 - inherits all from Box.
 - __style.selected__ - style for a selected item.
 - __style.item__ - style for an unselected item.
+- __commands/items__ - set buttons using an object with keys as titles of
+  buttons, containing of objects containing keys of `keys` and `callback`.
+- __autoCommandKeys__ - automatically bind list buttons to keys 0-9.
 
 ##### Properties:
 
@@ -1035,6 +1050,14 @@ A horizontal list. Useful for a main menu bar.
 ##### Methods:
 
 - inherits all from Box.
+- __setItems(commands)__ - set commands (see `commands` option above).
+- __add/addItem/appendItem(item, callback)__ - append an item to the bar.
+- __select(offset)__ - select an item on the bar.
+- __removeItem(child)__ - remove item from the bar.
+- __move(offset)__ - move relatively across the bar.
+- __moveLeft(offset)__ - move left relatively across the bar.
+- __moveRight(offset)__ - move right relatively across the bar.
+- __selectTab(index)__ - select button and execute its callback.
 
 
 #### Log (from ScrollableText)

lib/widget.js

@@ -443,10 +443,11 @@ Screen.prototype.enter = function() {
       this.cursorColor(this.cursor.color);
     }
   }
+  // this.program.put.smcup();
   this.program.alternateBuffer();
   this.program.hideCursor();
   this.program.cup(0, 0);
-  //this.program.csr(0, this.height - 1);
+  // this.program.csr(0, this.height - 1);
   this.alloc();
 };
 
@@ -456,12 +457,14 @@ Screen.prototype.leave = function() {
       || this.program.scrollBottom !== this.rows - 1) {
     this.program.csr(0, this.height - 1);
   }
-  // this.program.clear();
-  this.alloc();
+  // XXX For some reason if alloc/clear() is before this
+  // line, it doesn't work on linux console.
   this.program.showCursor();
+  this.alloc();
   if (this._listenedMouse) {
     this.program.disableMouse();
   }
+  // this.program.put.rmcup();
   this.program.normalBuffer();
   if (this.cursor._set) this.cursorReset();
   this.program.flush();

test/tail.js

@@ -0,0 +1,70 @@
+// `tail -f` a file.
+module.exports = function(file) {
+  var self = this
+    , fs = require('fs')
+    , StringDecoder = require('string_decoder').StringDecoder
+    , decode = new StringDecoder('utf8')
+    , buffer = new Buffer(64 * 1024)
+    , Stream = require('stream').Stream
+    , s = new Stream
+    , buff = ''
+    , pos = 0;
+
+  s.readable = true;
+  s.destroy = function() {
+    s.destroyed = true;
+    s.emit('end');
+    s.emit('close');
+  };
+
+  fs.open(file, 'a+', 0644, function(err, fd) {
+    if (err) {
+      s.emit('error', err);
+      s.destroy();
+      return;
+    }
+
+    (function read() {
+      if (s.destroyed) {
+        fs.close(fd);
+        return;
+      }
+
+      return fs.read(fd, buffer, 0, buffer.length, pos, function(err, bytes) {
+        if (err) {
+          s.emit('error', err);
+          s.destroy();
+          return;
+        }
+
+        if (!bytes) {
+          if (buff) {
+            stream.emit('line', buff);
+            buff = '';
+          }
+          return setTimeout(read, 1000);
+        }
+
+        var data = decode.write(buffer.slice(0, bytes));
+
+        s.emit('data', data);
+
+        var data = (buff + data).split(/\n+/)
+          , l = data.length - 1
+          , i = 0;
+
+        for (; i < l; i++) {
+          s.emit('line', data[i]);
+        }
+
+        buff = data[l];
+
+        pos += bytes;
+
+        return read();
+      });
+    })();
+  });
+
+  return s;
+};

test/widget.js

@@ -14,7 +14,12 @@ screen = blessed.screen({
   debug: true
 });
 
-screen.debug('test');
+screen._debugLog.parseTags = true;
+
+require('./tail')(__dirname + '/logs/widget.log').on('line', function(line) {
+  if (!screen._debugLog.hidden) return;
+  screen.debug(line);
+});
 
 screen.append(blessed.text({
   top: 0,