# CEGUI::MultiLineEditbox Class Reference

Base class for the multi-line edit box widget. More...

Inheritance diagram for CEGUI::MultiLineEditbox:

[legend]
Collaboration diagram for CEGUI::MultiLineEditbox:

[legend]
List of all members.

## Public Member Functions

bool | hasInputFocus (void) const
| return true if the edit box has input focus.
bool | isReadOnly (void) const
| return true if the edit box is read-only.
size_t | getCaratIndex (void) const
| return the current position of the carat.
size_t | getSelectionStartIndex (void) const
| return the current selection start point.
size_t | getSelectionEndIndex (void) const
| return the current selection end point.
size_t | getSelectionLength (void) const
| return the length of the current selection (in code points / characters).
size_t | getMaxTextLength (void) const
| return the maximum text length set for this edit box.
colour | getNormalTextColour (void) const
| return the currently set colour to be used for rendering edit box text in the normal, unselected state.
colour | getSelectedTextColour (void) const
| return the currently set colour to be used for rendering the edit box text when within the selected region.
colour | getNormalSelectBrushColour (void) const
| return the currently set colour to be used for rendering the edit box selection highlight when the edit box is active.
colour | getInactiveSelectBrushColour (void) const
| return the currently set colour to be used for rendering the edit box selection highlight when the edit box is inactive.
bool | isWordWrapped (void) const
| Return whether the text in the edit box will be word-wrapped.
virtual void | initialise (void)
| Initialise the Window based object ready for use.
void | setReadOnly (bool setting)
| Specify whether the edit box is read-only.
void | setCaratIndex (size_t carat_pos)
| Set the current position of the carat.
void | setSelection (size_t start_pos, size_t end_pos)
| Define the current selection for the edit box.
void | setMaxTextLength (size_t max_len)
| set the maximum text length for this edit box.
void | setNormalTextColour (const colour &col)
| Set the colour to be used for rendering edit box text in the normal, unselected state.
void | setSelectedTextColour (const colour &col)
| Set the colour to be used for rendering the edit box text when within the selected region.
void | setNormalSelectBrushColour (const colour &col)
| Set the colour to be used for rendering the edit box selection highlight when the edit box is active.
void | setInactiveSelectBrushColour (const colour &col)
| Set the colour to be used for rendering the edit box selection highlight when the edit box is inactive.
void | ensureCaratIsVisible (void)
| Scroll the view so that the current carat position is visible.
void | setWordWrapping (bool setting)
| Set whether the text will be word wrapped or not.
| MultiLineEditbox (const String &type, const String &name)
| Constructor for the MultiLineEditbox base class.
virtual | ~MultiLineEditbox (void)
| Destructor for the MultiLineEditbox base class.

## Static Public Attributes

static const String | EventNamespace
| Namespace for global events.
static const String | EventReadOnlyModeChanged
| The read-only mode for the edit box has been changed.
static const String | EventWordWrapModeChanged
| The word wrap mode of the text box has been changed.
static const String | EventMaximumTextLengthChanged
| The maximum allowable string length has been changed.
static const String | EventCaratMoved
| The text carat (insert point) has changed.
static const String | EventTextSelectionChanged
| The current text selection has changed.
static const String | EventEditboxFull
| The number of characters in the edit box has reached the current maximum.
static const String | EventVertScrollbarModeChanged
| Event triggered when the vertical scroll bar 'force' setting changes.
static const String | EventHorzScrollbarModeChanged
| Event triggered when the horizontal scroll bar 'force' setting changes.
static const argb_t | DefaultNormalTextColour = 0xFFFFFFFF
| Colour applied to normal unselected text.
static const argb_t | DefaultSelectedTextColour = 0xFF000000
| Colour applied to selected text.
static const argb_t | DefaultNormalSelectionColour = 0xFF6060FF
| Colour applied to normal selection brush.
static const argb_t | DefaultInactiveSelectionColour = 0xFF808080
| Colour applied to selection brush when widget is inactive.

## Protected Types

typedef std::vector< LineInfo > | LineList
| Type for collection of LineInfos.

## Protected Member Functions

