# WoopsiUI::MultiLineTextBox Class Reference

`#include <multilinetextbox.h>`

Inheritance diagram for WoopsiUI::MultiLineTextBox:

List of all members.

## Public Types
enum | TextAlignmentHoriz { TEXT_ALIGNMENT_HORIZ_CENTRE = 0, TEXT_ALIGNMENT_HORIZ_LEFT = 1, TEXT_ALIGNMENT_HORIZ_RIGHT = 2 }
enum | TextAlignmentVert { TEXT_ALIGNMENT_VERT_CENTRE = 0, TEXT_ALIGNMENT_VERT_TOP = 1, TEXT_ALIGNMENT_VERT_BOTTOM = 2 }
## Public Member Functions
| MultiLineTextBox (s16 x, s16 y, u16 width, u16 height, const WoopsiString &text, u32 flags, s16 maxRows=0, GadgetStyle *style=NULL)
virtual void | setTextAlignmentHoriz (TextAlignmentHoriz alignment)
virtual void | setTextAlignmentVert (TextAlignmentVert alignment)
virtual const u16 | getPageCount () const
virtual const u16 | getCurrentPage () const
virtual const Text * | getText () const
virtual void | setText (const WoopsiString &text)
virtual void | appendText (const WoopsiString &text)
virtual void | removeText (const u32 startIndex)
virtual void | removeText (const u32 startIndex, const u32 count)
virtual void | setFont (FontBase *font)
virtual const u32 | getTextLength () const
virtual void | showCursor ()
virtual void | hideCursor ()
virtual void | moveCursorToPosition (const s32 position)
virtual const s32 | getCursorPosition () const
virtual void | insertText (const WoopsiString &text, const u32 index)
virtual void | insertTextAtCursor (const WoopsiString &text)
virtual void | handleKeyboardPressEvent (const KeyboardEventArgs &e)
virtual void | handleKeyboardRepeatEvent (const KeyboardEventArgs &e)
bool | opensKeyboard () const
void | disableKeyboardPopup ()
void | enableKeyboardPopup ()
## Protected Member Functions
virtual void | getCursorCoordinates (s16 &x, s16 &y) const
virtual u32 | getCharIndexAtCoordinate (s16 x, s32 rowIndex) const
virtual u32 | getCharIndexAtCoordinates (s16 x, s16 y) const
s32 | getRowContainingCoordinate (s16 y) const
virtual void | drawContents (GraphicsPort *port)
virtual void | drawBorder (GraphicsPort *port)
virtual void | moveCursorLeft ()
virtual void | moveCursorRight ()
virtual void | moveCursorUp ()
virtual void | moveCursorDown ()
virtual bool | cullTopLines ()
virtual void | limitCanvasHeight ()
virtual void | limitCanvasY ()
void | jumpToCursor ()
void | jumpToTextBottom ()
virtual void | onResize (u16 width, u16 height)
virtual void | onClick (s16 x, s16 y)
virtual void | onDoubleClick (s16 x, s16 y)
virtual void | onKeyPress (KeyCode keyCode)
virtual void | onKeyRepeat (KeyCode keyCode)
void | processPhysicalKey (KeyCode keyCode)
virtual void | processKey (const WoopsiKey *key)
u8 | getRowX (s32 row) const
s16 | getRowY (s32 row) const
u32 | getCursorCodePoint () const
void | calculateVisibleRows ()
void | drawText (GraphicsPort *port)
void | drawCursor (GraphicsPort *port)
void | drawRow (GraphicsPort *port, s32 row)
virtual | ~MultiLineTextBox ()
| MultiLineTextBox (const MultiLineTextBox &multiLineTextBox)
## Protected Attributes
Text * | _text
u8 | _visibleRows
s16 | _maxRows
u32 | _topRow
TextAlignmentHoriz | _hAlignment
TextAlignmentVert | _vAlignment
s32 | _cursorPos
bool | _showCursor
bool | _opensKeyboard

## Detailed Description

Textbox that offers multiple lines of text. Has scrolling capability and can be dragged using the stylus. The text it contains can be changed or added to. It can remember more rows of text than it can display, and these additional rows can be scrolled through.

## Member Enumeration Documentation

enum WoopsiUI::MultiLineTextBox::TextAlignmentHoriz

Enum of horizontal alignment options.

Enumerator:

  TEXT_ALIGNMENT_HORIZ_CENTRE | Centre the text
  TEXT_ALIGNMENT_HORIZ_LEFT | Align left
  TEXT_ALIGNMENT_HORIZ_RIGHT | Align right

enum WoopsiUI::MultiLineTextBox::TextAlignmentVert

Enum of vertical alignment options.

Enumerator:

  TEXT_ALIGNMENT_VERT_CENTRE | Align to centre of textbox
  TEXT_ALIGNMENT_VERT_TOP | Align to top of textbox
  TEXT_ALIGNMENT_VERT_BOTTOM | Align to bottom of textbox

## Constructor & Destructor Documentation

WoopsiUI::MultiLineTextBox::MultiLineTextBox | ( | s16 | x,
|  | s16 | y,
|  | u16 | width,
|  | u16 | height,
|  | const WoopsiString & | text,
|  | u32 | flags,
|  | s16 | maxRows = `0`,
|  | GadgetStyle * | style = `NULL` |
| ) |  |  |

Constructor.

Parameters:

  | x | The x co-ordinate of the text box, relative to its parent.
  | y | The y co-ordinate of the text box, relative to its parent.
  | width | The width of the textbox.
  | height | The height of the textbox.
  | text | Pointer to a string to display in the textbox.
  | flags | Standard gadget flag options.
  | maxRows | The maximum number of rows the textbox can track. Adding text beyond this number will cause rows at the start of the text to be forgotten; text is essentially stored as a queue, and adding to the back of a full queue causes the front items to be popped off. Setting this to 0 will make the textbox track only the visible rows.
  | style | The style that the gadget should use. If this is not specified, the gadget will use the values stored in the global defaultGadgetStyle object. The gadget will copy the properties of the style into its own internal style object.

virtual WoopsiUI::MultiLineTextBox::~MultiLineTextBox | ( |  | ) | `[inline, protected, virtual]`

Destructor.

WoopsiUI::MultiLineTextBox::MultiLineTextBox | ( | const MultiLineTextBox & | multiLineTextBox | ) | `[inline, protected]`

Copy constructor is protected to prevent usage.

## Member Function Documentation

virtual void WoopsiUI::MultiLineTextBox::appendText | ( | const WoopsiString & | text | ) | `[virtual]`

Append new text to the end of the current text displayed in the textbox.

Parameters:

  | text | String to append.

Implements WoopsiUI::TextBoxBase.

void WoopsiUI::MultiLineTextBox::calculateVisibleRows | ( |  | ) | `[protected]`

Works out the number of visible rows within the textbox.

virtual bool WoopsiUI::MultiLineTextBox::cullTopLines | ( |  | ) | `[protected, virtual]`

Ensures that the textbox only contains the maximum allowed number of rows by culling any excess rows from the top of the text.

Returns:
  True if lines were removed from the text; false if not.

void WoopsiUI::MultiLineTextBox::disableKeyboardPopup | ( |  | ) | `[inline, virtual]`

Disables the keyboard popup when double-clicked.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::drawBorder | ( | GraphicsPort * | port | ) | `[protected, virtual]`

Draw the area of this gadget that falls within the clipping region. Called by the redraw() function to draw all visible regions.

Parameters:

  | port | The GraphicsPort to draw to.

See also:
  redraw()

Reimplemented from WoopsiUI::ScrollingPanel.

virtual void WoopsiUI::MultiLineTextBox::drawContents | ( | GraphicsPort * | port | ) | `[protected, virtual]`

Draw the area of this gadget that falls within the clipping region. Called by the redraw() function to draw all visible regions.

Parameters:

  | port | The GraphicsPort to draw to.

See also:
  redraw()

Reimplemented from WoopsiUI::ScrollingPanel.

void WoopsiUI::MultiLineTextBox::drawCursor | ( | GraphicsPort * | port | ) | `[protected]`

