blessed

Element (from Node)

The base element.

Options:

• fg, bg, bold, underline - Attributes.
• style - May contain attributes in the format of:

  {
    fg: 'blue',
    bg: 'black',
    border: {
      fg: 'blue'
    },
    scrollbar: {
      bg: 'blue'
    },
    focus: {
      bg: 'red'
    },
    hover: {
      bg: 'red'
    }
  }
  

• border - Border object, see below.
• content - Element’s text content.
• clickable - Element is clickable.
• input, keyable - Element is focusable and can receive key input.
• focused - Element is focused.
• hidden - Whether the element is hidden.
• label - A simple text label for the element.
• hoverText - A floating text label for the element which appears on mouseover.
• align - Text alignment: left, center, or right.
• valign - Vertical text alignment: top, middle, or bottom.
• shrink - Shrink/flex/grow to content and child elements. Width/height during render.
• padding - Amount of padding on the inside of the element. Can be a number or an object containing the properties: left, right, top, and bottom.
• width, height - Width/height of the element, can be a number, percentage (0-100%), or keyword (half or shrink). Percentages can also have offsets (50%+1, 50%-1).
• left, right, top, bottom - Offsets of the element relative to its parent. Can be a number, percentage (0-100%), or keyword (center). right and bottom do not accept keywords. Percentages can also have offsets (50%+1, 50%-1).
• position - Can contain the above options.
• scrollable - Whether the element is scrollable or not.
• ch - Background character (default is whitespace ` `).
• draggable - Allow the element to be dragged with the mouse.
• shadow - Draw a translucent offset shadow behind the element.

Properties:

• Inherits all from Node.
• name - Name of the element. Useful for form submission.
• border - Border object.
  • type - Type of border (line 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.
• style - Contains attributes (e.g. fg/bg/underline). See above.
• position - Raw width, height, and offsets.
• content - Raw text content.
• hidden - Whether the element is hidden or not.
• visible - Whether the element is visible or not.
• detached - Whether the element is attached to a screen in its ancestry somewhere.
• fg, bg - Foreground and background, must be numbers (-1 for default).
• bold, underline - Attributes.
• width - Calculated width.
• height - Calculated height.
• left - Calculated relative left offset.
• right - Calculated relative right offset.
• top - Calculated relative top offset.
• bottom - Calculated relative bottom offset.
• aleft - Calculated absolute left offset.
• aright - Calculated absolute right offset.
• atop - Calculated absolute top offset.
• abottom - Calculated absolute bottom offset.
• draggable - Whether the element is draggable. Set to true to allow dragging.

Events:

• Inherits all from Node.
• blur, focus - Received when an element is focused or unfocused.
• mouse - Received on mouse events for this element.
  • mousedown, mouseup - Mouse button was pressed or released.
  • wheeldown, wheelup - Wheel was scrolled down or up.
  • mouseover, mouseout - Element was hovered or unhovered.
  • mousemove - Mouse was moved somewhere on this element.
  • click - Element was clicked (slightly smarter than mouseup).
• keypress - Received on key events for this element.
• move - Received when the element is moved.
• resize - Received when the element is resized.
• key [name] - Received on key event for [name].
• prerender - Received before a call to render.
• render - Received after a call to render.
• hide - Received when element becomes hidden.
• show - Received when element is shown.
• destroy - Received when element is destroyed.

Methods:

• Inherits all from Node.
• Note: If the scrollable option is enabled, Element inherits all methods from ScrollableBox.
• render() - Write content and children to the screen buffer.
• hide() - Hide element.
• show() - Show element.
• toggle() - Toggle hidden/shown.
• focus() - Focus element.
• key(name, listener) - Bind a keypress listener for a specific key.
• onceKey(name, listener) - Bind a keypress listener for a specific key once.
• unkey(name, listener) - Remove a keypress listener for a specific key.
• onScreenEvent(type, handler) - Same asel.on('screen', ...) except this will automatically keep track of which listeners are bound to the screen object. For use with removeScreenEvent(), free(), and destroy().
• removeScreenEvent(type, handler) - Same asel.removeListener('screen', ...) except this will automatically keep track of which listeners are bound to the screen object. For use with onScreenEvent(), free(), and destroy().
• free() - Free up the element. Automatically unbind all events that may have been bound to the screen object. This prevents memory leaks. For use with onScreenEvent(), removeScreenEvent(), and destroy().
• destroy() - Same as the detach() method, except this will automatically call free() and unbind any screen events to prevent memory leaks. for use with onScreenEvent(), removeScreenEvent(), and free().
• setIndex(z) - Set the z-index of the element (changes rendering order).
• setFront() - Put the element in front of its siblings.
• setBack() - Put the element in back of its siblings.
• setLabel(text/options) - Set the label text for the top-left corner. Example options: {text:'foo',side:'left'}
• removeLabel() - Remove the label completely.
• setHover(text/options) - Set a hover text box to follow the cursor. Similar to the “title” DOM attribute in the browser. Example options: {text:'foo'}
• removeHover() - Remove the hover label completely.
• enableMouse() - Enable mouse events for the element (automatically called when a form of on(‘mouse’) is bound).
• enableKeys() - Enable keypress events for the element (automatically called when a form of on(‘keypress’) is bound).
• enableInput() - Enable key and mouse events. Calls bot enableMouse and enableKeys.
• enableDrag() - Enable dragging of the element.
• disableDrag() - Disable dragging of the element.
• screenshot([xi, xl, yi, yl]) - Take an SGR screenshot of the element within the region. Returns a string containing only characters and SGR codes. Can be displayed by simply echoing it in a terminal.

Content Methods

Methods for dealing with text content, line by line. Useful for writing a text editor, irc client, etc.

Note: All of these methods deal with pre-aligned, pre-wrapped text. If you use deleteTop() on a box with a wrapped line at the top, it may remove 3-4 “real” lines (rows) depending on how long the original line was.

The lines parameter can be a string or an array of strings. The line parameter must be a string.

• setContent(text) - Set the content. Note: When text is input, it will be stripped of all non-SGR escape codes, tabs will be replaced with 8 spaces, and tags will be replaced with SGR codes (if enabled).
• getContent() - Return content, slightly different from el.content. Assume the above formatting.
• setText(text) - Similar to setContent, but ignore tags and remove escape codes.
• getText() - Similar to getContent, but return content with tags and escape codes removed.
• insertLine(i, lines) - Insert a line into the box’s content.
• deleteLine(i) - Delete a line from the box’s content.
• getLine(i) - Get a line from the box’s content.
• getBaseLine(i) - Get a line from the box’s content from the visible top.
• setLine(i, line) - Set a line in the box’s content.
• setBaseLine(i, line) - Set a line in the box’s content from the visible top.
• clearLine(i) - Clear a line from the box’s content.
• clearBaseLine(i) - Clear a line from the box’s content from the visible top.
• insertTop(lines) - Insert a line at the top of the box.
• insertBottom(lines) - Insert a line at the bottom of the box.
• deleteTop() - Delete a line at the top of the box.
• deleteBottom() - Delete a line at the bottom of the box.
• unshiftLine(lines) - Unshift a line onto the top of the content.
• shiftLine(i) - Shift a line off the top of the content.
• pushLine(lines) - Push a line onto the bottom of the content.
• popLine(i) - Pop a line off the bottom of the content.
• getLines() - An array containing the content lines.
• getScreenLines() - An array containing the lines as they are displayed on the screen.
• strWidth(text) - Get a string’s displayed width, taking into account double-width, surrogate pairs, combining characters, tags, and SGR escape codes.