mirror of
https://github.com/embarklabs/neo-blessed.git
synced 2025-01-10 19:16:20 +00:00
docs. minor changes.
This commit is contained in:
Christopher Jeffrey
parent
39b7ae7546
commit
6bf8afb357
393
README.md
393
README.md
@ -103,6 +103,399 @@ program.getCursor(function(err, data) {
|
||||
});
|
||||
```
|
||||
|
||||
## High-level Documentation
|
||||
|
||||
### Example
|
||||
|
||||
This will render a box with ascii borders containing the text 'Hello world!',
|
||||
centered horizontally and vertically.
|
||||
|
||||
``` js
|
||||
var blessed = require('blessed')
|
||||
, program = blessed()
|
||||
, screen = new blessed.Screen({ program: program });
|
||||
|
||||
screen.append(new blessed.Box({
|
||||
top: 'center',
|
||||
left: 'center',
|
||||
width: '50%',
|
||||
height: '50%',
|
||||
border: {
|
||||
type: 'ascii',
|
||||
fg: 1
|
||||
},
|
||||
fg: 3,
|
||||
bg: 5,
|
||||
content: 'Hello world!',
|
||||
}));
|
||||
|
||||
screen.on('keypress', function(ch, key) {
|
||||
if (key.name === 'escape') {
|
||||
process.exit(0);
|
||||
}
|
||||
});
|
||||
|
||||
screen.render();
|
||||
```
|
||||
|
||||
### Widgets
|
||||
|
||||
Blessed comes with a number of high-level widgets so you can avoid all the
|
||||
nasty low-level terminal stuff.
|
||||
|
||||
#### Node (from EventEmitter)
|
||||
|
||||
The base node which everything inherits from.
|
||||
|
||||
Options:
|
||||
|
||||
- screen - the screen to be associated with.
|
||||
- parent - the desired parent.
|
||||
- children - an arrray of children.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from EventEmitter.
|
||||
- children - array of node's children.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from EventEmitter.
|
||||
- remove - received when node is removed from it's current parent.
|
||||
- reparent - received when node gains a new parent.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from EventEmitter.
|
||||
- prepend(node) - prepend a node to this node's children.
|
||||
- append(node) - append a node to this node's children.
|
||||
- remove(node) - remove child node from node.
|
||||
- detach() - remove node from its parent.
|
||||
|
||||
#### Screen (from Node)
|
||||
|
||||
The screen on which every other node renders.
|
||||
|
||||
Options:
|
||||
|
||||
- program - the blessed Program to be associated with.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from Node.
|
||||
- program - the blessed Program object.
|
||||
- tput - the blessed Tput object.
|
||||
- focused - top of the focus history stack.
|
||||
- width - width of the screen (same as `program.cols`).
|
||||
- height - height of the screen (same as `program.rows`).
|
||||
- left - left offset, always zero.
|
||||
- right - right offset, always zero.
|
||||
- top - top offset, always zero.
|
||||
- bottom - bottom offset, always zero.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from Node.
|
||||
- mouse - received on mouse events.
|
||||
- keypress - received on key events.
|
||||
- element [name] - global events received for all elements.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from Node.
|
||||
- alloc() - allocate a new pending screen buffer and a new output screen buffer.
|
||||
- draw(start, end) - draw the screen based on the contents of the screen buffer.
|
||||
- render() - render all child elements, writing all data to the screen buffer and drawing the screen.
|
||||
- clearRegion(x1, x2, y1, y2) - clear any region on the screen.
|
||||
- fillRegion(attr, ch, x1, x2, y1, y2) - fill any region with a character of a certain attribute.
|
||||
- focus(offset) - focus element by offset of focusable elements.
|
||||
- focusPrev() - focus previous element in the index.
|
||||
- focusNext() - focus next element in the index.
|
||||
- focusPush(element) - push element on the focus stack (equivalent to `screen.focused = el`).
|
||||
- focusPop()/focusLast() - pop element off the focus stack.
|
||||
|
||||
#### Element (from Node)
|
||||
|
||||
The base element.
|
||||
|
||||
Options:
|
||||
|
||||
- fg, bg, bold, underline - attributes.
|
||||
- border - border object, see below.
|
||||
- content - element's text content.
|
||||
- clickable - element is clickable.
|
||||
- input - element is focusable and can receive key input.
|
||||
- hidden - whether the element is hidden.
|
||||
- label - a simple text label for the element.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from Node.
|
||||
- border - border object.
|
||||
- type - type of border (`ascii` or `bg`). `bg` by default.
|
||||
- ch - character to use if `bg` type, default is space.
|
||||
- bg, fg - border foreground and background, must be numbers (-1 for default).
|
||||
- bold, underline - border attributes.
|
||||
- position - raw width, height, and offsets.
|
||||
- content - text content.
|
||||
- hidden - whether the element is hidden or not.
|
||||
- fg, bg - foreground and background, must be numbers (-1 for default).
|
||||
- bold, underline - attributes.
|
||||
- width - calculated width.
|
||||
- height - calculated height.
|
||||
- left - calculated absolute left offset.
|
||||
- right - calculated absolute right offset.
|
||||
- top - calculated absolute top offset.
|
||||
- bottom - calculated absolute bottom offset.
|
||||
- rleft - calculated relative left offset.
|
||||
- rright - calculated relative right offset.
|
||||
- rtop - calculated relative top offset.
|
||||
- rbottom - calculated relative bottom offset.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from Node.
|
||||
- mouse - received on mouse events for this element.
|
||||
- keypress - received on key events for this element.
|
||||
- move - received when the element is moved.
|
||||
- resize - received when the element is resized.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from Node.
|
||||
- render() - write content and children to the screen buffer.
|
||||
- setContent(text) - set the content.
|
||||
- hide() - hide element.
|
||||
- show() - show element.
|
||||
- toggle() - toggle hidden/shown.
|
||||
- focus() - focus element.
|
||||
|
||||
#### Box (from Element)
|
||||
|
||||
A box element which draws a simple box containing `content` or other elements.
|
||||
|
||||
Inherits all options, properties, events, and methods from Box.
|
||||
|
||||
#### Text (from Element)
|
||||
|
||||
An element similar to Box, but geared towards rendering simple text elements.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from Element.
|
||||
- fill - fill the entire line with chosen bg until parent bg ends, even if
|
||||
there is not enough text to fill the entire width.
|
||||
|
||||
Inherits all options, properties, events, and methods from Element.
|
||||
|
||||
#### Line (from Box)
|
||||
|
||||
A simple line which can be `ascii` or `bg` styled.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from Box.
|
||||
- orientation - can be `vertical` or `horizontal`.
|
||||
- type, bg, fg, ch - treated the same as a border object.
|
||||
|
||||
Inherits all options, properties, events, and methods from Box.
|
||||
|
||||
#### ScrollableBox (from Box)
|
||||
|
||||
A box with scrollable content.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from Box.
|
||||
- baseLimit - a limit to the childBase. default is `Infinity`.
|
||||
- alwaysScroll - a option which causes the ignoring of `childOffset`. this in
|
||||
turn causes the childBase to change every time the element is scrolled.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from Box.
|
||||
- childBase - the offset of the top of the scroll content.
|
||||
- childOffset - the offset of the chosen item (if there is one).
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from Box.
|
||||
- scroll - received when the element is scrolled.
|
||||
|
||||
Methods:
|
||||
|
||||
- scroll(offset) - scroll the content by an offset.
|
||||
|
||||
#### List (from ScrollableBox)
|
||||
|
||||
A scrollable list which can display selectable items.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
- selectFg, selectedBg - foreground and background for selected item, treated
|
||||
like fg and bg.
|
||||
- selectedBold, selectedUnderline - character attributes for selected item,
|
||||
treated like bold and underline.
|
||||
- mouse - whether to automatically enable mouse support for this list (allows
|
||||
clicking items).
|
||||
- items - an array of strings which become the list's items.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
- select - received when an item is selected.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
- add(text) - add an item based on a string.
|
||||
- select(index) - select an index of an item.
|
||||
- move(offset) - select item based on current offset.
|
||||
- up(amount) - select item above selected.
|
||||
- down(amount) - select item below selected.
|
||||
|
||||
#### ScrollableText (from ScrollableBox)
|
||||
|
||||
A scrollable text box which can display and scroll text, as well as handle pre-existing newlines and escape codes.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
- mouse - whether to enable automatic mouse support for this element.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from ScrollableBox.
|
||||
|
||||
#### Input (from Box)
|
||||
|
||||
A form input.
|
||||
|
||||
#### Textbox (from Input)
|
||||
|
||||
A box which allows text input.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from Input.
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from Input.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from Input.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from Input.
|
||||
- setInput(callback) - grab key events and start reading text from the
|
||||
keyboard. takes a callback which receives the final value.
|
||||
- setEditor(callback) - open text editor in $EDITOR, read the output from the
|
||||
resulting file. takes a callback which receives the final value.
|
||||
|
||||
#### ProgressBar (from Input)
|
||||
|
||||
A progress bar allowing various styles.
|
||||
|
||||
Options:
|
||||
|
||||
- inherits all from Input.
|
||||
- barFg, barBg - (completed) bar foreground and background.
|
||||
- ch - the character to fill the bar with (default is space).
|
||||
- filled - the amount filled (0 - 100).
|
||||
|
||||
Properties:
|
||||
|
||||
- inherits all from Input.
|
||||
|
||||
Events:
|
||||
|
||||
- inherits all from Input.
|
||||
- reset - bar was reset.
|
||||
- complete - bar has completely filled.
|
||||
|
||||
Methods:
|
||||
|
||||
- inherits all from Input.
|
||||
- progress(amount) - progress the bar by a fill amount.
|
||||
- reset() - reset the bar.
|
||||
|
||||
### Positioning
|
||||
|
||||
Offsets may be a number, a percentage (e.g. `50%`), or a keyword (e.g.
|
||||
`center`).
|
||||
|
||||
Dimensions may be a number, or a percentage (e.g. `50%`).
|
||||
|
||||
Positions are treated almost *exactly* the same as they are in CSS/CSSOM when
|
||||
an element has the `position: absolute` CSS property.
|
||||
|
||||
When an element is created, it can be given coordinates in its constructor:
|
||||
|
||||
``` js
|
||||
var box = new blessed.Box({
|
||||
left: 'center',
|
||||
top: 'center',
|
||||
bg: 3,
|
||||
width: '50%',
|
||||
height: '50%'
|
||||
});
|
||||
```
|
||||
|
||||
This tells blessed to create a box, perfectly centered **relative to its
|
||||
parent**, 50% as wide and 50% as tall as its parent.
|
||||
|
||||
To access the calculated offsets, relative to the parent:
|
||||
|
||||
``` js
|
||||
console.log(box.rleft);
|
||||
console.log(box.rtop);
|
||||
```
|
||||
|
||||
To access the calculated offsets, absolute (relative to the screen):
|
||||
|
||||
``` js
|
||||
console.log(box.left);
|
||||
console.log(box.top);
|
||||
```
|
||||
|
||||
#### Overlapping offsets and dimensions greater than parents'
|
||||
|
||||
This still needs to be tested a bit, but it should work.
|
||||
|
||||
### Rendering
|
||||
|
||||
To actually render the screen buffer, you must call `render`.
|
||||
|
||||
``` js
|
||||
box.setContent('Hello world.');
|
||||
screen.render();
|
||||
```
|
||||
|
||||
Elements are rendered with the lower elements in the children array being
|
||||
painted first. In terms of the painter's algorithm, the lowest indicies in the
|
||||
array are the furthest away, just like in the DOM.
|
||||
|
||||
### Testing
|
||||
|
||||
- For an interactive test, see `test/widget.js`.
|
||||
- For a less interactive position testing, see `test/widget-pos.js`.
|
||||
|
||||
## License
|
||||
|
||||
Copyright (c) 2013, Christopher Jeffrey. (MIT License)
|
||||
|
||||
@ -1,44 +1,9 @@
|
||||
/**
|
||||
* Blessed high-level interface
|
||||
* Still in development
|
||||
* Copyright (c) 2013, Christopher Jeffrey (MIT License)
|
||||
* Still under heavy development.
|
||||
*/
|
||||
|
||||
/*
|
||||
API Example:
|
||||
This will render a box with ascii borders containing the
|
||||
text 'Hello world!', centered horizontally and vertically.
|
||||
|
||||
var blessed = require('blessed')
|
||||
, program = blessed()
|
||||
, screen;
|
||||
|
||||
screen = new blessed.Screen({
|
||||
program: program
|
||||
});
|
||||
|
||||
screen.append(new blessed.Text({
|
||||
screen: screen,
|
||||
parent: screen,
|
||||
fg: 3,
|
||||
bg: 5,
|
||||
border: {
|
||||
type: 'ascii',
|
||||
fg: 1
|
||||
},
|
||||
content: 'Hello world!',
|
||||
top: 'center',
|
||||
left: 'center'
|
||||
}));
|
||||
|
||||
program.on('keypress', function(ch, key) {
|
||||
if (key.name === 'escape') {
|
||||
process.exit(0);
|
||||
}
|
||||
});
|
||||
|
||||
screen.render();
|
||||
*/
|
||||
|
||||
/**
|
||||
* Modules
|
||||
*/
|
||||
@ -136,10 +101,10 @@ function Screen(options) {
|
||||
this.tput = this.program.tput;
|
||||
this.dattr = ((0 << 18) | (0x1ff << 9)) | 0x1ff;
|
||||
this.position = {
|
||||
left: this.left = 0,
|
||||
right: this.right = 0,
|
||||
top: this.top = 0,
|
||||
bottom: this.bottom = 0
|
||||
left: this.left = this.rleft = 0,
|
||||
right: this.right = this.rright = 0,
|
||||
top: this.top = this.rtop = 0,
|
||||
bottom: this.bottom = this.rbottom = 0
|
||||
};
|
||||
|
||||
//this.focused = null;
|
||||
@ -1270,6 +1235,7 @@ ScrollableBox.prototype.scroll = function(offset) {
|
||||
}
|
||||
if (this.childBase < 0) this.childBase = 0;
|
||||
else if (this.childBase > this.baseLimit) this.childBase = this.baseLimit;
|
||||
this.emit('scroll');
|
||||
};
|
||||
|
||||
/**
|
||||
@ -1315,6 +1281,10 @@ function List(options) {
|
||||
self.screen.render();
|
||||
});
|
||||
}
|
||||
|
||||
// self.on('keypress', function(ch, key) {
|
||||
// if (key.name === 'enter') self.emit('select');
|
||||
// });
|
||||
}
|
||||
|
||||
List.prototype.__proto__ = ScrollableBox.prototype;
|
||||
@ -1528,7 +1498,6 @@ Input.prototype.__proto__ = Box.prototype;
|
||||
|
||||
function Textbox(options) {
|
||||
Input.call(this, options);
|
||||
this.value = options.value || '';
|
||||
this.content = options.content || '';
|
||||
this.screen._listenKeys(this);
|
||||
}
|
||||
@ -1691,9 +1660,13 @@ ProgressBar.prototype.progress = function(filled) {
|
||||
this.filled += filled;
|
||||
if (this.filled < 0) this.filled = 0;
|
||||
else if (this.filled > 100) this.filled = 100;
|
||||
if (this.filled === 100) {
|
||||
this.emit('complete');
|
||||
}
|
||||
};
|
||||
|
||||
ProgressBar.prototype.reset = function() {
|
||||
this.emit('reset');
|
||||
this.filled = 0;
|
||||
};
|
||||
|
||||
|
||||
@ -2,6 +2,10 @@ var blessed = require('blessed')
|
||||
, program = blessed()
|
||||
, assert = require('assert');
|
||||
|
||||
// My terminal size at the time of writing these tests:
|
||||
program.cols = 154;
|
||||
program.rows = 19;
|
||||
|
||||
var screen = new blessed.Screen({
|
||||
program: program
|
||||
});
|
||||
@ -45,10 +49,6 @@ inner.setContent(inner.content + '\n' + JSON.stringify({
|
||||
rbottom: inner.rbottom
|
||||
}));
|
||||
|
||||
// NOTE: With 154 cols.
|
||||
program.cols = 154;
|
||||
program.rows = 19;
|
||||
|
||||
assert.equal(inner.width, 57);
|
||||
assert.equal(inner.height, 7);
|
||||
|
||||
@ -87,6 +87,17 @@ inner.top = inner.bottom = inner.left = inner.right = 5;
|
||||
assert.equal(inner.width, 144);
|
||||
assert.equal(inner.height, 9);
|
||||
|
||||
// Test center keyword
|
||||
reset(inner, {
|
||||
width: '50%',
|
||||
height: '50%',
|
||||
left: 'center',
|
||||
top: 'center'
|
||||
});
|
||||
|
||||
assert.equal(inner.rleft, 29);
|
||||
assert.equal(inner.rtop, 4);
|
||||
|
||||
// TODO: Start storing position.left, etc. as absolute?
|
||||
|
||||
screen.on('keypress', function(ch, key) {
|
||||
@ -98,6 +109,7 @@ screen.on('keypress', function(ch, key) {
|
||||
screen.render();
|
||||
|
||||
function reset(el, pos) {
|
||||
pos = pos || {};
|
||||
el.position.width = el.options.width = pos.width;
|
||||
el.position.height = el.options.height = pos.height;
|
||||
el.position.left = el.options.left = pos.left;
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user