virtual Rect | getTextRenderArea (void) const =0
| Return a Rect object describing, in un-clipped pixels, the window relative area that the text should be rendered in to.
virtual Scrollbar * | createVertScrollbar (const String &name) const =0
| create and return a pointer to a Scrollbar widget for use as vertical scroll bar
virtual Scrollbar * | createHorzScrollbar (const String &name) const =0
| create and return a pointer to a Scrollbar widget for use as horizontal scroll bar
virtual void | cacheEditboxBaseImagery ()=0
| Perform rendering of the widget control frame and other 'static' areas. This method should not render the actual text. Note that the text will be rendered to layer 4 and the selection brush to layer 3, other layers can be used for rendering imagery behind and infront of the text & selection..
virtual void | cacheCaratImagery (const Rect &textArea)=0
| Render the carat.
void | addMultiLineEditboxEvents (void)
| Add multi-line edit box specific events.
void | cacheTextLines (const Rect &dest_area)
| Render text lines.
void | formatText (void)
| Format the text into lines as needed by the current formatting options.
size_t | getNextTokenLength (const String &text, size_t start_idx) const
| Return the length of the next token in String text starting at index start_idx.
virtual void | populateRenderCache ()
| Update the rendering cache.
void | configureScrollbars (void)
| display required integrated scroll bars according to current state of the edit box and update their values.
size_t | getTextIndexFromPosition (const Point &pt) const
| Return the text code point index that is rendered closest to screen position pt.
size_t | getLineNumberFromIndex (size_t index) const
| Return the line number a given index falls on with the current formatting. Will return last line if index is out of range.
void | clearSelection (void)
| Clear the current selection setting.
void | eraseSelectedText (bool modify_text=true)
| Erase the currently selected text.
void | handleBackspace (void)
| Processing for backspace key.
void | handleDelete (void)
| Processing for Delete key.
void | handleCharLeft (uint sysKeys)
| Processing to move carat one character left.
void | handleWordLeft (uint sysKeys)
| Processing to move carat one word left.
void | handleCharRight (uint sysKeys)
| Processing to move carat one character right.
void | handleWordRight (uint sysKeys)
| Processing to move carat one word right.
void | handleDocHome (uint sysKeys)
| Processing to move carat to the start of the text.
void | handleDocEnd (uint sysKeys)
| Processing to move carat to the end of the text.
void | handleLineHome (uint sysKeys)
| Processing to move carat to the start of the current line.
void | handleLineEnd (uint sysKeys)
| Processing to move carat to the end of the current line.
void | handleLineUp (uint sysKeys)
| Processing to move carat up a line.
void | handleLineDown (uint sysKeys)
| Processing to move carat down a line.
void | handleNewLine (uint sysKeys)
| Processing to insert a new line / paragraph.
virtual bool | testClassName_impl (const String &class_name) const
| Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.
bool | handle_scrollChange (const EventArgs &args)
| Internal handler that is triggered when the user interacts with the scrollbars.
void | onReadOnlyChanged (WindowEventArgs &e)
| Handler called when the read-only state of the edit box changes.
void | onWordWrapModeChanged (WindowEventArgs &e)
| Handler called when the word wrap mode for the the edit box changes.
void | onMaximumTextLengthChanged (WindowEventArgs &e)
| Handler called when the maximum text length for the edit box changes.
void | onCaratMoved (WindowEventArgs &e)
| Handler called when the carat moves.
void | onTextSelectionChanged (WindowEventArgs &e)
| Handler called when the text selection changes.
void | onEditboxFullEvent (WindowEventArgs &e)
| Handler called when the edit box is full.
void | onVertScrollbarModeChanged (WindowEventArgs &e)
| Handler called when the 'always show' setting for the vertical scroll bar changes.
void | onHorzScrollbarModeChanged (WindowEventArgs &e)
| Handler called when 'always show' setting for the horizontal scroll bar changes.
virtual void | onMouseButtonDown (MouseEventArgs &e)
| Handler called when a mouse button has been depressed within this window's area.
virtual void | onMouseButtonUp (MouseEventArgs &e)
| Handler called when a mouse button has been released within this window's area.
virtual void | onMouseDoubleClicked (MouseEventArgs &e)
| Handler called when a mouse button has been double-clicked within this window's area.
virtual void | onMouseTripleClicked (MouseEventArgs &e)
| Handler called when a mouse button has been triple-clicked within this window's area.
virtual void | onMouseMove (MouseEventArgs &e)
| Handler called when the mouse cursor has been moved within this window's area.
virtual void | onCaptureLost (WindowEventArgs &e)
| Handler called when this window loses capture of mouse inputs.
virtual void | onCharacter (KeyEventArgs &e)
| Handler called when a character-key has been pressed while this window has input focus.
virtual void | onKeyDown (KeyEventArgs &e)
| Handler called when a key as been depressed while this window has input focus.
virtual void | onTextChanged (WindowEventArgs &e)
| Handler called when the window's text is changed.
virtual void | onSized (WindowEventArgs &e)
| Handler called when the window's size changes.
virtual void | onMouseWheel (MouseEventArgs &e)
| Handler called when the mouse wheel (z-axis) position changes within this window's area.

## Protected Attributes

bool | d_readOnly
| true if the edit box is in read-only mode
size_t | d_maxTextLen
| Maximum number of characters for this Editbox.
size_t | d_caratPos
| Position of the carat / insert-point.
size_t | d_selectionStart
| Start of selection area.
size_t | d_selectionEnd
| End of selection area.
bool | d_dragging
| true when a selection is being dragged.
size_t | d_dragAnchorIdx
| Selection index for drag selection anchor point.
bool | d_wordWrap
| true when formatting uses word-wrapping.
LineList | d_lines
| Holds the lines for the current formatting.
float | d_widestExtent
| Holds the extent of the widest line as calculated in the last formatting pass.
Scrollbar * | d_vertScrollbar
| Points to the vertical scroll bar widget.
Scrollbar * | d_horzScrollbar
| Points to the horizontal scroll bar widget.
bool | d_forceVertScroll
| true if vertical scrollbar should always be displayed
bool | d_forceHorzScroll
| true if horizontal scrollbar should always be displayed
const Image * | d_selectionBrush
| Image to use as the selection brush (should be set by derived class).
colour | d_normalTextColour
| Text colour used normally.
colour | d_selectTextColour
| Text colour used when text is highlighted.
colour | d_selectBrushColour
| Colour to apply to the selection brush.
colour | d_inactiveSelectBrushColour
| Colour to apply to the selection brush when widget is inactive / read-only.

## Static Protected Attributes

static String | d_lineBreakChars
| Holds what we consider to be line break characters.

## Classes

struct | LineInfo
| struct used to store information about a formatted line within the paragraph. More...

## Detailed Description

Base class for the multi-line edit box widget.

## Member Function Documentation

virtual void CEGUI::MultiLineEditbox::cacheCaratImagery | ( | const Rect & | textArea | ) | `[protected, pure virtual]`

Render the carat.

Returns:
  Nothing

virtual void CEGUI::MultiLineEditbox::cacheEditboxBaseImagery | ( |  | ) | `[protected, pure virtual]`

Perform rendering of the widget control frame and other 'static' areas. This method should not render the actual text. Note that the text will be rendered to layer 4 and the selection brush to layer 3, other layers can be used for rendering imagery behind and infront of the text & selection..

Returns:
  Nothing.

virtual Scrollbar* CEGUI::MultiLineEditbox::createHorzScrollbar | ( | const String & | name | ) | const`[protected, pure virtual]`

create and return a pointer to a Scrollbar widget for use as horizontal scroll bar

Parameters:

  | name | String holding the name to be assigned to the component.

Returns:
  Pointer to a Scrollbar to be used for scrolling horizontally.

virtual Scrollbar* CEGUI::MultiLineEditbox::createVertScrollbar | ( | const String & | name | ) | const`[protected, pure virtual]`

create and return a pointer to a Scrollbar widget for use as vertical scroll bar

Parameters:

  | name | String holding the name to be assigned to the component.

Returns:
  Pointer to a Scrollbar to be used for scrolling vertically.

void CEGUI::MultiLineEditbox::eraseSelectedText | ( | bool | modify_text = `true` | ) | `[protected]`

Erase the currently selected text.

Parameters:

  | modify_text | when true, the actual text will be modified. When false, everything is done except erasing the characters.

size_t CEGUI::MultiLineEditbox::getCaratIndex | ( | void |  | ) | const`[inline]`

return the current position of the carat.

Returns:
  Index of the insert carat relative to the start of the text.

colour CEGUI::MultiLineEditbox::getInactiveSelectBrushColour | ( | void |  | ) | const`[inline]`

return the currently set colour to be used for rendering the edit box selection highlight when the edit box is inactive.

Returns:
  colour value describing the ARGB colour that is currently set.

size_t CEGUI::MultiLineEditbox::getMaxTextLength | ( | void |  | ) | const`[inline]`

return the maximum text length set for this edit box.

Returns:
  The maximum number of code points (characters) that can be entered into this edit box.

size_t CEGUI::MultiLineEditbox::getNextTokenLength | ( | const String & | text,
|  | size_t | start_idx
| ) | const`[protected]`

Return the length of the next token in String text starting at index start_idx.

Note:
  Any single whitespace character is one token, any group of other characters is a token.

Returns:
  The code point length of the token.

colour CEGUI::MultiLineEditbox::getNormalSelectBrushColour | ( | void |  | ) | const`[inline]`

return the currently set colour to be used for rendering the edit box selection highlight when the edit box is active.

Returns:
  colour value describing the ARGB colour that is currently set.

colour CEGUI::MultiLineEditbox::getNormalTextColour | ( | void |  | ) | const`[inline]`

return the currently set colour to be used for rendering edit box text in the normal, unselected state.

Returns:
  colour value describing the ARGB colour that is currently set.

colour CEGUI::MultiLineEditbox::getSelectedTextColour | ( | void |  | ) | const`[inline]`

return the currently set colour to be used for rendering the edit box text when within the selected region.

Returns:
  colour value describing the ARGB colour that is currently set.

size_t CEGUI::MultiLineEditbox::getSelectionEndIndex | ( | void |  | ) | const

return the current selection end point.

Returns:
  Index of the selection end point relative to the start of the text. If no selection is defined this function returns the position of the carat.

size_t CEGUI::MultiLineEditbox::getSelectionLength | ( | void |  | ) | const

return the length of the current selection (in code points / characters).

Returns:
  Number of code points (or characters) contained within the currently defined selection.

size_t CEGUI::MultiLineEditbox::getSelectionStartIndex | ( | void |  | ) | const

return the current selection start point.

Returns:
  Index of the selection start point relative to the start of the text. If no selection is defined this function returns the position of the carat.

size_t CEGUI::MultiLineEditbox::getTextIndexFromPosition | ( | const Point & | pt | ) | const`[protected]`

Return the text code point index that is rendered closest to screen position pt.

Parameters:

  | pt | Point object describing a position on the screen in pixels.

Returns:
  Code point index into the text that is rendered closest to screen position pt.

virtual Rect CEGUI::MultiLineEditbox::getTextRenderArea | ( | void |  | ) | const`[protected, pure virtual]`

Return a Rect object describing, in un-clipped pixels, the window relative area that the text should be rendered in to.

Returns:
  Rect object describing the area of the Window to be used for rendering text.

bool CEGUI::MultiLineEditbox::hasInputFocus | ( | void |  | ) | const

return true if the edit box has input focus.

Returns:
  - true if the edit box has keyboard input focus.
  - false if the edit box does not have keyboard input focus.

void CEGUI::MultiLineEditbox::initialise | ( | void |  | ) | `[virtual]`

Initialise the Window based object ready for use.

Note:
  This must be called for every window created. Normally this is handled automatically by the WindowFactory for each Window type.

Returns:
  Nothing

Reimplemented from CEGUI::Window.

bool CEGUI::MultiLineEditbox::isReadOnly | ( | void |  | ) | const`[inline]`

return true if the edit box is read-only.

Returns:
  - true if the edit box is read only and can't be edited by the user.
  - false if the edit box is not read only and may be edited by the user.

bool CEGUI::MultiLineEditbox::isWordWrapped | ( | void |  | ) | const

Return whether the text in the edit box will be word-wrapped.

Returns:
  - true if the text will be word-wrapped at the edges of the widget frame.
  - false if text will not be word-wrapped (a scroll bar will be used to access long text lines).

void CEGUI::MultiLineEditbox::onCaptureLost | ( | WindowEventArgs & | e | ) | `[protected, virtual]`

Handler called when this window loses capture of mouse inputs.

Parameters:

  | e | WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onCharacter | ( | KeyEventArgs & | e | ) | `[protected, virtual]`

Handler called when a character-key has been pressed while this window has input focus.

