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

Base class for an Editbox widget. More...

+ Inheritance diagram for CEGUI::Editbox:
+ Collaboration diagram for CEGUI::Editbox:

List of all members.

Public Types

typedef RegexMatcher::MatchState MatchState

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.
MatchState getTextMatchState () const
 return the validation MatchState for the current Editbox text, given the currently set validation string.
const StringgetValidationString (void) const
 return the currently set validation string
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).
String::value_type getMaskCodePoint (void) const
 return the 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 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 Editbox.
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 setMaskCodePoint (String::value_type code_point)
 set the code point used when rendering masked text.
void setMaxTextLength (size_t max_len)
 set the maximum text length for this Editbox.
void setValidator (RegexMatcher *matcher)
 Set the RegexMatcher based validator for this Editbox.
virtual bool performCopy (Clipboard &clipboard)
virtual bool performCut (Clipboard &clipboard)
virtual bool performPaste (Clipboard &clipboard)
 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
static const String EventMaskedRenderingModeChanged
static const String EventMaskCodePointChanged
static const String EventValidationStringChanged
static const String EventMaximumTextLengthChanged
static const String EventTextValidityChanged
static const String EventCaretMoved
static const String EventTextSelectionChanged
static const String EventEditboxFull
static const String EventTextAccepted

Protected Member Functions

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 currently defined selection (just the region, not the text).
void eraseSelectedText (bool modify_text=true)
 Erase the currently selected text.
MatchState getStringMatchState (const String &str) const
 return the match state of the given string for the validation regular expression.
bool handleValidityChangeForString (const String &str)
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 handleHome (uint sysKeys)
 Processing to move caret to the start of the text.
void handleEnd (uint sysKeys)
 Processing to move caret to the end of the text.
virtual bool validateWindowRenderer (const WindowRenderer *renderer) const
 validate window renderer
virtual void onReadOnlyChanged (WindowEventArgs &e)
 Handler called when the read only state of the Editbox has been changed.
virtual void onMaskedRenderingModeChanged (WindowEventArgs &e)
 Handler called when the masked rendering mode (password mode) has been changed.
virtual void onMaskCodePointChanged (WindowEventArgs &e)
 Handler called 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)
 Handler called when the maximum text length for the edit box is changed.
virtual void onTextValidityChanged (RegexMatchStateEventArgs &e)
 Handler called when something has caused the validity state of the current text to change.
virtual void onCaretMoved (WindowEventArgs &e)
 Handler called when the caret (insert point) position changes.
virtual void onTextSelectionChanged (WindowEventArgs &e)
 Handler called when the current text selection changes.
virtual void onEditboxFullEvent (WindowEventArgs &e)
 Handler called when the edit box text has reached the set maximum length.
virtual void onTextAcceptedEvent (WindowEventArgs &e)
 Handler called when the user accepts the edit box text by pressing Return, Enter, or Tab.
void onMouseButtonDown (MouseEventArgs &e)
 Handler called when a mouse button has been depressed within this window's area.
void onMouseButtonUp (MouseEventArgs &e)
 Handler called when a mouse button has been released within this window's area.
void onMouseDoubleClicked (MouseEventArgs &e)
 Handler called when a mouse button has been double-clicked within this window's area.
void onMouseTripleClicked (MouseEventArgs &e)
 Handler called when a mouse button has been triple-clicked within this window's area.
void onMouseMove (MouseEventArgs &e)
 Handler called when the mouse cursor has been moved within this window's area.
void onCaptureLost (WindowEventArgs &e)
 Handler called when this window loses capture of mouse inputs.
void onCharacter (KeyEventArgs &e)
 Handler called when a character-key has been pressed while this window has input focus.
void onKeyDown (KeyEventArgs &e)
 Handler called when a key as been depressed while this window has input focus.
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.
String::value_type d_maskCodePoint
 Code point to use when rendering masked text.
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.
String d_validationString
 Copy of validation reg-ex string.
RegexMatcherd_validator
 Pointer to class used for validation of text.
bool d_weOwnValidator
 specifies whether validator was created by us, or supplied by user.
bool d_dragging
 true when a selection is being dragged.
size_t d_dragAnchorIdx
 Selection index for drag selection anchor point.
MatchState d_validatorMatchState
 Current match state of EditboxText.
bool d_previousValidityChangeResponse
 Previous match state change response.

Detailed Description

Base class for an Editbox widget.


Member Function Documentation

