1 /*********************************************************************** 2 created: 13/4/2004 3 author: Paul D Turner 4 5 purpose: Interface to base class for Editbox widget 6 *************************************************************************/ 7 /*************************************************************************** 8 * Copyright (C) 2004 - 2009 Paul D Turner & The CEGUI Development Team 9 * 10 * Permission is hereby granted, free of charge, to any person obtaining 11 * a copy of this software and associated documentation files (the 12 * "Software"), to deal in the Software without restriction, including 13 * without limitation the rights to use, copy, modify, merge, publish, 14 * distribute, sublicense, and/or sell copies of the Software, and to 15 * permit persons to whom the Software is furnished to do so, subject to 16 * the following conditions: 17 * 18 * The above copyright notice and this permission notice shall be 19 * included in all copies or substantial portions of the Software. 20 * 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 23 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 24 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 25 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 26 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 27 * OTHER DEALINGS IN THE SOFTWARE. 28 ***************************************************************************/ 29 #ifndef _CEGUIEditbox_h_ 30 #define _CEGUIEditbox_h_ 31 32 #include "CEGUI/Base.h" 33 #include "CEGUI/Window.h" 34 #include "CEGUI/RegexMatcher.h" 35 36 #if defined(_MSC_VER) 37 # pragma warning(push) 38 # pragma warning(disable : 4251) 39 #endif 40 41 // Start of CEGUI namespace section 42 namespace CEGUI 43 { 44 //! Base class for the EditboxWindowRenderer class 45 class CEGUIEXPORT EditboxWindowRenderer : public WindowRenderer 46 { 47 public: 48 //! Constructor 49 EditboxWindowRenderer(const String& name); 50 51 /*! 52 \brief 53 Return the text code point index that is rendered closest to screen 54 position \a pt. 55 56 \param pt 57 Point object describing a position on the screen in pixels. 58 59 \return 60 Code point index into the text that is rendered closest to screen 61 position \a pt. 62 */ 63 virtual size_t getTextIndexFromPosition(const Vector2f& pt) const = 0; 64 }; 65 66 //----------------------------------------------------------------------------// 67 68 //! Base class for an Editbox widget 69 class CEGUIEXPORT Editbox : public Window 70 { 71 public: 72 typedef RegexMatcher::MatchState MatchState; 73 74 //! Namespace for global events 75 static const String EventNamespace; 76 //! Window factory name 77 static const String WidgetTypeName; 78 /** Event fired when the read-only mode for the edit box is changed. 79 * Handlers are passed a const WindowEventArgs reference with 80 * WindowEventArgs::window set to the Editbox whose read only setting 81 * has been changed. 82 */ 83 static const String EventReadOnlyModeChanged; 84 /** Event fired when the masked rendering mode (password mode) is changed. 85 * Handlers are passed a const WindowEventArgs reference with 86 * WindowEventArgs::window set to the Editbox that has been put into or 87 * taken out of masked text (password) mode. 88 */ 89 static const String EventMaskedRenderingModeChanged; 90 /** Event fired whrn the code point (character) used for masked text is 91 * changed. 92 * Handlers are passed a const WindowEventArgs reference with 93 * WindowEventArgs::window set to the Editbox whose text masking codepoint 94 * has been changed. 95 */ 96 static const String EventMaskCodePointChanged; 97 /** Event fired when the validation string is changed. 98 * Handlers are passed a const WindowEventArgs reference with 99 * WindowEventArgs::window set to the Editbox whose validation string has 100 * been changed. 101 */ 102 static const String EventValidationStringChanged; 103 /** Event fired when the maximum allowable string length is changed. 104 * Handlers are passed a const WindowEventArgs reference with 105 * WindowEventArgs::window set to the Editbox whose maximum string length 106 * has been changed. 107 */ 108 static const String EventMaximumTextLengthChanged; 109 /** Event fired when the validity of the Exitbox text (as determined by a 110 * RegexMatcher object) has changed. 111 * Handlers are passed a const RegexMatchStateEventArgs reference with 112 * WindowEventArgs::window set to the Editbox whose text validity has 113 * changed and RegexMatchStateEventArgs::matchState set to the new match 114 * validity. Handler return is significant, as follows: 115 * - true indicates the new state - and therfore text - is to be accepted. 116 * - false indicates the new state is not acceptable, and the previous text 117 * should remain in place. NB: This is only possible when the validity 118 * change is due to a change in the text, if the validity change is due to 119 * a change in the validation regular expression string, then returning 120 * false will have no effect. 121 */ 122 static const String EventTextValidityChanged; 123 /** Event fired when the text caret position / insertion point is changed. 124 * Handlers are passed a const WindowEventArgs reference with 125 * WindowEventArgs::window set to the Editbox whose current insertion point 126 * has changed. 127 */ 128 static const String EventCaretMoved; 129 /** Event fired when the current text selection is changed. 130 * Handlers are passed a const WindowEventArgs reference with 131 * WindowEventArgs::window set to the Editbox whose current text selection 132 * was changed. 133 */ 134 static const String EventTextSelectionChanged; 135 /** Event fired when the number of characters in the edit box reaches the 136 * currently set maximum. 137 * Handlers are passed a const WindowEventArgs reference with 138 * WindowEventArgs::window set to the Editbox that has become full. 139 */ 140 static const String EventEditboxFull; 141 /** Event fired when the user accepts the current text by pressing Return, 142 * Enter, or Tab. 143 * Handlers are passed a const WindowEventArgs reference with 144 * WindowEventArgs::window set to the Editbox in which the user has accepted 145 * the current text. 146 */ 147 static const String EventTextAccepted; 148 149 /*! 150 \brief 151 return true if the Editbox has input focus. 152 153 \return 154 - true if the Editbox has keyboard input focus. 155 - false if the Editbox does not have keyboard input focus. 156 */ 157 bool hasInputFocus(void) const; 158 159 /*! 160 \brief 161 return true if the Editbox is read-only. 162 163 \return 164 true if the Editbox is read only and can't be edited by the user, false 165 if the Editbox is not read only and may be edited by the user. 166 */ isReadOnly(void)167 bool isReadOnly(void) const 168 {return d_readOnly;} 169 170 /*! 171 \brief 172 return true if the text for the Editbox will be rendered masked. 173 174 \return 175 true if the Editbox text will be rendered masked using the currently set 176 mask code point, false if the Editbox text will be rendered as ordinary 177 text. 178 */ isTextMasked(void)179 bool isTextMasked(void) const 180 {return d_maskText;} 181 182 /*! 183 \brief 184 return the validation MatchState for the current Editbox text, given the 185 currently set validation string. 186 187 \note 188 Validation is performed by means of a regular expression. If the text 189 matches the regex, the text is said to have passed validation. If the 190 text does not match with the regex then the text fails validation. 191 The default RegexMatcher uses the pcre library to perform regular 192 expression operations, details about the pattern syntax can be found 193 on unix-like systems by way of <tt>man pcrepattern</tt> (or online at 194 http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). 195 Alternatively, see the perl regex documentation at 196 http://perldoc.perl.org/perlre.html 197 198 \return 199 One of the MatchState enumerated values indicating the current match state. 200 */ 201 MatchState getTextMatchState() const; 202 203 /*! 204 \brief 205 return the currently set validation string 206 207 \note 208 Validation is performed by means of a regular expression. If the text 209 matches the regex, the text is said to have passed validation. If the 210 text does not match with the regex then the text fails validation. 211 The default RegexMatcher uses the pcre library to perform regular 212 expression operations, details about the pattern syntax can be found 213 on unix-like systems by way of <tt>man pcrepattern</tt> (or online at 214 http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). 215 Alternatively, see the perl regex documentation at 216 http://perldoc.perl.org/perlre.html 217 218 \return 219 String object containing the current validation regex data 220 */ getValidationString(void)221 const String& getValidationString(void) const 222 {return d_validationString;} 223 224 /*! 225 \brief 226 return the current position of the caret. 227 228 \return 229 Index of the insert caret relative to the start of the text. 230 */ 231 size_t getCaretIndex(void) const; 232 233 /*! 234 \brief 235 return the current selection start point. 236 237 \return 238 Index of the selection start point relative to the start of the text. 239 If no selection is defined this function returns the position of the 240 caret. 241 */ 242 size_t getSelectionStartIndex(void) const; 243 244 /*! 245 \brief 246 return the current selection end point. 247 248 \return 249 Index of the selection end point relative to the start of the text. If 250 no selection is defined this function returns the position of the caret. 251 */ 252 size_t getSelectionEndIndex(void) const; 253 254 /*! 255 \brief 256 return the length of the current selection (in code points / 257 characters). 258 259 \return 260 Number of code points (or characters) contained within the currently 261 defined selection. 262 */ 263 size_t getSelectionLength(void) const; 264 265 /*! 266 \brief 267 return the code point used when rendering masked text. 268 269 \return 270 utf32 or char (depends on used String class) code point value representing 271 the Unicode code point that will be rendered instead of the Editbox text 272 when rendering in masked mode. 273 */ getMaskCodePoint(void)274 String::value_type getMaskCodePoint(void) const 275 { return d_maskCodePoint; } 276 277 /*! 278 \brief 279 return the maximum text length set for this Editbox. 280 281 \return 282 The maximum number of code points (characters) that can be entered into 283 this Editbox. 284 285 \note 286 Depending on the validation string set, the actual length of text that 287 can be entered may be less than the value returned here 288 (it will never be more). 289 */ getMaxTextLength(void)290 size_t getMaxTextLength(void) const 291 {return d_maxTextLen;} 292 293 /*! 294 \brief 295 Specify whether the Editbox is read-only. 296 297 \param setting 298 true if the Editbox is read only and can't be edited by the user, false 299 if the Editbox is not read only and may be edited by the user. 300 301 \return 302 Nothing. 303 */ 304 void setReadOnly(bool setting); 305 306 /*! 307 \brief 308 Specify whether the text for the Editbox will be rendered masked. 309 310 \param setting 311 - true if the Editbox text should be rendered masked using the currently 312 set mask code point. 313 - false if the Editbox text should be rendered as ordinary text. 314 315 \return 316 Nothing. 317 */ 318 void setTextMasked(bool setting); 319 320 /*! 321 \brief 322 Set the text validation string. 323 324 \note 325 Validation is performed by means of a regular expression. If the text 326 matches the regex, the text is said to have passed validation. If the 327 text does not match with the regex then the text fails validation. 328 The default RegexMatcher uses the pcre library to perform regular 329 expression operations, details about the pattern syntax can be found 330 on unix-like systems by way of <tt>man pcrepattern</tt> (or online at 331 http://www.pcre.org/pcre.txt (scroll / search "PCREPATTERN(3)"). 332 Alternatively, see the perl regex documentation at 333 http://perldoc.perl.org/perlre.html 334 335 \param validation_string 336 String object containing the validation regex data to be used. 337 338 \return 339 Nothing. 340 */ 341 void setValidationString(const String& validation_string); 342 343 /*! 344 \brief 345 Set the current position of the caret. 346 347 \param caret_pos 348 New index for the insert caret relative to the start of the text. If 349 the value specified is greater than the number of characters in the 350 Editbox, the caret is positioned at the end of the text. 351 352 \return 353 Nothing. 354 */ 355 void setCaretIndex(size_t caret_pos); 356 357 /*! 358 \brief 359 Define the current selection for the Editbox 360 361 \param start_pos 362 Index of the starting point for the selection. If this value is greater 363 than the number of characters in the Editbox, the selection start will 364 be set to the end of the text. 365 366 \param end_pos 367 Index of the ending point for the selection. If this value is greater 368 than the number of characters in the Editbox, the selection end will be 369 set to the end of the text. 370 371 \return 372 Nothing. 373 */ 374 void setSelection(size_t start_pos, size_t end_pos); 375 376 /*! 377 \brief 378 Define the current selection start for the Editbox 379 380 \param start_pos 381 Index of the starting point for the selection. If this value is greater than the number of characters in the Editbox, the 382 selection start will be set to the end of the text. 383 384 \return 385 Nothing. 386 */ 387 void setSelectionStart(size_t start_pos); 388 389 /*! 390 \brief 391 Define the current selection for the Editbox 392 393 \param start_pos 394 Length of the selection. 395 396 \return 397 Nothing. 398 */ 399 void setSelectionLength(size_t length); 400 401 /*! 402 \brief 403 set the code point used when rendering masked text. 404 405 \param code_point 406 utf32 or char (depends on used String class) code point value representing 407 the vode point that should be rendered instead of the Editbox text when 408 rendering in masked mode. 409 410 \return 411 Nothing. 412 */ 413 void setMaskCodePoint(String::value_type code_point); 414 415 /*! 416 \brief 417 set the maximum text length for this Editbox. 418 419 \param max_len 420 The maximum number of code points (characters) that can be entered into 421 this Editbox. 422 423 \note 424 Depending on the validation string set, the actual length of text that 425 can be entered may be less than the value set here 426 (it will never be more). 427 428 \return 429 Nothing. 430 */ 431 void setMaxTextLength(size_t max_len); 432 433 /*! 434 \brief 435 Set the RegexMatcher based validator for this Editbox. 436 437 \param matcher 438 Pointer to an object that implements the RegexMatcher interface, or 0 439 to restore a system supplied RegexMatcher (if support is available). 440 441 \note 442 If the previous RegexMatcher validator is one supplied via the system, 443 it is deleted and replaced with the given RegexMatcher. User supplied 444 RegexMatcher objects will never be deleted by the system and you must 445 ensure that the object is not deleted while the Editbox holds a pointer 446 to it. Once the Editbox is destroyed or the validator is set to 447 something else it is the responsibility of client code to ensure any 448 previous custom validator is deleted. 449 */ 450 void setValidator(RegexMatcher* matcher); 451 452 //! \copydoc Window::performCopy 453 virtual bool performCopy(Clipboard& clipboard); 454 455 //! \copydoc Window::performCut 456 virtual bool performCut(Clipboard& clipboard); 457 458 //! \copydoc Window::performPaste 459 virtual bool performPaste(Clipboard& clipboard); 460 461 //! Constructor for Editbox class. 462 Editbox(const String& type, const String& name); 463 464 //! Destructor for Editbox class. 465 virtual ~Editbox(void); 466 467 protected: 468 /*! 469 \brief 470 Return the text code point index that is rendered closest to screen 471 position \a pt. 472 473 \param pt 474 Point object describing a position on the screen in pixels. 475 476 \return 477 Code point index into the text that is rendered closest to screen 478 position \a pt. 479 */ 480 size_t getTextIndexFromPosition(const Vector2f& pt) const; 481 482 //! Clear the currently defined selection (just the region, not the text). 483 void clearSelection(void); 484 485 /*! 486 \brief 487 Erase the currently selected text. 488 489 \param modify_text 490 when true, the actual text will be modified. When false, everything is 491 done except erasing the characters. 492 */ 493 void eraseSelectedText(bool modify_text = true); 494 495 /*! 496 \brief 497 return the match state of the given string for the validation regular 498 expression. 499 */ 500 MatchState getStringMatchState(const String& str) const; 501 502 /** Helper to update validator match state as needed for the given string 503 * and event handler return codes. 504 * 505 * This effectively asks permission from event handlers to proceed with the 506 * change, updates d_validatorMatchState and returns an appropriate bool. 507 * The return value basically says whether or not to set the input string 508 * as the current text for the Editbox. 509 */ 510 bool handleValidityChangeForString(const String& str); 511 512 //! Processing for backspace key 513 void handleBackspace(void); 514 515 //! Processing for Delete key 516 void handleDelete(void); 517 518 //! Processing to move caret one character left 519 void handleCharLeft(uint sysKeys); 520 521 //! Processing to move caret one word left 522 void handleWordLeft(uint sysKeys); 523 524 //! Processing to move caret one character right 525 void handleCharRight(uint sysKeys); 526 527 //! Processing to move caret one word right 528 void handleWordRight(uint sysKeys); 529 530 //! Processing to move caret to the start of the text. 531 void handleHome(uint sysKeys); 532 533 //! Processing to move caret to the end of the text 534 void handleEnd(uint sysKeys); 535 536 //! validate window renderer 537 virtual bool validateWindowRenderer(const WindowRenderer* renderer) const; 538 539 /*! 540 \brief 541 Handler called when the read only state of the Editbox has been changed. 542 */ 543 virtual void onReadOnlyChanged(WindowEventArgs& e); 544 545 /*! 546 \brief 547 Handler called when the masked rendering mode (password mode) has been 548 changed. 549 */ 550 virtual void onMaskedRenderingModeChanged(WindowEventArgs& e); 551 552 /*! 553 \brief 554 Handler called when the code point to use for masked rendering has been 555 changed. 556 */ 557 virtual void onMaskCodePointChanged(WindowEventArgs& e); 558 559 /*! 560 \brief 561 Event fired internally when the validation string is changed. 562 */ 563 virtual void onValidationStringChanged(WindowEventArgs& e); 564 565 /*! 566 \brief 567 Handler called when the maximum text length for the edit box is changed. 568 */ 569 virtual void onMaximumTextLengthChanged(WindowEventArgs& e); 570 571 /*! 572 \brief 573 Handler called when something has caused the validity state of the 574 current text to change. 575 */ 576 virtual void onTextValidityChanged(RegexMatchStateEventArgs& e); 577 578 /*! 579 \brief 580 Handler called when the caret (insert point) position changes. 581 */ 582 virtual void onCaretMoved(WindowEventArgs& e); 583 584 /*! 585 \brief 586 Handler called when the current text selection changes. 587 */ 588 virtual void onTextSelectionChanged(WindowEventArgs& e); 589 590 /*! 591 \brief 592 Handler called when the edit box text has reached the set maximum 593 length. 594 */ 595 virtual void onEditboxFullEvent(WindowEventArgs& e); 596 597 /*! 598 \brief 599 Handler called when the user accepts the edit box text by pressing 600 Return, Enter, or Tab. 601 */ 602 virtual void onTextAcceptedEvent(WindowEventArgs& e); 603 604 // Overridden event handlers 605 void onMouseButtonDown(MouseEventArgs& e); 606 void onMouseButtonUp(MouseEventArgs& e); 607 void onMouseDoubleClicked(MouseEventArgs& e); 608 void onMouseTripleClicked(MouseEventArgs& e); 609 void onMouseMove(MouseEventArgs& e); 610 void onCaptureLost(WindowEventArgs& e); 611 void onCharacter(KeyEventArgs& e); 612 void onKeyDown(KeyEventArgs& e); 613 void onTextChanged(WindowEventArgs& e); 614 615 //! True if the editbox is in read-only mode 616 bool d_readOnly; 617 //! True if the editbox text should be rendered masked. 618 bool d_maskText; 619 //! Code point to use when rendering masked text. 620 String::value_type d_maskCodePoint; 621 //! Maximum number of characters for this Editbox. 622 size_t d_maxTextLen; 623 //! Position of the caret / insert-point. 624 size_t d_caretPos; 625 //! Start of selection area. 626 size_t d_selectionStart; 627 //! End of selection area. 628 size_t d_selectionEnd; 629 //! Copy of validation reg-ex string. 630 String d_validationString; 631 //! Pointer to class used for validation of text. 632 RegexMatcher* d_validator; 633 //! specifies whether validator was created by us, or supplied by user. 634 bool d_weOwnValidator; 635 //! true when a selection is being dragged. 636 bool d_dragging; 637 //! Selection index for drag selection anchor point. 638 size_t d_dragAnchorIdx; 639 //! Current match state of EditboxText 640 MatchState d_validatorMatchState; 641 //! Previous match state change response 642 bool d_previousValidityChangeResponse; 643 644 private: 645 646 void addEditboxProperties(void); 647 }; 648 649 } // End of CEGUI namespace section 650 651 #if defined(_MSC_VER) 652 # pragma warning(pop) 653 #endif 654 655 #endif // end of guard _CEGUIEditbox_h_ 656