CEGUI::Editbox Class Reference

Base class for an Editbox widget. More...

Inheritance diagram for CEGUI::Editbox:

Inheritance graph
[legend]
Collaboration diagram for CEGUI::Editbox:

Collaboration graph
[legend]

List of all members.

Public Member Functions

bool hasInputFocus (void) const
 return true if the Editbox has input focus.
bool isReadOnly (void) const
 return true if the Editbox is read-only.
bool isTextMasked (void) const
 return true if the text for the Editbox will be rendered masked.
bool isTextValid (void) const
 return true if the Editbox text is valid given the currently set validation string.
const StringgetValidationString (void) const
 return the currently set validation string
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).
utf32 getMaskCodePoint (void) const
 return the utf32 code point used when rendering masked text.
size_t getMaxTextLength (void) const
 return the maximum text length set for this Editbox.
void setReadOnly (bool setting)
 Specify whether the Editbox is read-only.
void setTextMasked (bool setting)
 Specify whether the text for the Editbox will be rendered masked.
void setValidationString (const String &validation_string)
 Set the text validation string.
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 Editbox.
void setMaskCodePoint (utf32 code_point)
 set the utf32 code point used when rendering masked text.
void setMaxTextLength (size_t max_len)
 set the maximum text length for this Editbox.
 Editbox (const String &type, const String &name)
 Constructor for Editbox class.
virtual ~Editbox (void)
 Destructor for Editbox class.

Static Public Attributes

static const String EventNamespace
 Namespace for global events.
static const String WidgetTypeName
 Window factory name.
static const String EventReadOnlyModeChanged
 The read-only mode for the edit box has been changed.
static const String EventMaskedRenderingModeChanged
 The masked rendering mode (password mode) has been changed.
static const String EventMaskCodePointChanged
 The code point (character) to use for masked text has been changed.
static const String EventValidationStringChanged
 The validation string has been changed.
static const String EventMaximumTextLengthChanged
 The maximum allowable string length has been changed.
static const String EventTextInvalidated
 Some operation has made the current text invalid with regards to the validation string.
static const String EventInvalidEntryAttempted
 The user attempted to modify the text in a way that would have made it invalid.
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 EventTextAccepted
 The user has accepted the current text by pressing Return, Enter, or Tab.

Protected Member Functions

size_t getTextIndexFromPosition (const Point &pt) const
 Return the text code point index that is rendered closest to screen position pt.
void clearSelection (void)
 Return the text code point index that is rendered closest to screen position pt.
void eraseSelectedText (bool modify_text=true)
 Erase the currently selected text.
bool isStringValid (const String &str) const
 return true if the given string matches the validation regular expression.
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 handleHome (uint sysKeys)
 Processing to move carat to the start of the text.
void handleEnd (uint sysKeys)
 Processing to move carat to the end of the text.
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 hierarchy.
virtual bool validateWindowRenderer (const String &name) const
 Function used in checking if a WindowRenderer is valid for this window.
virtual void onReadOnlyChanged (WindowEventArgs &e)
 Event fired internally when the read only state of the Editbox has been changed.
virtual void onMaskedRenderingModeChanged (WindowEventArgs &e)
 Event fired internally when the masked rendering mode (password mode) has been changed.
virtual void onMaskCodePointChanged (WindowEventArgs &e)
 Event fired internally when the code point to use for masked rendering has been changed.
virtual void onValidationStringChanged (WindowEventArgs &e)
 Event fired internally when the validation string is changed.
virtual void onMaximumTextLengthChanged (WindowEventArgs &e)
 Event fired internally when the maximum text length for the edit box is changed.
virtual void onTextInvalidatedEvent (WindowEventArgs &e)
 Event fired internally when something has caused the current text to now fail validation.
virtual void onInvalidEntryAttempted (WindowEventArgs &e)
 Event fired internally when the user attempted to make a change to the edit box that would have caused it to fail validation.
virtual void onCaratMoved (WindowEventArgs &e)
 Event fired internally when the carat (insert point) position changes.
virtual void onTextSelectionChanged (WindowEventArgs &e)
 Event fired internally when the current text selection changes.
virtual void onEditboxFullEvent (WindowEventArgs &e)
 Event fired internally when the edit box text has reached the set maximum length.
virtual void onTextAcceptedEvent (WindowEventArgs &e)
 Event fired internally when the user accepts the edit box text by pressing Return, Enter, or Tab.
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.

Protected Attributes