void CEGUI::Editbox::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.
size_t CEGUI::Editbox::getCaretIndex ( void  ) const

return the current position of the caret.

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

return the code point used when rendering masked text.

Returns:
utf32 or char (depends on used String class) code point value representing the Unicode code point that will be rendered instead of the Editbox text when rendering in masked mode.
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).
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 caret.
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.
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 caret.
size_t CEGUI::Editbox::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 the validation MatchState for the current Editbox text, given 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. The default RegexMatcher uses the pcre library to perform regular expression operations, details about the pattern syntax can be found on unix-like systems by way of man pcrepattern (or online at http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). Alternatively, see the perl regex documentation at http://perldoc.perl.org/perlre.html
Returns:
One of the MatchState enumerated values indicating the current match state.
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. The default RegexMatcher uses the pcre library to perform regular expression operations, details about the pattern syntax can be found on unix-like systems by way of man pcrepattern (or online at http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). Alternatively, see the perl regex documentation at http://perldoc.perl.org/perlre.html
Returns:
String object containing the current validation regex data
bool CEGUI::Editbox::handleValidityChangeForString ( const String str) [protected]

Helper to update validator match state as needed for the given string and event handler return codes.

This effectively asks permission from event handlers to proceed with the change, updates d_validatorMatchState and returns an appropriate bool. The return value basically says whether or not to set the input string as the current text for the Editbox.

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

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

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

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

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

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

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

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

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

set the code point used when rendering masked text.

Parameters:
code_pointutf32 or char (depends on used String class) code point value representing the vode point that should be rendered instead of the Editbox text when rendering in masked mode.
Returns:
Nothing.
void CEGUI::Editbox::setMaxTextLength ( size_t  max_len)

set the maximum text length for this Editbox.

Parameters:
max_lenThe 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.
void CEGUI::Editbox::setReadOnly ( bool  setting)

Specify whether the Editbox is read-only.

Parameters:
settingtrue 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.
void CEGUI::Editbox::setSelection ( size_t  start_pos,
size_t  end_pos 
)

Define the current selection 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.
end_posIndex 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.
void CEGUI::Editbox::setSelectionLength ( size_t  length)

Define the current selection for the Editbox.

Parameters:
start_posLength of the selection.
Returns:
Nothing.
void CEGUI::Editbox::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.
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 ordinary text.
Returns:
Nothing.
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. The default RegexMatcher uses the pcre library to perform regular expression operations, details about the pattern syntax can be found on unix-like systems by way of man pcrepattern (or online at http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). Alternatively, see the perl regex documentation at http://perldoc.perl.org/perlre.html
Parameters:
validation_stringString object containing the validation regex data to be used.
Returns:
Nothing.

Set the RegexMatcher based validator for this Editbox.

Parameters:
matcherPointer to an object that implements the RegexMatcher interface, or 0 to restore a system supplied RegexMatcher (if support is available).
Note:
If the previous RegexMatcher validator is one supplied via the system, it is deleted and replaced with the given RegexMatcher. User supplied RegexMatcher objects will never be deleted by the system and you must ensure that the object is not deleted while the Editbox holds a pointer to it. Once the Editbox is destroyed or the validator is set to something else it is the responsibility of client code to ensure any previous custom validator is deleted.

Member Data Documentation

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

Event fired when the number of characters in the edit box reaches the currently set maximum. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox that has become full.

Event fired whrn the code point (character) used for masked text is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox whose text masking codepoint has been changed.

Event fired when the masked rendering mode (password mode) is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox that has been put into or taken out of masked text (password) mode.

Event fired when the maximum allowable string length is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox whose maximum string length has been changed.

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

Event fired when the user accepts the current text by pressing Return, Enter, or Tab. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox in which the user has accepted the current text.

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

Event fired when the validity of the Exitbox text (as determined by a RegexMatcher object) has changed. Handlers are passed a const RegexMatchStateEventArgs reference with WindowEventArgs::window set to the Editbox whose text validity has changed and RegexMatchStateEventArgs::matchState set to the new match validity. Handler return is significant, as follows:

  • true indicates the new state - and therfore text - is to be accepted.
  • false indicates the new state is not acceptable, and the previous text should remain in place. NB: This is only possible when the validity change is due to a change in the text, if the validity change is due to a change in the validation regular expression string, then returning false will have no effect.

Event fired when the validation string is changed. Handlers are passed a const WindowEventArgs reference with WindowEventArgs::window set to the Editbox whose validation string has been changed.

 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends