textbuffer.md

The TextBuffer

A textBuffer is a buffer holding text contents that can be used for things like text areas, or even text editors.

A textBuffer is way more flexible than a raw screenBuffer for that purpose. Nonetheless, a textBuffer is always backed by a screenBuffer, i.e. its dst (destination) should be a screenBuffer.

Internally, it has 3 buffers:

• a buffer holding raw text (line of text): raw text buffer
• a buffer holding attributes (colors, styles): the attr buffer
• a misc buffer holding userland data, useful for your application: the misc buffer

It comes with a lot of facilities to interact with the text, to manage the cursor, to colorize the text, to manage tabs...

Note: The TextBuffer is still in beta, some methods are missing but the existing API should be stable or remain backward compatible. If you wonder what can be done with textBuffers, have a look to Neon, a small text-editor in early alpha stage, featuring a javascript syntax hilighter.

Table of Contents

• Constructor and static methods:

  • TextBuffer()
  • TextBuffer.create()

• Properties:

  • .x
  • .y

• Methods:

  • .getText()
  • .setText()
  • .getHidden()
  • .setHidden()
  • .getContentSize()
  • .setEmptyCellAttr()
  • .setAttrAt()
  • .setAttrCodeAt()
  • .setAttrRegion()
  • .setAttrCodeRegion()
  • .getMisc()
  • .getMiscAt()
  • .moveTo()
  • .moveToColumn()
  • .moveToLine(), .moveToRow()
  • .move()
  • .moveUp()
  • .moveDown()
  • .moveLeft()
  • .moveRight()
  • .moveForward()
  • .moveBackward()
  • .moveToEndOfLine()
  • .moveInBound()
  • .insert()
  • .delete()
  • .backDelete()
  • .newLine()
  • .joinLine()
  • .iterate()
  • .draw()
  • .drawCursor()
  • .load()
  • .save()

new TextBuffer( options )

• options Object, where:
  • dst: ScreenBuffer the destination to write on
  • width integer (optional, default: Infinity) width, i.e. max-length of a line
  • height integer (optional, default: Infinity) height, i.e. maximum number of lines
  • x: integer (optional) default x-position in the dst
  • y: integer (optional) default y-position in the dst
  • tabWidth: integer (optional, default: 4) set the tabulation width
  • forceInBound: integer (optional, default: false) if true, the cursor cannot move out of bounds
  • hidden: boolean (optional, default: false) if true, the text is invisible
  • wrap: boolean (optional, default: false) set the wrapping behavior

This creates a TextBuffer instance with the appropriate options.

TextBuffer.create( options )

DEPRECATED, use new TextBuffer() instead.

.x , .y

Those properties are respectively the x and the y coordinate, in the dst (destination), where the textBuffer should be drawn. This can be overriden when invoking .draw().

.getText()

It extracts and returns the text content of the textBuffer.

.setText( text )

• text string the text content

This set the text content of the textBuffer.

It reset both the attr buffer and the misc buffer.

.getHidden()

It returns true if the textBuffer is in hidden mode.

.setHidden( state )

• state boolean if true, it enables the hidden mode, else it disables it

It set on or off the hidden mode. The hidden mode is useful if your textBuffer is holding things like password.

.getContentSize()

It returns an object with a width and height properties: the size of the text content.

.setEmptyCellAttr( attr )

• attr Object or integer attributes of the chars (attribute object or bit flags, see: the attribute object)

This set the attributes for empty cells, i.e. cells in the screenBuffer where there is no textBuffer content (not even spaces).

.setAttrAt( attr , x , y )

• attr Object or integer attributes of the char (attribute object or bit flags, see: the attribute object)
• x integer the x-coordinate (i.e. the column number)
• y integer the y-coordinate (i.e. the row number)

This set the attributes for the textBuffer cell at (x,y) coordinates.

.setAttrCodeAt( attr , x , y )

• attr integer attributes of the char in the bit flags form
• x integer the x-coordinate (i.e. the column number)
• y integer the y-coordinate (i.e. the row number)

Like .setAttrAt(), but it only accepts attributes in the bit flags form (faster).

.setAttrRegion( attr , [region] )

• attr Object or integer attributes of the char (attribute object or bit flags, see: the attribute object)
• region Object (optional, default to the whole textBuffer) the targeted rectangular region, where:
  • xmin integer the minimal x-coordinate
  • xmax integer the maximal x-coordinate
  • ymin integer the minimal y-coordinate
  • ymax integer the maximal y-coordinate

This set the attributes for the textBuffer cells in the rectangular region (if specified), or all cells of the textBuffer.

.setAttrCodeRegion( attr , [region] )

• attr integer attributes of the char in the bit flags form
• region Object (optional, default to the whole textBuffer) the targeted rectangular region, where:
  • xmin integer the minimal x-coordinate
  • xmax integer the maximal x-coordinate
  • ymin integer the minimal y-coordinate
  • ymax integer the maximal y-coordinate

Like .setAttrRegion(), but it only accepts attributes in the bit flags form (faster).

.getMisc()

Get the misc meta data at the current cursor position.

.getMiscAt( x , y )

• x integer the x-coordinate (i.e. the column number)
• y integer the y-coordinate (i.e. the row number)

Get the misc meta data at the (x,y) coordinates.

.moveTo( x , y )