Draws the cursor.

Parameters:

  | port | The GraphicsPort to draw to.

void WoopsiUI::MultiLineTextBox::drawRow | ( | GraphicsPort * | port,
|  | s32 | row |
| ) |  |  | `[protected]`

Draws a single line of text.

Parameters:

  | port | The GraphicsPort to draw to.
  | row | The index of the row to draw.

void WoopsiUI::MultiLineTextBox::drawText | ( | GraphicsPort * | port | ) | `[protected]`

Draws text.

Parameters:

  | port | The GraphicsPort to draw to.

void WoopsiUI::MultiLineTextBox::enableKeyboardPopup | ( |  | ) | `[inline, virtual]`

Enables the keyboard popup when double-clicked.

Implements WoopsiUI::TextBoxBase.

virtual u32 WoopsiUI::MultiLineTextBox::getCharIndexAtCoordinate | ( | s16 | x,
|  | s32 | rowIndex |
| ) |  |  | const`[protected, virtual]`

Gets the index of the character at the specified x co-ordinate in the specified row.

Parameters:

  | x | X co-ordinate of the character.
  | rowIndex | Index of the row containing the character.

Returns:
  The index of the character at the specified co-ordinate.

virtual u32 WoopsiUI::MultiLineTextBox::getCharIndexAtCoordinates | ( | s16 | x,
|  | s16 | y |
| ) |  |  | const`[protected, virtual]`

Get the index of the character at the specified co-ordinates.

Parameters:

  | x | X co-ordinate of the character.
  | y | Y co-ordinate of the character.

Returns:
  The index of the character at the specified co-ordinates.

virtual const u16 WoopsiUI::MultiLineTextBox::getCurrentPage | ( |  | ) | const`[virtual]`

Returns the current page.

Returns:
  The current page.

See also:
  getPageCount().

u32 WoopsiUI::MultiLineTextBox::getCursorCodePoint | ( |  | ) | const`[protected]`

Gets the character under the cursor.

Returns:
  The character under the cursor.

virtual void WoopsiUI::MultiLineTextBox::getCursorCoordinates | ( | s16 & | x,
|  | s16 & | y |
| ) |  |  | const`[protected, virtual]`

Get the co-ordinates of the cursor relative to the text.

Parameters:

  | x | Will be populated with the x co-ordinate of the cursor.
  | y | Will be populated with the y co-ordinate of the cursor.

virtual const s32 WoopsiUI::MultiLineTextBox::getCursorPosition | ( |  | ) | const`[inline, virtual]`

Get the cursor position. This is the index within the string that the cursor is currently positioned over.

Returns:
  position The cursor position.

Implements WoopsiUI::TextBoxBase.

virtual const u16 WoopsiUI::MultiLineTextBox::getPageCount | ( |  | ) | const`[virtual]`

Returns the number of "pages" that the text spans. A page is defined as the amount of text that can be displayed within the textbox at one time.

Returns:
  The page count.

s32 WoopsiUI::MultiLineTextBox::getRowContainingCoordinate | ( | s16 | y | ) | const`[protected]`

Get the row containing the specified Y co-ordinate.

Parameters:

  | y | Y co-ordinate to locate.

Returns:
  The index of the row containing the specified Y co-ordinate.

u8 WoopsiUI::MultiLineTextBox::getRowX | ( | s32 | row | ) | const`[protected]`

Gets the x position of a row of text based on the width of the row and the type of horizontal alignment currently set.

Parameters:

  | row | The index of the row.

Returns:
  The x co-ordinate of the row.

s16 WoopsiUI::MultiLineTextBox::getRowY | ( | s32 | row | ) | const`[protected]`

Gets the y position of the specified row of text based on the type of vertical alignment currently set.

Parameters:

  | row | The row number to find the y co-ordinate of.

Returns:
  The y co-ordinate of the specified row of text.

virtual const Text* WoopsiUI::MultiLineTextBox::getText | ( |  | ) | const`[inline, virtual]`

Returns a pointer to the Text object that contains the wrapped text used in the textbox. It is used as the pre-processed data source for the textbox, and should not be altered.

