1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: wx/textentry.h 3 // Purpose: interface of wxTextEntry 4 // Author: Vadim Zeitlin 5 // Created: 2009-03-01 (extracted from wx/textctrl.h) 6 // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwindows.org> 7 // Licence: wxWindows licence 8 ///////////////////////////////////////////////////////////////////////////// 9 10 11 /** 12 wxTextPos is a position in the text 13 */ 14 typedef long wxTextPos; 15 16 17 /** 18 @class wxTextEntry 19 20 Common base class for single line text entry fields. 21 22 This class is not a control itself, as it doesn't derive from wxWindow. 23 Instead it is used as a base class by other controls, notably wxTextCtrl 24 and wxComboBox and gathers the methods common to both of them. 25 26 @library{wxcore} 27 @category{ctrl} 28 29 @see wxTextCtrl, wxComboBox 30 31 @since 2.9.0 32 */ 33 class wxTextEntry 34 { 35 public: 36 /** 37 Appends the text to the end of the text control. 38 39 @param text 40 Text to write to the text control. 41 42 @remarks 43 After the text is appended, the insertion point will be at the 44 end of the text control. If this behaviour is not desired, the 45 programmer should use GetInsertionPoint() and SetInsertionPoint(). 46 47 @see WriteText() 48 */ 49 virtual void AppendText(const wxString& text); 50 51 /** 52 Call this function to enable auto-completion of the text typed in a 53 single-line text control using the given @a choices. 54 55 Notice that currently this function is only implemented in wxGTK2, 56 wxMSW and wxOSX/Cocoa (for wxTextCtrl only, but not for wxComboBox) 57 ports and does nothing under the other platforms. 58 59 @since 2.9.0 60 61 @return 62 @true if the auto-completion was enabled or @false if the operation 63 failed, typically because auto-completion is not supported by the 64 current platform. 65 66 @see AutoCompleteFileNames() 67 */ 68 bool AutoComplete(const wxArrayString& choices); 69 70 /** 71 Enable auto-completion using the provided completer object. 72 73 This method should be used instead of AutoComplete() overload taking 74 the array of possible completions if the total number of strings is too 75 big as it allows returning the completions dynamically, depending on 76 the text already entered by user and so is more efficient. 77 78 The specified @a completer object will be used to retrieve the list of 79 possible completions for the already entered text and will be deleted 80 by wxTextEntry itself when it's not needed any longer. 81 82 Notice that you need to include @c wx/textcompleter.h in order to 83 define your class inheriting from wxTextCompleter. 84 85 Currently this method is only implemented in wxMSW and wxOSX/Cocoa (for 86 wxTextCtrl only, but not for wxComboBox). 87 88 @since 2.9.2 89 90 @param completer 91 The object to be used for generating completions if non-@NULL. If 92 it is @NULL, auto-completion is disabled. The wxTextEntry object 93 takes ownership of this pointer and will delete it in any case 94 (i.e. even if this method returns @false). 95 96 @return 97 @true if the auto-completion was enabled or @false if the operation 98 failed, typically because auto-completion is not supported by the 99 current platform. 100 101 @see wxTextCompleter 102 */ 103 bool AutoComplete(wxTextCompleter *completer); 104 105 /** 106 Call this function to enable auto-completion of the text typed in a 107 single-line text control using all valid file system paths. 108 109 Notice that currently this function is only implemented in wxMSW port 110 and does nothing under the other platforms. 111 112 @since 2.9.0 113 114 @return 115 @true if the auto-completion was enabled or @false if the operation 116 failed, typically because auto-completion is not supported by the 117 current platform. 118 119 @see AutoComplete() 120 */ 121 bool AutoCompleteFileNames(); 122 123 /** 124 Call this function to enable auto-completion of the text using the file 125 system directories. 126 127 Unlike AutoCompleteFileNames() which completes both file names and 128 directories, this function only completes the directory names. 129 130 Notice that currently this function is only implemented in wxMSW port 131 and does nothing under the other platforms. 132 133 @since 2.9.3 134 135 @return 136 @true if the auto-completion was enabled or @false if the operation 137 failed, typically because auto-completion is not supported by the 138 current platform. 139 140 @see AutoComplete() 141 */ 142 bool AutoCompleteDirectories(); 143 144 /** 145 Returns @true if the selection can be copied to the clipboard. 146 */ 147 virtual bool CanCopy() const; 148 149 /** 150 Returns @true if the selection can be cut to the clipboard. 151 */ 152 virtual bool CanCut() const; 153 154 /** 155 Returns @true if the contents of the clipboard can be pasted into the 156 text control. 157 158 On some platforms (Motif, GTK) this is an approximation and returns 159 @true if the control is editable, @false otherwise. 160 */ 161 virtual bool CanPaste() const; 162 163 /** 164 Returns @true if there is a redo facility available and the last 165 operation can be redone. 166 */ 167 virtual bool CanRedo() const; 168 169 /** 170 Returns @true if there is an undo facility available and the last 171 operation can be undone. 172 */ 173 virtual bool CanUndo() const; 174 175 /** 176 Sets the new text control value. 177 178 It also marks the control as not-modified which means that IsModified() 179 would return @false immediately after the call to ChangeValue(). 180 181 The insertion point is set to the start of the control (i.e. position 182 0) by this function. 183 184 This functions does not generate the @c wxEVT_TEXT 185 event but otherwise is identical to SetValue(). 186 187 See @ref overview_events_prog for more information. 188 189 @since 2.7.1 190 191 @param value 192 The new value to set. It may contain newline characters if the text 193 control is multi-line. 194 */ 195 virtual void ChangeValue(const wxString& value); 196 197 /** 198 Clears the text in the control. 199 200 Note that this function will generate a @c wxEVT_TEXT 201 event, i.e. its effect is identical to calling @c SetValue(""). 202 */ 203 virtual void Clear(); 204 205 /** 206 Copies the selected text to the clipboard. 207 */ 208 virtual void Copy(); 209 210 /** 211 Copies the selected text to the clipboard and removes it from the control. 212 */ 213 virtual void Cut(); 214 215 /** 216 Returns the insertion point, or cursor, position. 217 218 This is defined as the zero based index of the character position to 219 the right of the insertion point. For example, if the insertion point 220 is at the end of the single-line text control, it is equal to 221 GetLastPosition(). 222 223 Notice that insertion position is, in general, different from the index 224 of the character the cursor position at in the string returned by 225 GetValue(). While this is always the case for the single line controls, 226 multi-line controls can use two characters @c "\\r\\n" as line 227 separator (this is notably the case under MSW) meaning that indices in 228 the control and its string value are offset by 1 for every line. 229 230 Hence to correctly get the character at the current cursor position, 231 taking into account that there can be none if the cursor is at the end 232 of the string, you could do the following: 233 234 @code 235 wxString GetCurrentChar(wxTextCtrl *tc) 236 { 237 long pos = tc->GetInsertionPoint(); 238 if ( pos == tc->GetLastPosition() ) 239 return wxString(); 240 241 return tc->GetRange(pos, pos + 1); 242 } 243 @endcode 244 */ 245 virtual long GetInsertionPoint() const; 246 247 /** 248 Returns the zero based index of the last position in the text control, 249 which is equal to the number of characters in the control. 250 */ 251 virtual wxTextPos GetLastPosition() const; 252 253 /** 254 Returns the string containing the text starting in the positions 255 @a from and up to @a to in the control. 256 257 The positions must have been returned by another wxTextCtrl method. 258 Please note that the positions in a multiline wxTextCtrl do @b not 259 correspond to the indices in the string returned by GetValue() because 260 of the different new line representations (@c CR or @c CR LF) and so 261 this method should be used to obtain the correct results instead of 262 extracting parts of the entire value. It may also be more efficient, 263 especially if the control contains a lot of data. 264 */ 265 virtual wxString GetRange(long from, long to) const; 266 267 /** 268 Gets the current selection span. 269 270 If the returned values are equal, there was no selection. Please note 271 that the indices returned may be used with the other wxTextCtrl methods 272 but don't necessarily represent the correct indices into the string 273 returned by GetValue() for multiline controls under Windows (at least,) 274 you should use GetStringSelection() to get the selected text. 275 276 @param from 277 The returned first position. 278 @param to 279 The returned last position. 280 281 @beginWxPerlOnly 282 In wxPerl this method takes no parameters and returns a 283 2-element list (from, to). 284 @endWxPerlOnly 285 */ 286 virtual void GetSelection(long* from, long* to) const; 287 288 /** 289 Gets the text currently selected in the control. 290 291 If there is no selection, the returned string is empty. 292 */ 293 virtual wxString GetStringSelection() const; 294 295 /** 296 Gets the contents of the control. 297 298 Notice that for a multiline text control, the lines will be separated 299 by (Unix-style) @c \\n characters, even under Windows where they are 300 separated by a @c \\r\\n sequence in the native control. 301 */ 302 virtual wxString GetValue() const; 303 304 /** 305 Returns @true if the controls contents may be edited by user (note that 306 it always can be changed by the program). 307 308 In other words, this functions returns @true if the control hasn't been 309 put in read-only mode by a previous call to SetEditable(). 310 */ 311 virtual bool IsEditable() const; 312 313 /** 314 Returns @true if the control is currently empty. 315 316 This is the same as @c GetValue().empty() but can be much more 317 efficient for the multiline controls containing big amounts of text. 318 319 @since 2.7.1 320 */ 321 virtual bool IsEmpty() const; 322 323 /** 324 Pastes text from the clipboard to the text item. 325 */ 326 virtual void Paste(); 327 328 /** 329 If there is a redo facility and the last operation can be redone, 330 redoes the last operation. 331 332 Does nothing if there is no redo facility. 333 */ 334 virtual void Redo(); 335 336 /** 337 Removes the text starting at the first given position up to 338 (but not including) the character at the last position. 339 340 This function puts the current insertion point position at @a to as a 341 side effect. 342 343 @param from 344 The first position. 345 @param to 346 The last position. 347 */ 348 virtual void Remove(long from, long to); 349 350 /** 351 Replaces the text starting at the first position up to 352 (but not including) the character at the last position with the given text. 353 354 This function puts the current insertion point position at @a to as a 355 side effect. 356 357 @param from 358 The first position. 359 @param to 360 The last position. 361 @param value 362 The value to replace the existing text with. 363 */ 364 virtual void Replace(long from, long to, const wxString& value); 365 366 /** 367 Makes the text item editable or read-only, overriding the 368 @b wxTE_READONLY flag. 369 370 @param editable 371 If @true, the control is editable. If @false, the control is 372 read-only. 373 374 @see IsEditable() 375 */ 376 virtual void SetEditable(bool editable); 377 378 /** 379 Sets the insertion point at the given position. 380 381 @param pos 382 Position to set, in the range from 0 to GetLastPosition() inclusive. 383 */ 384 virtual void SetInsertionPoint(long pos); 385 386 /** 387 Sets the insertion point at the end of the text control. 388 389 This is equivalent to calling wxTextCtrl::SetInsertionPoint() with 390 wxTextCtrl::GetLastPosition() argument. 391 */ 392 virtual void SetInsertionPointEnd(); 393 394 /** 395 This function sets the maximum number of characters the user can enter 396 into the control. 397 398 In other words, it allows limiting the text value length to @a len not 399 counting the terminating @c NUL character. 400 401 If @a len is 0, the previously set max length limit, if any, is discarded 402 and the user may enter as much text as the underlying native text control widget 403 supports (typically at least 32Kb). 404 If the user tries to enter more characters into the text control when it 405 already is filled up to the maximal length, a @c wxEVT_TEXT_MAXLEN 406 event is sent to notify the program about it (giving it the possibility 407 to show an explanatory message, for example) and the extra input is discarded. 408 409 Note that in wxGTK this function may only be used with single line text controls. 410 */ 411 virtual void SetMaxLength(unsigned long len); 412 413 /** 414 Selects the text starting at the first position up to (but not 415 including) the character at the last position. 416 417 If both parameters are equal to -1 all text in the control is selected. 418 419 Notice that the insertion point will be moved to @a from by this 420 function. 421 422 @param from 423 The first position. 424 @param to 425 The last position. 426 427 @see SelectAll() 428 */ 429 virtual void SetSelection(long from, long to); 430 431 /** 432 Selects all text in the control. 433 434 @see SetSelection() 435 */ 436 virtual void SelectAll(); 437 438 /** 439 Deselects selected text in the control. 440 441 @since 2.9.5 442 */ 443 virtual void SelectNone(); 444 445 /** 446 Sets a hint shown in an empty unfocused text control. 447 448 The hints are usually used to indicate to the user what is supposed to 449 be entered into the given entry field, e.g. a common use of them is to 450 show an explanation of what can be entered in a wxSearchCtrl. 451 452 The hint is shown (usually greyed out) for an empty control until it 453 gets focus and is shown again if the control loses it and remains 454 empty. It won't be shown once the control has a non-empty value, 455 although it will be shown again if the control contents is cleared. 456 Because of this, it generally only makes sense to use hints with the 457 controls which are initially empty. 458 459 Notice that hints are known as <em>cue banners</em> under MSW or 460 <em>placeholder strings</em> under OS X. 461 462 @remarks For the platforms without native hints support (and currently 463 only the MSW port does have it and even there it is only used under 464 Windows Vista and later only), the implementation has several known 465 limitations. Notably, the hint display will not be properly updated 466 if you change wxTextEntry contents programmatically when the hint 467 is displayed using methods other than SetValue() or ChangeValue() 468 or others which use them internally (e.g. Clear()). In other words, 469 currently you should avoid calling methods such as WriteText() or 470 Replace() when using hints and the text control is empty. 471 472 @remarks Hints can only be used for single line text controls, 473 native multi-line text controls don't support hints under any 474 platform and hence wxWidgets doesn't provide them neither. 475 476 @since 2.9.0 477 */ 478 virtual bool SetHint(const wxString& hint); 479 480 /** 481 Returns the current hint string. 482 483 See SetHint() for more information about hints. 484 485 @since 2.9.0 486 */ 487 virtual wxString GetHint() const; 488 489 //@{ 490 /** 491 Attempts to set the control margins. When margins are given as wxPoint, 492 x indicates the left and y the top margin. Use -1 to indicate that 493 an existing value should be used. 494 495 @return 496 @true if setting of all requested margins was successful. 497 498 @since 2.9.1 499 */ 500 bool SetMargins(const wxPoint& pt); 501 bool SetMargins(wxCoord left, wxCoord top = -1); 502 //@} 503 504 /** 505 Returns the margins used by the control. The @c x field of the returned 506 point is the horizontal margin and the @c y field is the vertical one. 507 508 @remarks If given margin cannot be accurately determined, its value 509 will be set to -1. On some platforms you cannot obtain valid 510 margin values until you have called SetMargins(). 511 512 @see SetMargins() 513 514 @since 2.9.1 515 */ 516 wxPoint GetMargins() const; 517 518 /** 519 Sets the new text control value. 520 521 It also marks the control as not-modified which means that IsModified() 522 would return @false immediately after the call to SetValue(). 523 524 The insertion point is set to the start of the control (i.e. position 525 0) by this function. 526 527 Note that, unlike most other functions changing the controls values, 528 this function generates a @c wxEVT_TEXT event. To avoid 529 this you can use ChangeValue() instead. 530 531 @param value 532 The new value to set. It may contain newline characters if the text 533 control is multi-line. 534 */ 535 virtual void SetValue(const wxString& value); 536 537 /** 538 If there is an undo facility and the last operation can be undone, 539 undoes the last operation. 540 541 Does nothing if there is no undo facility. 542 */ 543 virtual void Undo(); 544 545 /** 546 Writes the text into the text control at the current insertion position. 547 548 @param text 549 Text to write to the text control. 550 551 @remarks 552 Newlines in the text string are the only control characters 553 allowed, and they will cause appropriate line breaks. 554 See operator<<() and AppendText() for more convenient ways of 555 writing to the window. 556 After the write operation, the insertion point will be at the end 557 of the inserted text, so subsequent write operations will be appended. 558 To append text after the user may have interacted with the control, 559 call wxTextCtrl::SetInsertionPointEnd() before writing. 560 */ 561 virtual void WriteText(const wxString& text); 562 }; 563