• x integer the x-coordinate (i.e. the column number)
• y integer the y-coordinate (i.e. the row number)

It moves the textBuffer's cursor to the (x,y) coordinates.

.moveToColumn( x )

• x integer the x-coordinate (i.e. the column number)

It moves the textBuffer's cursor to the xth column.

.moveToLine( y ) , .moveToRow( y )

• y integer the y-coordinate (i.e. the row number)

It moves the textBuffer's cursor to the yth row/line.

.move( x , y )

• x integer the relative x-coordinate (i.e. the column number)
• y integer the relative y-coordinate (i.e. the row number)

Like .moveTo(), but it moves the textBuffer's cursor relative to its current position.

.moveUp()

It moves the textBuffer's cursor one cell up.

.moveDown()

It moves the textBuffer's cursor one cell down.

.moveLeft()

It moves the textBuffer's cursor one cell left.

.moveRight()

It moves the textBuffer's cursor one cell right.

.moveForward( justSkipNullCells )

• justSkipNullCells boolean

It moves the textBuffer's cursor one character forward, different form .moveRight(), since it would move the cursor at the begining of the next line if it was on the last character of a line.

It always skips null cells. Null cells are produced by tabulation: there is only one text character but followed by n null cells that are not part of the actual text content.

If justSkipNullCells is set, it does not move forward unless the cursor is over a null cell.

.moveBackward( justSkipNullCells )

• justSkipNullCells boolean

It moves the textBuffer's cursor one character backward, different form .moveLeft(), since it would move the cursor at the end of the previous line if it was on the first character of a line.

It always skips null cells. Null cells are produced by tabulation: there is only one text character but followed by n null cells that are not part of the actual text content.

If justSkipNullCells is set, it does not move backward unless the cursor is over a null cell.

.moveToEndOfLine()

It moves the textBuffer's cursor to the end of the current line.

.moveInBound( ignoreCx )

• ignoreCx boolean do not affect the cursor's x-coordinate

It moves the textBuffer's cursor in bound, i.e. to a cell that has text content.

.insert( text , [attr] )

• text string the raw text to insert
• attr Object or integer (optional, default: the empty cell attributes) attributes of the text about to be inserted (attribute object or bit flags, see: the attribute object)

It inserts the text at the current cursor position, with the given attributes.

.delete( [n] )

• n integer (optional, default: 1) the number of chars to delete

It deletes n characters at the current cursor position. This is the action usually bound to the delete key.

.backDelete( [n] )

• n integer (optional, default: 1) the number of chars to delete

It deletes n characters backward starting from the current cursor position. This is the action usually bound to the backspace key.

.newLine()

It inserts a new line at the current cursor position. It will split the current line in two, if there are characters at/after the current cursor position.

.joinLine()

It moves the cursor to the end of the line and joins the current line with the following line.

.iterate( options , callback )

• options Object where:
  • finalCall boolean call the callback one more time at the end of the buffer with an empty string
• callback Function( cellData ), where:
  • cellData Object where:
    • offset integer the offset/position of the current cell in the raw/serialized text
    • x integer the x-coordinate (i.e. the column number) of the current cell
    • y integer the y-coordinate (i.e. the row number) of the current cell
    • text string a single character string, the character of the current cell
    • attr integer the attributes of the current cell in the bit flags mode, use ScreenBuffer.attr2object() to convert it if necessary
    • misc Object userland meta-data for the current cell

It iterates over the whole textBuffer, using the callback for each cell.

.draw( [options] )

• options Object (optional) if provided, each defined option will override the default behavior. Available options are:
  • dst ScreenBuffer (optional) override textBuffer.dst
  • x integer (optional) override textBuffer.x
  • y integer (optional) override textBuffer.y
  • srcClipRect Rect (optional, default: the whole source region is used) the source clipping rectangle
  • dstClipRect Rect (optional, default: the whole destination region is used) the destination clipping rectangle
  • blending boolean (optional, default: false) if true blending (transparencies) is allowed
  • wrap boolean or string (optional, default: false) if set, wrapping will be enabled, it can be set to:
    • 'x': only wrap along the x-axis
    • 'y': only wrap along the y-axis
    • true, 'both': wrap along the x and y axis
    • false: no wrapping
  • tile boolean (optional, default: false) if true, the source will fill the destination entirely using tiling: the source is repeated multiple times along the x and y axis.

This draws the current textBuffer into its dst (destination), which is a ScreenBuffer instance.

To actually display a textBuffer, you need to:

• draw the textBuffer to a screenBuffer
• then draw that screenBuffer to the terminal (or draw the whole screenBuffer chain until the terminal)

.drawCursor( [options] )

• options Object (optional) if provided, each defined option will override the default behavior. Available options are:
  • dst ScreenBuffer (optional) override textBuffer.dst

This draws the current textBuffer's cursor into its dst (destination), which is a ScreenBuffer instance. Drawing the cursor means that the destination's cursor is moved to the coordinate of the source's cursor. It updates the cursor position so the user know where he is typing.

.load( filepath , callback )

• filepath string the path of the file to load
• callback Function( error ) completion callback

This erases all contents (text, attr and misc) and loads the content of the file (which is a text file).

.save( filepath , callback )

• filepath string the path of the file to save into
• callback Function( error ) completion callback

This saves the raw text content into a file.