Skip to content

Latest commit

 

History

History
222 lines (135 loc) · 7.75 KB

TextBox.md

File metadata and controls

222 lines (135 loc) · 7.75 KB

TextBox

A textBox is box area containing a text. The text can have attributes (colors, styles), it can be wrapped (line-wrapping, word-wrapping), the whole textBox can be scrollable (both horizontal and vertical). The text content source may have markup or ansi code (if so, the contentHasMarkup option should be set accordingly, see below).

When scrollable, it is sensible to mouse-wheel (anywhere) and click on the scrollbar. It supports text-selection, and copy to clipboard (Linux only at the moment, it needs xclipboard).

It is backed by a TextBuffer.

Table of Contents

Events

key

See Element's key event.

Key Bindings

  • tinyScrollUp: scroll up a bit, default: UP
  • tinyScrollDown: scroll down a bit, default: DOWN
  • scrollUp: scroll up, default: PAGE_UP
  • scrollDown: scroll down, default: PAGE_DOWN, space
  • scrollTop: scroll to the top, default: HOME
  • scrollBottom: scroll to the bottom, default: END
  • scrollLeft: scroll left, default: LEFT
  • scrollRight: scroll right, default: RIGHT
  • copyClipboard: copy to clipboard, default: CTRL_Y

new TextBox( options )

  • options Object, where:
    • all the base class Element constructor's options
    • contentHasMarkup boolean or string when set to true or the string 'markup', the content contains Terminal Kit's markup, used to set attributes of parts of the content, when set to the string 'ansi', the content contains ANSI escape sequence, default: false.
    • attr object general attribute for the textBox
    • textAttr object attribute for the text content, default to { bgColor: 'default' }
    • altTextAttr object alternate attribute for the text, default to textAttr + { color: 'gray' , italic: true }
    • voidAttr object attribute for the area of the textBox without any text content, default to { bgColor: 'default' }
    • emptyAttr object alias of voidAttr
    • scrollable boolean if set, the textBox is scrollable (default: false)
    • hasHScrollBar boolean if set and if scrollable, the textBox has a horizontal scrollbar
    • hasVScrollBar boolean if set and if scrollable, the textBox has a vertical scrollbar
    • scrollX number the initial horizontal scroll value, default: 0
    • scrollY number the initial vertical scroll value, default: 0
    • extraScrolling boolean if unset (the default), it is possible to scroll down until both the content bottom and textBox bottom are on the same line, if set, it is possible to scroll down until the bottom of the content reaches the top of the textBox
    • tabWidth number (default: 4) number of cells (=spaces) for the tab character
    • lineWrap boolean when set, the text content is wrapped to the next line instead of being clipped by the textBox border
    • wordWrap boolean like lineWrap but is word-aware, i.e. it doesn't split words
    • firstLineRightShift number if set (default: 0) , the first-line of content is right-shifted from this amount of cells, may be useful for prompt, or continuing another box in the flow
    • hiddenContent string or null, if set, the content is hidden, using this string as a replacement for all chars (useful for password)
    • stateMachine object (TODOC)

This creates a TextBox element.

.setSizeAndPosition( options )

This set the size and position of the textBox, updating line-wrapping and scrollbar.

.scrollTo( x , y )

  • x, y number the new scrolling coordinates

This scrolls the textBox to the x,y coordinates and updates scrollbars.

.scroll( dx , dy )

  • dx, dy number the delta of the scroll

This scrolls the textBox from this x,y delta and updates scrollbars.

.scrollToTop()

This scrolls the textBox to the top and updates scrollbars.

.scrollToBottom()

This scrolls the textBox to the bottom and updates scrollbars.

.getContent()

It returns the current text-content.

.getContentSize()

It returns the current text-content size, an object with a width and height property.

.prependContent( content , [dontDraw] )

  • content string the text-content to prepend
  • dontDraw boolean if set, don't outerDraw the widget (default: false, outerDraw)

Prepend text-content at the begining of the current content. It supports markup or ansi if the textBox was instanciated with the contentHasMarkup options on.

.appendContent( content , [dontDraw] )

  • content string the text-content to append
  • dontDraw boolean if set, don't outerDraw the widget (default: false, outerDraw)

Append text-content at the end of the current content. It supports markup or ansi if the textBox was instanciated with the contentHasMarkup options on.

.appendLog( content , [dontDraw] )

  • content string the text-content to append
  • dontDraw boolean if set, don't outerDraw the widget (default: false, outerDraw)

This method is almost like .appendContent(), but more suitable for logging. It appends a new line of text-content at the end of the current content. Then it performs an intelligent scroll of the textBox: if the scrolling was already at the bottom, it will scroll down so that new content will be in the viewport. It supports markup or ansi if the textBox was instanciated with the contentHasMarkup options on.

.getAltContent()

It returns the alternate text-content.

.setAltContent( content , [hasMarkup] , [dontDraw] )

  • content string the alternate text-content
  • hasMarkup boolean or string when set to true or the string 'markup', the content contains Terminal Kit's markup, used to set attributes of parts of the content, when set to the string 'ansi', the content contains ANSI escape sequence, default: false.
  • dontDraw boolean if set, don't outerDraw the widget (default: false, outerDraw)

It set the alternate text-content, work like its .setContent() counterpart.

.textBuffer

This property holds the underlying TextBuffer object. It can be used to achieve more complex stuffs.