Parameters:

  | e | KeyEventArgs object whose 'codepoint' field is set to the Unicode code point (encoded as utf32) for the character typed, and whose 'sysKeys' field represents the combination of SystemKey that were active when the event was generated. All other fields should be considered as 'junk'.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onKeyDown | ( | KeyEventArgs & | e | ) | `[protected, virtual]`

Handler called when a key as been depressed while this window has input focus.

Parameters:

  | e | KeyEventArgs object whose 'scancode' field is set to the Key::Scan value representing the key that was pressed, and whose 'sysKeys' field represents the combination of SystemKey that were active when the event was generated.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseButtonDown | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when a mouse button has been depressed within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseButtonUp | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when a mouse button has been released within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseDoubleClicked | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when a mouse button has been double-clicked within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseMove | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when the mouse cursor has been moved within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseTripleClicked | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when a mouse button has been triple-clicked within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onMouseWheel | ( | MouseEventArgs & | e | ) | `[protected, virtual]`

Handler called when the mouse wheel (z-axis) position changes within this window's area.

Parameters:

  | e | MouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onSized | ( | WindowEventArgs & | e | ) | `[protected, virtual]`

Handler called when the window's size changes.

Parameters:

  | e | WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::onTextChanged | ( | WindowEventArgs & | e | ) | `[protected, virtual]`

Handler called when the window's text is changed.

Parameters:

  | e | WindowEventArgs object whose 'window' pointer field is set to the window that triggered the event. For this event the trigger window is always 'this'.

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::populateRenderCache | ( |  | ) | `[protected, virtual]`

| Update the rendering cache. Populates the Window's RenderCache with imagery to be sent to the renderer. Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::setCaratIndex | ( | size_t | carat_pos | ) |

Set the current position of the carat.

Parameters:

  | carat_pos | New index for the insert carat relative to the start of the text. If the value specified is greater than the number of characters in the edit box, the carat is positioned at the end of the text.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setInactiveSelectBrushColour | ( | const colour & | col | ) |

Set the colour to be used for rendering the edit box selection highlight when the edit box is inactive.

Parameters:

  | col | colour value describing the ARGB colour that is to be used.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setMaxTextLength | ( | size_t | max_len | ) |

set the maximum text length for this edit box.

Parameters:

  | max_len | The maximum number of code points (characters) that can be entered into this Editbox.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setNormalSelectBrushColour | ( | const colour & | col | ) |

Set the colour to be used for rendering the edit box selection highlight when the edit box is active.

Parameters:

  | col | colour value describing the ARGB colour that is to be used.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setNormalTextColour | ( | const colour & | col | ) |

Set the colour to be used for rendering edit box text in the normal, unselected state.

Parameters:

  | col | colour value describing the ARGB colour that is to be used.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setReadOnly | ( | bool | setting | ) |

Specify whether the edit box is read-only.

Parameters:

  setting

  - true if the edit box is read only and can't be edited by the user.
  - false if the edit box is not read only and may be edited by the user.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setSelectedTextColour | ( | const colour & | col | ) |

Set the colour to be used for rendering the edit box text when within the selected region.

Returns:
  colour value describing the ARGB colour that is currently set.

void CEGUI::MultiLineEditbox::setSelection | ( | size_t | start_pos,
|  | size_t | end_pos
| ) |

Define the current selection for the edit box.

Parameters:

  | start_pos | Index of the starting point for the selection. If this value is greater than the number of characters in the edit box, the selection start will be set to the end of the text.
  | end_pos | Index of the ending point for the selection. If this value is greater than the number of characters in the edit box, the selection start will be set to the end of the text.

Returns:
  Nothing.

void CEGUI::MultiLineEditbox::setWordWrapping | ( | bool | setting | ) |

Set whether the text will be word wrapped or not.

Parameters:

  setting

  - true if the text should word-wrap at the edges of the text box.
  - false if the text should not wrap, but a scroll bar should be used.

Returns:
  Nothing.

virtual bool CEGUI::MultiLineEditbox::testClassName_impl | ( | const String & | class_name | ) | const`[inline, protected, virtual]`

Return whether this window was inherited from the given class name at some point in the inheritance heirarchy.

Parameters:

  | class_name | The class name that is to be checked.

Returns:
  true if this window was inherited from class_name. false if not.

Reimplemented from CEGUI::Window.