bool d_readOnly
 True if the editbox is in read-only mode.
bool d_maskText
 True if the editbox text should be rendered masked.
utf32 d_maskCodePoint
 Code point to use when rendering masked text.
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.
String d_validationString
 Copy of validation reg-ex string.
RegexValidatord_validator
 RegEx String used for validation of text.
bool d_dragging
 true when a selection is being dragged.
size_t d_dragAnchorIdx
 Selection index for drag selection anchor point.


Detailed Description

Base class for an Editbox widget.

Member Function Documentation

void CEGUI::Editbox::clearSelection ( void   )  [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.
Clear the current selection setting

References getSelectionLength(), and setSelection().

Referenced by eraseSelectedText(), handleCharLeft(), handleCharRight(), handleEnd(), handleHome(), handleWordLeft(), handleWordRight(), onMouseButtonDown(), and onTextChanged().

void CEGUI::Editbox::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.

References clearSelection(), CEGUI::Window::d_text, CEGUI::String::erase(), getSelectionLength(), getSelectionStartIndex(), onTextChanged(), and setCaratIndex().

Referenced by handleBackspace(), handleDelete(), and onCharacter().

size_t CEGUI::Editbox::getCaratIndex ( void   )  const [inline]

return the current position of the carat.

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

Referenced by CEGUI::Combobox::getCaratIndex(), handleBackspace(), handleDelete(), handleWordLeft(), handleWordRight(), onKeyDown(), onTextChanged(), and CEGUI::FalagardEditbox::render().

utf32 CEGUI::Editbox::getMaskCodePoint ( void   )  const [inline]

return the utf32 code point used when rendering masked text.

Returns:
utf32 code point value representing the Unicode code point that will be rendered instead of the Editbox text when rendering in masked mode.

Referenced by CEGUI::FalagardEditbox::getTextIndexFromPosition(), and CEGUI::FalagardEditbox::render().

size_t CEGUI::Editbox::getMaxTextLength ( void   )  const [inline]

return the maximum text length set for this Editbox.

Returns:
The maximum number of code points (characters) that can be entered into this Editbox.
Note:
Depending on the validation string set, the actual length of text that can be entered may be less than the value returned here (it will never be more).

Referenced by CEGUI::Combobox::getMaxTextLength().

size_t CEGUI::Editbox::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.

References d_caratPos, d_selectionEnd, and d_selectionStart.

Referenced by CEGUI::Combobox::getSelectionEndIndex(), and CEGUI::FalagardEditbox::render().

size_t CEGUI::Editbox::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.

References d_selectionEnd, and d_selectionStart.

Referenced by clearSelection(), eraseSelectedText(), CEGUI::Combobox::getSelectionLength(), handleBackspace(), handleDelete(), onCharacter(), onKeyDown(), CEGUI::FalagardEditbox::render(), and CEGUI::EditboxProperties::SelectionStart::set().

size_t CEGUI::Editbox::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.

References d_caratPos, d_selectionEnd, and d_selectionStart.

Referenced by eraseSelectedText(), CEGUI::Combobox::getSelectionStartIndex(), handleBackspace(), handleDelete(), onCharacter(), CEGUI::FalagardEditbox::render(), and CEGUI::EditboxProperties::SelectionLength::set().

size_t CEGUI::Editbox::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.

References CEGUI::Window::d_windowRenderer, and CEGUI::EditboxWindowRenderer::getTextIndexFromPosition().

Referenced by onMouseButtonDown(), and onMouseMove().

const String& CEGUI::Editbox::getValidationString ( void   )  const [inline]

return the currently set validation string

Note:
Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.
Returns:
String object containing the current validation regex data

Referenced by CEGUI::Combobox::getValidationString().

bool CEGUI::Editbox::hasInputFocus ( void   )  const

return true if the Editbox has input focus.

Returns:
true if the Editbox has keyboard input focus, false if the Editbox does not have keyboard input focus.

References CEGUI::Window::isActive().

Referenced by CEGUI::Combobox::hasInputFocus(), onCharacter(), onKeyDown(), and CEGUI::FalagardEditbox::render().

bool CEGUI::Editbox::isReadOnly ( void   )  const [inline]

return true if the Editbox is read-only.

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

Referenced by CEGUI::Combobox::editbox_MouseDownHandler(), handleBackspace(), handleDelete(), CEGUI::Combobox::isReadOnly(), onCharacter(), onKeyDown(), and CEGUI::FalagardEditbox::render().

bool CEGUI::Editbox::isTextMasked ( void   )  const [inline]

return true if the text for the Editbox will be rendered masked.

Returns:
true if the Editbox text will be rendered masked using the currently set mask code point, false if the Editbox text will be rendered as plain text.

Referenced by CEGUI::FalagardEditbox::getTextIndexFromPosition(), onMaskCodePointChanged(), onMouseDoubleClicked(), and CEGUI::FalagardEditbox::render().

bool CEGUI::Editbox::isTextValid ( void   )  const

return true if the Editbox text is valid given the currently set validation string.

Note:
It is possible to programmatically set 'invalid' text for the Editbox by calling setText. This has certain implications since if invalid text is set, whatever the user types into the box will be rejected when the input is validated.

Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.

Returns:
true if the current Editbox text passes validation, false if the text does not pass validation.

References CEGUI::Window::d_text, and isStringValid().

Referenced by CEGUI::Combobox::isTextValid(), setMaxTextLength(), and setValidationString().

void CEGUI::Editbox::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.

References d_dragging, and CEGUI::EventArgs::handled.

void CEGUI::Editbox::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.

References CEGUI::KeyEventArgs::codepoint, d_caratPos, d_maxTextLen, CEGUI::Window::d_text, CEGUI::String::erase(), eraseSelectedText(), CEGUI::Window::getFont(), getSelectionLength(), getSelectionStartIndex(), CEGUI::EventArgs::handled, hasInputFocus(), CEGUI::String::insert(), isReadOnly(), isStringValid(), CEGUI::String::length(), onEditboxFullEvent(), onInvalidEntryAttempted(), and CEGUI::Window::setText().

void CEGUI::Editbox::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.

References CEGUI::Control, d_dragAnchorIdx, getCaratIndex(), getSelectionLength(), handleBackspace(), handleCharLeft(), handleCharRight(), CEGUI::EventArgs::handled, handleDelete(), handleEnd(), handleHome(), handleWordLeft(), handleWordRight(), hasInputFocus(), isReadOnly(), onTextAcceptedEvent(), CEGUI::KeyEventArgs::scancode, and CEGUI::KeyEventArgs::sysKeys.

void CEGUI::Editbox::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.

References CEGUI::MouseEventArgs::button, CEGUI::Window::captureInput(), clearSelection(), d_dragAnchorIdx, d_dragging, getTextIndexFromPosition(), CEGUI::EventArgs::handled, CEGUI::LeftButton, CEGUI::MouseEventArgs::position, and setCaratIndex().

void CEGUI::Editbox::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.

References CEGUI::MouseEventArgs::button, CEGUI::EventArgs::handled, CEGUI::LeftButton, and CEGUI::Window::releaseInput().

void CEGUI::Editbox::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.

References CEGUI::MouseEventArgs::button, d_caratPos, d_dragAnchorIdx, CEGUI::Window::d_text, CEGUI::TextUtils::getNextWordStartIdx(), CEGUI::TextUtils::getWordStartIdx(), CEGUI::EventArgs::handled, isTextMasked(), CEGUI::LeftButton, CEGUI::String::length(), setCaratIndex(), and setSelection().

void CEGUI::Editbox::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.

References d_caratPos, d_dragAnchorIdx, d_dragging, getTextIndexFromPosition(), CEGUI::EventArgs::handled, CEGUI::MouseEventArgs::position, setCaratIndex(), and setSelection().

void CEGUI::Editbox::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.

References CEGUI::MouseEventArgs::button, d_caratPos, d_dragAnchorIdx, CEGUI::Window::d_text, CEGUI::EventArgs::handled, CEGUI::LeftButton, CEGUI::String::length(), setCaratIndex(), and setSelection().

void CEGUI::Editbox::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.

References clearSelection(), CEGUI::Window::d_text, getCaratIndex(), CEGUI::EventArgs::handled, CEGUI::String::length(), and setCaratIndex().

Referenced by eraseSelectedText(), and setMaxTextLength().

void CEGUI::Editbox::onTextInvalidatedEvent ( WindowEventArgs e  )  [protected, virtual]

Event fired internally when something has caused the current text to now fail validation.

This can be caused by changing the validation string or setting a maximum length that causes the current text to be truncated.

References EventNamespace, EventTextInvalidated, and CEGUI::EventSet::fireEvent().

Referenced by setMaxTextLength(), and setValidationString().

void CEGUI::Editbox::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 Editbox, the carat is positioned at the end of the text.
Returns:
Nothing.

References d_caratPos, CEGUI::Window::d_text, CEGUI::String::length(), and onCaratMoved().

Referenced by CEGUI::Combobox::droplist_SelectionAcceptedHandler(), eraseSelectedText(), handleBackspace(), handleCharLeft(), handleCharRight(), handleEnd(), handleHome(), handleWordLeft(), handleWordRight(), onMouseButtonDown(), onMouseDoubleClicked(), onMouseMove(), onMouseTripleClicked(), onTextChanged(), and CEGUI::Combobox::setCaratIndex().

void CEGUI::Editbox::setMaskCodePoint ( utf32  code_point  ) 

set the utf32 code point used when rendering masked text.

Parameters:
code_point utf32 code point value representing the Unicode code point that should be rendered instead of the Editbox text when rendering in masked mode.
Returns:
Nothing.

References d_maskCodePoint, and onMaskCodePointChanged().

void CEGUI::Editbox::setMaxTextLength ( size_t  max_len  ) 

set the maximum text length for this Editbox.

Parameters:
max_len The maximum number of code points (characters) that can be entered into this Editbox.
Note:
Depending on the validation string set, the actual length of text that can be entered may be less than the value set here (it will never be more).
Returns:
Nothing.

References d_maxTextLen, CEGUI::Window::d_text, isTextValid(), CEGUI::String::length(), onMaximumTextLengthChanged(), onTextChanged(), onTextInvalidatedEvent(), and CEGUI::String::resize().

Referenced by CEGUI::Combobox::setMaxTextLength().

void CEGUI::Editbox::setReadOnly ( bool  setting  ) 

Specify whether the Editbox is read-only.

Parameters:
setting true if the Editbox is read only and can't be edited by the user, false if the Editbox is not read only and may be edited by the user.
Returns:
Nothing.

References d_readOnly, and onReadOnlyChanged().

Referenced by CEGUI::Combobox::setReadOnly().

void CEGUI::Editbox::setSelection ( size_t  start_pos,
size_t  end_pos 
)

Define the current selection for the Editbox.

Parameters:
start_pos Index 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.
end_pos Index of the ending point for the selection. If this value is greater than the number of characters in the Editbox, the selection end will be set to the end of the text.
Returns:
Nothing.

References d_selectionEnd, d_selectionStart, CEGUI::Window::d_text, CEGUI::String::length(), and onTextSelectionChanged().

Referenced by clearSelection(), CEGUI::Combobox::droplist_SelectionAcceptedHandler(), handleCharLeft(), handleCharRight(), handleEnd(), handleHome(), handleWordLeft(), handleWordRight(), onMouseDoubleClicked(), onMouseMove(), onMouseTripleClicked(), CEGUI::EditboxProperties::SelectionLength::set(), CEGUI::EditboxProperties::SelectionStart::set(), and CEGUI::Combobox::setSelection().

void CEGUI::Editbox::setTextMasked ( bool  setting  ) 

Specify whether the text for the Editbox will be rendered masked.

Parameters:
setting true if the Editbox text should be rendered masked using the currently set mask code point, false if the Editbox text should be rendered as plain text.
Returns:
Nothing.

References d_maskText, and onMaskedRenderingModeChanged().

void CEGUI::Editbox::setValidationString ( const String validation_string  ) 

Set the text validation string.

Note:
Validation is performed by means of a regular expression. If the text matches the regex, the text is said to have passed validation. If the text does not match with the regex then the text fails validation.
Parameters:
validation_string String object containing the validation regex data to be used.
Returns:
Nothing.

References CEGUI::String::c_str(), CEGUI::RegexValidator::d_regex, d_validationString, d_validator, CEGUI::Window::getName(), isTextValid(), onTextInvalidatedEvent(), onValidationStringChanged(), and CEGUI::RegexValidator::release().

Referenced by Editbox(), CEGUI::Spinner::setTextInputMode(), and CEGUI::Combobox::setValidationString().

virtual bool CEGUI::Editbox::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 hierarchy.

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.

References CEGUI::Window::testClassName_impl().

virtual bool CEGUI::Editbox::validateWindowRenderer ( const String name  )  const [inline, protected, virtual]

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

Returns:
Returns true if the given WindowRenderer class name is valid for this window. False if not.

Reimplemented from CEGUI::Window.


Generated on Thu Nov 27 20:34:34 2008 for Crazy Eddies GUI System by  doxygen 1.5.7.1