Returns:
  Pointer to the Text object.

virtual const u32 WoopsiUI::MultiLineTextBox::getTextLength | ( |  | ) | const`[virtual]`

Get the length of the text string.

Returns:
  The length of the text string.

virtual void WoopsiUI::MultiLineTextBox::handleKeyboardPressEvent | ( | const KeyboardEventArgs & | e | ) | `[virtual]`

Handle a keyboard press event.

Parameters:

  | e | The event data.

Reimplemented from WoopsiUI::KeyboardEventHandler.

virtual void WoopsiUI::MultiLineTextBox::handleKeyboardRepeatEvent | ( | const KeyboardEventArgs & | e | ) | `[virtual]`

Handle a keyboard repeat event.

Parameters:

  | e | The event data.

Reimplemented from WoopsiUI::KeyboardEventHandler.

virtual void WoopsiUI::MultiLineTextBox::hideCursor | ( |  | ) | `[virtual]`

Hides the cursor.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::insertText | ( | const WoopsiString & | text,
|  | const u32 | index |
| ) |  |  | `[virtual]`

Insert text at the specified index.

Parameters:

  | text | The text to insert.
  | index | Index at which to insert the text.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::insertTextAtCursor | ( | const WoopsiString & | text | ) | `[virtual]`

Insert text at the current cursor position.

Parameters:

  | text | The text to insert.

Implements WoopsiUI::TextBoxBase.

void WoopsiUI::MultiLineTextBox::jumpToCursor | ( |  | ) | `[protected]`

Jumps to the cursor co-ordinates of the text.

void WoopsiUI::MultiLineTextBox::jumpToTextBottom | ( |  | ) | `[protected]`

Jumps to the bottom of the text.

virtual void WoopsiUI::MultiLineTextBox::limitCanvasHeight | ( |  | ) | `[protected, virtual]`

Ensures that the canvas height is the height of the gadget, if the gadget exceeds the size of the text, or the height of the text if the text exceeds the size of the gadget.

virtual void WoopsiUI::MultiLineTextBox::limitCanvasY | ( |  | ) | `[protected, virtual]`

Ensures that the canvas cannot scroll beyond its height.

virtual void WoopsiUI::MultiLineTextBox::moveCursorDown | ( |  | ) | `[protected, virtual]`

Move cursor one row downwards.

virtual void WoopsiUI::MultiLineTextBox::moveCursorLeft | ( |  | ) | `[protected, virtual]`

Move cursor one character to the left.

virtual void WoopsiUI::MultiLineTextBox::moveCursorRight | ( |  | ) | `[protected, virtual]`

Move cursor one character to the right.

virtual void WoopsiUI::MultiLineTextBox::moveCursorToPosition | ( | const s32 | position | ) | `[virtual]`

Move the cursor to the text position specified. 0 indicates the start of the string. If position is greater than the length of the string, the cursor is moved to the end of the string.

Parameters:

  | position | The new cursor position.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::moveCursorUp | ( |  | ) | `[protected, virtual]`

Move cursor one row upwards.

virtual void WoopsiUI::MultiLineTextBox::onClick | ( | s16 | x,
|  | s16 | y |
| ) |  |  | `[protected, virtual]`

Starts the dragging system.

Parameters:

  | x | The x co-ordinate of the click.
  | y | The y co-ordinate of the click.

Reimplemented from WoopsiUI::ScrollingPanel.

virtual void WoopsiUI::MultiLineTextBox::onDoubleClick | ( | s16 | x,
|  | s16 | y |
| ) |  |  | `[protected, virtual]`

Opens the keyboard on the bottom display.

Parameters:

  | x | The x co-ordinates of the click.
  | y | The y co-ordinates of the click.

Reimplemented from WoopsiUI::Gadget.

virtual void WoopsiUI::MultiLineTextBox::onKeyPress | ( | KeyCode | keyCode | ) | `[protected, virtual]`

Moves the cursor.

Parameters:

  | keyCode | The key that was pressed.

Reimplemented from WoopsiUI::Gadget.

virtual void WoopsiUI::MultiLineTextBox::onKeyRepeat | ( | KeyCode | keyCode | ) | `[protected, virtual]`

Moves the cursor.

Parameters:

  | keyCode | The key that repeated.

Reimplemented from WoopsiUI::Gadget.

virtual void WoopsiUI::MultiLineTextBox::onResize | ( | u16 | width,
|  | u16 | height |
| ) |  |  | `[protected, virtual]`

Resize the textbox to the new dimensions.

Parameters:

  | width | The new width.
  | height | The new height.

Reimplemented from WoopsiUI::Gadget.

bool WoopsiUI::MultiLineTextBox::opensKeyboard | ( |  | ) | const`[inline, virtual]`

Check if the textbox opens the keyboard popup when double-clicked.

Returns:
  True if the keyboard pops up; false if not.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::processKey | ( | const WoopsiKey * | key | ) | `[protected, virtual]`

Handles keyboard key presses and key repeats.

Parameters:

  | key | Key that raised the event.

void WoopsiUI::MultiLineTextBox::processPhysicalKey | ( | KeyCode | keyCode | ) | `[protected]`

Handles physical button presses. Moves the cursor in the direction pressed.

Parameters:

  | keyCode | keyCode The key that was pressed.

virtual void WoopsiUI::MultiLineTextBox::removeText | ( | const u32 | startIndex,
|  | const u32 | count |
| ) |  |  | `[virtual]`

Remove specified number of characters from the string from the start index onwards.

Parameters:

  | startIndex | Index to remove from.
  | count | Number of characters to remove.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::removeText | ( | const u32 | startIndex | ) | `[virtual]`

Remove all characters from the string from the start index onwards.

Parameters:

  | startIndex | Index to remove from.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::setFont | ( | FontBase * | font | ) | `[virtual]`

Set the font used in the textbox.

Parameters:

  | font | Pointer to the new font.

Reimplemented from WoopsiUI::Gadget.

virtual void WoopsiUI::MultiLineTextBox::setText | ( | const WoopsiString & | text | ) | `[virtual]`

Set the text displayed in the textbox.

Parameters:

  | text | String to display.

Implements WoopsiUI::TextBoxBase.

virtual void WoopsiUI::MultiLineTextBox::setTextAlignmentHoriz | ( | TextAlignmentHoriz | alignment | ) | `[virtual]`

Set the horizontal alignment of text within the textbox.

Parameters:

  | alignment | The horizontal position of the text.

virtual void WoopsiUI::MultiLineTextBox::setTextAlignmentVert | ( | TextAlignmentVert | alignment | ) | `[virtual]`

Set the vertical alignment of text within the textbox.

Parameters:

  | alignment | The vertical position of the text.

virtual void WoopsiUI::MultiLineTextBox::showCursor | ( |  | ) | `[virtual]`

Shows the cursor.

Implements WoopsiUI::TextBoxBase.

## Member Data Documentation

s32 WoopsiUI::MultiLineTextBox::_cursorPos`[protected]`

Position of the cursor within the string.

TextAlignmentHoriz WoopsiUI::MultiLineTextBox::_hAlignment`[protected]`

Horizontal alignment of the text.

s16 WoopsiUI::MultiLineTextBox::_maxRows`[protected]`

Maximum number of rows that the textbox should buffer.

bool WoopsiUI::MultiLineTextBox::_opensKeyboard`[protected]`

Set to false to disable keyboard popup when double-clicked.

bool WoopsiUI::MultiLineTextBox::_showCursor`[protected]`

Set to true to make cursor visible.

Text* WoopsiUI::MultiLineTextBox::_text`[protected]`

Text object that manipulates and wraps the raw text string.

u32 WoopsiUI::MultiLineTextBox::_topRow`[protected]`

Index of the top row of text currently displayed.

TextAlignmentVert WoopsiUI::MultiLineTextBox::_vAlignment`[protected]`

Vertical alignment of the text.

u8 WoopsiUI::MultiLineTextBox::_visibleRows`[protected]`

Total number of rows that the textbox can display at once.

The documentation for this class was generated from the following file:

- multilinetextbox.h