Crazy Eddie's GUI System  0.8.4
CEGUI::MultiLineEditbox Class Reference

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

+ Inheritance diagram for CEGUI::MultiLineEditbox:
+ Collaboration diagram for CEGUI::MultiLineEditbox:

List of all members.

Classes

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

Public Types

typedef std::vector< LineInfo
CEGUI_VECTOR_ALLOC(LineInfo)> 
LineList
 Type for collection of LineInfos.

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 getCaretIndex (void) const
 return the current position of the caret.
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.
bool isWordWrapped (void) const
 Return whether the text in the edit box will be word-wrapped.
ScrollbargetVertScrollbar () const
 Return a pointer to the vertical scrollbar component widget for this MultiLineEditbox.
bool isVertScrollbarAlwaysShown (void) const
 Return whether the vertical scroll bar is always shown.
ScrollbargetHorzScrollbar () const
 Return a pointer to the horizontal scrollbar component widget for this MultiLineEditbox.
Rectf getTextRenderArea (void) const
 Return a Rect object describing, in un-clipped pixels, the window relative area that the text should be rendered in to.
const LineListgetFormattedLines (void) const
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.
virtual void initialiseComponents (void)
 Initialise the Window based object ready for use.
void setReadOnly (bool setting)
 Specify whether the edit box is read-only.
void setCaretIndex (size_t caret_pos)
 Set the current position of the caret.
void setSelection (size_t start_pos, size_t end_pos)
 Define the current selection for the edit box.
void setSelectionStart (size_t start_pos)
 Define the current selection start for the Editbox.
void setSelectionLength (size_t length)
 Define the current selection for the Editbox.
void setMaxTextLength (size_t max_len)
 set the maximum text length for this edit box.
void ensureCaretIsVisible (void)
 Scroll the view so that the current caret position is visible.
void setWordWrapping (bool setting)
 Set whether the text will be word wrapped or not.
void setShowVertScrollbar (bool setting)
 Set whether the vertical scroll bar should always be shown.
void setSelectionBrushImage (const Image *image)
const ImagegetSelectionBrushImage () const
virtual bool performCopy (Clipboard &clipboard)
virtual bool performCut (Clipboard &clipboard)
virtual bool performPaste (Clipboard &clipboard)
void formatText (const bool update_scrollbars)
 Format the text into lines as dictated by the formatting options.
 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 WidgetTypeName
 Window factory name.
static const String EventReadOnlyModeChanged
static const String EventWordWrapModeChanged
static const String EventMaximumTextLengthChanged
static const String EventCaretMoved
static const String EventTextSelectionChanged
static const String EventEditboxFull
static const String EventVertScrollbarModeChanged
static const String EventHorzScrollbarModeChanged
static const String VertScrollbarName
 Widget name for the vertical scrollbar component.
static const String HorzScrollbarName
 Widget name for the horizontal scrollbar component.

Protected Member Functions

void formatText (void)
 Return a Rect object describing, in un-clipped pixels, the window relative area that the text should be rendered in to.
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.
void configureScrollbars (void)
 display required integrated scroll bars according to current state of the edit box and update their values.
size_t getTextIndexFromPosition (const Vector2f &pt) const
 Return the text code point index that is rendered closest to screen position pt.
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 caret one character left.
void handleWordLeft (uint sysKeys)
 Processing to move caret one word left.
void handleCharRight (uint sysKeys)
 Processing to move caret one character right.
void handleWordRight (uint sysKeys)
 Processing to move caret one word right.
void handleDocHome (uint sysKeys)
 Processing to move caret to the start of the text.
void handleDocEnd (uint sysKeys)
 Processing to move caret to the end of the text.
void handleLineHome (uint sysKeys)
 Processing to move caret to the start of the current line.
void handleLineEnd (uint sysKeys)
 Processing to move caret to the end of the current line.
void handleLineUp (uint sysKeys)
 Processing to move caret up a line.
void handleLineDown (uint sysKeys)
 Processing to move caret down a line.
void handleNewLine (uint sysKeys)
 Processing to insert a new line / paragraph.
void handlePageUp (uint sysKeys)
 Processing to move caret one page up.
void handlePageDown (uint sysKeys)
 Processing to move caret one page down.
bool handle_scrollChange (const EventArgs &args)
 Internal handler that is triggered when the user interacts with the scrollbars.
