web analytics
July 13, 2015

Widgets – TextBox

Widgets_Textbox

The TextBox widget is exactly what the name implies: text in a box. It is capable of showing text in a fixed size, in multiple rows, where text is scrollable and selectable. The user can interact with the textbox to change the position of the cursor or caret, as well highlight and select a piece of text. In combination with other widgets, the textbox can be used to store text being inputted by the user.

Usage

To use the textbox, first the bounds and text size must be specified. To set the size to an exact amount of rows and columns, you can make use of the setDimension(cols, rows) method. Below a list of important methods when working with the textbox:

  • setTextSize(sz) – Set the scale of the text
  • showCursor(bool) – Set whether a cursor (caret) is shown and that selections are allowed
  • showScrollbar(bool) – Set whether a vertical scrollbar is shown to the right
  • showBackspace(bool) – Set whether a backspace button is shown to the right
  • setDimension(cols, rows) – Set the bounds to display a given amount of columns and rows
  • setSelection(text) – Insert text at the currently selected position, replacing any selections
  • setMaxLength(len) – Set the maximum amount of characters the textbox can hold
  • setText(text) – Set the text displayed, limited by the maximum length

Example: Show long piece of text

#include "Phoenard.h"

PHN_TextBox textbox; // Define the widget

void setup() {
  // Setup and add the textbox
  textbox.setBounds(10, 10, 150, 220);
  textbox.setTextSize(2);
  textbox.showScrollbar(true);
  textbox.showCursor(false);
  textbox.setMaxLength(500);
  textbox.setText("This is a piece of "
                  "text shown inside "
                  "of a textbox which "
                  "you can scroll up "
                  "and down.\n\n"
                  "This text can include "
                  "newline characters "
                  "as well:\n\n"
                  "Line 1\n"
                  "Line 2\n");
  display.addWidget(textbox);
}

void loop() {
  display.update();
}

 

Example: Entering text from Serial

#include "Phoenard.h"

PHN_TextBox textbox; // Define the widget

void setup() {
  // Initialize Serial
  Serial.begin(9600);
  
  // Setup and add the textbox
  textbox.setBounds(10, 10, 300, 220);
  textbox.setTextSize(2);
  textbox.showScrollbar(true);
  textbox.showCursor(true);
  textbox.setMaxLength(2000);
  display.addWidget(textbox);
}

void loop() {
  display.update();
  
  // Enter text from Serial
  while (Serial.available()) {
    textbox.setSelection(Serial.read());
  }
}

 

Example: Making use of selections

#include "Phoenard.h"

PHN_TextBox textbox; // Define the widget

void setup() {
  // Initialize Serial
  Serial.begin(9600);
  
  // Setup and add the textbox
  textbox.setBounds(10, 10, 300, 220);
  textbox.setTextSize(2);
  textbox.showScrollbar(true);
  textbox.showCursor(true);
  textbox.setMaxLength(100);
  textbox.setText("Hello, world!");
  display.addWidget(textbox);
  
  // Replace the 'world' with 'universe'
  textbox.setSelectionRange(7, 5);
  textbox.setSelection("universe");
}

void loop() {
  display.update();
}

[fbcomments]