bool handle_vertScrollbarVisibilityChanged (const EventArgs &)
virtual bool validateWindowRenderer (const WindowRenderer *renderer) const
 Function used in checking if a WindowRenderer is valid for this window.
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 onCaretMoved (WindowEventArgs &e)
 Handler called when the caret 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 (ElementEventArgs &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.
virtual void onFontChanged (WindowEventArgs &e)
 Handler called when the window's font is changed.

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_caretPos
 Position of the caret / 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.
bool d_forceVertScroll
 true if vertical scrollbar should always be displayed
bool d_forceHorzScroll
 true if horizontal scrollbar should always be displayed
const Imaged_selectionBrush
 Image to use as the selection brush (should be set by derived class).

Static Protected Attributes

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

Detailed Description

Base class for the multi-line edit box widget.


Member Function Documentation

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

Erase the currently selected text.

Parameters:
modify_textwhen true, the actual text will be modified. When false, everything is done except erasing the characters.
void CEGUI::MultiLineEditbox::formatText ( const bool  update_scrollbars)

Format the text into lines as dictated by the formatting options.

Parameters:
update_scrollbars
  • true if scrollbar configuration should be performed.
  • false if scrollbar configuration should not be performed.
void CEGUI::MultiLineEditbox::formatText ( void  ) [protected]

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.

Format the text into lines as needed by the current formatting options.

Deprecated:
This is deprecated in favour of the version taking a boolean.
size_t CEGUI::MultiLineEditbox::getCaretIndex ( void  ) const [inline]

return the current position of the caret.

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

Return a pointer to the horizontal scrollbar component widget for this MultiLineEditbox.

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectExceptionThrown if the horizontal Scrollbar component does not exist.
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.

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 caret.

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

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

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 caret.
size_t CEGUI::MultiLineEditbox::getTextIndexFromPosition ( const Vector2f pt) const [protected]

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

Parameters:
ptPoint object describing a position on the screen in pixels.
Returns:
Code point index into the text that is rendered closest to screen position pt.

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.

Return a pointer to the vertical scrollbar component widget for this MultiLineEditbox.

Returns:
Pointer to a Scrollbar object.
Exceptions:
UnknownObjectExceptionThrown if the vertical Scrollbar component does not exist.

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.
virtual void CEGUI::MultiLineEditbox::initialiseComponents ( 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.

Return whether the vertical scroll bar is always shown.

Returns:
  • true if the scroll bar will always be shown even if it is not required.
  • false if the scroll bar will only be shown when it is required.

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).
virtual void CEGUI::MultiLineEditbox::onCaptureLost ( WindowEventArgs e) [protected, virtual]

Handler called when this window loses capture of mouse inputs.

Parameters:
eWindowEventArgs 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.

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

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

Parameters:
eKeyEventArgs 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.

virtual void CEGUI::MultiLineEditbox::onFontChanged ( WindowEventArgs e) [protected, virtual]

Handler called when the window's font is changed.

Parameters:
eWindowEventArgs 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.

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

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

Parameters:
eKeyEventArgs 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.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

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

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

Parameters:
eMouseEventArgs object. All fields are valid.

Reimplemented from CEGUI::Window.

virtual void CEGUI::MultiLineEditbox::onSized ( ElementEventArgs e) [protected, virtual]

Handler called when the window's size changes.

Parameters:
eWindowEventArgs 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.

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

Handler called when the window's text is changed.

Parameters:
eWindowEventArgs 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.

virtual bool CEGUI::MultiLineEditbox::performCopy ( Clipboard clipboard) [virtual]

Asks the widget to perform a clipboard copy to the provided clipboard.

Parameters:
clipboardTarget clipboard class
Returns:
true if the copy was successful and allowed, false otherwise

Reimplemented from CEGUI::Window.

virtual bool CEGUI::MultiLineEditbox::performCut ( Clipboard clipboard) [virtual]

Asks the widget to perform a clipboard cut to the provided clipboard.

Parameters:
clipboardTarget clipboard class
Returns:
true if the cut was successful and allowed, false otherwise

Reimplemented from CEGUI::Window.

virtual bool CEGUI::MultiLineEditbox::performPaste ( Clipboard clipboard) [virtual]

Asks the widget to perform a clipboard paste from the provided clipboard.

Parameters:
clipboardSource clipboard class
Returns:
true if the paste was successful and allowed, false otherwise

Reimplemented from CEGUI::Window.

void CEGUI::MultiLineEditbox::setCaretIndex ( size_t  caret_pos)

Set the current position of the caret.

Parameters:
caret_posNew index for the insert caret relative to the start of the text. If the value specified is greater than the number of characters in the edit box, the caret is positioned at the end of the text.
Returns:
Nothing.

set the maximum text length for this edit box.

Parameters:
max_lenThe maximum number of code points (characters) that can be entered into this Editbox.
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::setSelection ( size_t  start_pos,
size_t  end_pos 
)

Define the current selection for the edit box.

Parameters:
start_posIndex 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_posIndex 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.

Define the current selection for the Editbox.

Parameters:
start_posLength of the selection.
Returns:
Nothing.
void CEGUI::MultiLineEditbox::setSelectionStart ( size_t  start_pos)

Define the current selection start for the Editbox.

Parameters:
start_posIndex of the starting point for the selection. If this value is greater than the number of characters in the Editbox, the selection start will be set to the end of the text.
Returns:
Nothing.

Set whether the vertical scroll bar should always be shown.

Parameters:
settingtrue if the vertical scroll bar should be shown even when it is not required. false if the vertical scroll bar should only be shown when it is required.
Returns:
Nothing.

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::validateWindowRenderer ( const WindowRenderer renderer) const [protected, virtual]

Function used in checking if a WindowRenderer is valid for this window.

Parameters:
rendererWindow renderer that will be checked (it can be null!)
Returns:
Returns true if the given WindowRenderer class name is valid for this window. False if not.

Reimplemented from CEGUI::Window.


Member Data Documentation

Event fired when the text caret / current insertion position is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose caret position has changed.

Event fired when the number of characters in the edit box reaches the current maximum length. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose text length has reached the set maximum allowable length for the edit box.

Event fired when the mode setting that forces the display of the horizontal scroll bar for the edit box is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose horizontal scrollbar mode has been changed.

Event fired when the maximum allowable string length for the edit box has been changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose maximum string length was changed.

Event fired when the read-only mode for the edit box has been changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose read-only mode was changed.

Event fired when the current text selection for the edit box is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose text selection was changed.

Event fired when the mode setting that forces the display of the vertical scroll bar for the edit box is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose vertical scrollbar mode has been changed.

Event fired when the word wrap mode of the edit box has been changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the MultiLineEditbox whose word wrap mode was changed.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends