docs/latex/wx/text.tex

   1 \section{\class{wxTextCtrl}}\label{wxtextctrl}
   2
   3 A text control allows text to be displayed and edited. It may be
   4 single line or multi-line.
   5
   6 \wxheading{Derived from}
   7
   8 streambuf\\
   9 \helpref{wxControl}{wxcontrol}\\
  10 \helpref{wxWindow}{wxwindow}\\
  11 \helpref{wxEvtHandler}{wxevthandler}\\
  12 \helpref{wxObject}{wxobject}
  13
  14 \wxheading{Include files}
  15
  16 <wx/textctrl.h>
  17
  18 \wxheading{Window styles}
  19
  20 \twocolwidtha{5cm}
  21 \begin{twocollist}\itemsep=0pt
  22 \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
  23 the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
  24 either processed internally by the control or used for navigation between
  25 dialog controls).}
  26 \twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
  27 EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the
  28 next control in a dialog instead. For the control created with this style,
  29 you can still use Ctrl-Enter to pass to the next control from the keyboard.}
  30 \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
  31 \twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
  32 \twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
  33 \twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
  34 \end{twocollist}
  35
  36 See also \helpref{window styles overview}{windowstyles} and
  37 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
  38
  39 \wxheading{Remarks}
  40
  41 This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such as
  42 the following:
  43
  44 {\small%
  45 \begin{verbatim}
  46   wxTextCtrl *control = new wxTextCtrl(...);
  47
  48   ostream stream(control)
  49
  50   stream << 123.456 << " some text\n";
  51   stream.flush();
  52 \end{verbatim}
  53 }%
  54
  55 If your compiler does not support derivation from {\bf streambuf} and gives a compile error, define the symbol
  56 {\bf NO\_TEXT\_WINDOW\_STREAM} in the wxTextCtrl header file.
  57
  58 Note that any use of C++ iostreams (including this one) deprecated and might get completely removed
  59 in the future.
  60
  61 \wxheading{Event handling}
  62
  63 The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
  64 wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
  65 automatically, when the control has the focus.
  66
  67 To process input from a text control, use these event handler macros to direct input to member
  68 functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
  69
  70 \twocolwidtha{7cm}%
  71 \begin{twocollist}\itemsep=0pt
  72 \twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
  73 generated when the text changes. Notice that this event will always be sent
  74 when the text controls contents changes - whether this is due to user input or
  75 comes from the program itself (for example, if SetValue() is called)}
  76 \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
  77 generated when enter is pressed in a single-line text control.}
  78 \end{twocollist}%
  79
  80 %\wxheading{See also}
  81 %
  82 %\helpref{wxRichTextCtrl}{wxrichtextctrl}
  83 %
  84 \latexignore{\rtfignore{\wxheading{Members}}}
  85
  86 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
  87
  88 \func{}{wxTextCtrl}{\void}
  89
  90 Default constructor.
  91
  92 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
  93 \param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  94 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
  95
  96 Constructor, creating and showing a text control.
  97
  98 \wxheading{Parameters}
  99
 100 \docparam{parent}{Parent window. Should not be NULL.}
 101
 102 \docparam{id}{Control identifier. A value of -1 denotes a default value.}
 103
 104 \docparam{value}{Default text value.}
 105
 106 \docparam{pos}{Text control position.}
 107
 108 \docparam{size}{Text control size.}
 109
 110 \docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
 111
 112 \docparam{validator}{Window validator.}
 113
 114 \docparam{name}{Window name.}
 115
 116 \wxheading{Remarks}
 117
 118 The horizontal scrollbar ({\bf wxTE\_HSCROLL} style flag) will only be created for multi-line text controls.
 119 Without a horizontal scrollbar, text lines that don't fit in the control's
 120 size will be wrapped (but no newline character is inserted). Single line
 121 controls don't have a horizontal scrollbar, the text is automatically scrolled
 122 so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
 123 visible.
 124
 125 Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
 126 as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
 127 apply.
 128
 129 \wxheading{See also}
 130
 131 \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
 132
 133 \membersection{wxTextCtrl::\destruct{wxTextCtrl}}
 134
 135 \func{}{\destruct{wxTextCtrl}}{\void}
 136
 137 Destructor, destroying the text control.
 138
 139 \membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
 140
 141 \func{void}{AppendText}{\param{const wxString\& }{ text}}
 142
 143 Appends the text to the end of the text control.
 144
 145 \wxheading{Parameters}
 146
 147 \docparam{text}{Text to write to the text control.}
 148
 149 \wxheading{Remarks}
 150
 151 After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
 152 the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
 153
 154 \wxheading{See also}
 155
 156 \helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
 157
 158 \membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
 159
 160 \func{virtual bool}{CanCopy}{\void}
 161
 162 Returns TRUE if the selection can be copied to the clipboard.
 163
 164 \membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
 165
 166 \func{virtual bool}{CanCut}{\void}
 167
 168 Returns TRUE if the selection can be cut to the clipboard.
 169
 170 \membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
 171
 172 \func{virtual bool}{CanPaste}{\void}
 173
 174 Returns TRUE if the contents of the clipboard can be pasted into the
 175 text control. On some platforms (Motif, GTK) this is an approximation
 176 and returns TRUE if the control is editable, FALSE otherwise.
 177
 178 \membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
 179
 180 \func{virtual bool}{CanRedo}{\void}
 181
 182 Returns TRUE if there is a redo facility available and the last operation
 183 can be redone.
 184
 185 \membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
 186
 187 \func{virtual bool}{CanUndo}{\void}
 188
 189 Returns TRUE if there is an undo facility available and the last operation
 190 can be undone.
 191
 192 \membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
 193
 194 \func{virtual void}{Clear}{\void}
 195
 196 Clears the text in the control.
 197
 198 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 199
 200 \func{virtual void}{Copy}{\void}
 201
 202 Copies the selected text to the clipboard under Motif and MS Windows.
 203
 204 \membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
 205
 206 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 207 \param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 208 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
 209
 210 Creates the text control for two-step construction. Derived classes
 211 should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
 212 for further details.
 213
 214 \membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
 215
 216 \func{virtual void}{Cut}{\void}
 217
 218 Copies the selected text to the clipboard and removes the selection.
 219
 220 \membersection{wxTextCtrl::DiscardEdits}
 221
 222 \func{void}{DiscardEdits}{\void}
 223
 224 Resets the internal `modified' flag as if the current edits had been saved.
 225
 226 \membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
 227
 228 \constfunc{virtual long}{GetInsertionPoint}{\void}
 229
 230 Returns the insertion point. This is defined as the zero based index of the
 231 character position to the right of the insertion point. For example, if
 232 the insertion point is at the end of the text control, it is equal to
 233 both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
 234 \helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
 235
 236 The following code snippet safely returns the character at the insertion
 237 point or the zero character if the point is at the end of the control.
 238
 239 {\small%
 240 \begin{verbatim}
 241   char GetCurrentChar(wxTextCtrl *tc) {
 242     if (tc->GetInsertionPoint() == tc->GetLastPosition())
 243       return '\0';
 244     return tc->GetValue[tc->GetInsertionPoint()];
 245   }
 246 \end{verbatim}
 247 }%
 248
 249 \membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
 250
 251 \constfunc{virtual long}{GetLastPosition}{\void}
 252
 253 Returns the zero based index of the last position in the text control,
 254 which is equal to the number of characters in the control.
 255
 256 \membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
 257
 258 \constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
 259
 260 Gets the length of the specified line, not including any trailing newline
 261 character(s).
 262
 263 \wxheading{Parameters}
 264
 265 \docparam{lineNo}{Line number (starting from zero).}
 266
 267 \wxheading{Return value}
 268
 269 The length of the line, or -1 if {\it lineNo} was invalid.
 270
 271 \membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
 272
 273 \constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
 274
 275 Returns the contents of a given line in the text control, not including
 276 any trailing newline character(s).
 277
 278 \wxheading{Parameters}
 279
 280 \docparam{lineNo}{The line number, starting from zero.}
 281
 282 \wxheading{Return value}
 283
 284 The contents of the line.
 285
 286 \membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
 287
 288 \constfunc{int}{GetNumberOfLines}{\void}
 289
 290 Returns the number of lines in the text control buffer.
 291
 292 \wxheading{Remarks}
 293
 294 Note that even empty text controls have one line (where the insertion point
 295 is), so GetNumberOfLines() never returns 0.
 296
 297 For gtk\_text (multi-line) controls, the number of lines is
 298 calculated by actually counting newline characters in the buffer. You
 299 may wish to avoid using functions that work with line numbers if you are
 300 working with controls that contain large amounts of text.
 301
 302 \membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
 303
 304 \func{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
 305
 306 Gets the current selection span. If the returned values are equal, there was
 307 no selection.
 308
 309 \wxheading{Parameters}
 310
 311 \docparam{from}{The returned first position.}
 312
 313 \docparam{to}{The returned last position.}
 314
 315 \pythonnote{The wxPython version of this method returns a tuple
 316 consisting of the from and to values.}
 317
 318 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 319
 320 \constfunc{wxString}{GetValue}{\void}
 321
 322 Gets the contents of the control.
 323
 324 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 325
 326 \constfunc{bool}{IsModified}{\void}
 327
 328 Returns TRUE if the text has been modified.
 329
 330 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 331
 332 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 333
 334 Loads and displays the named file, if it exists.
 335
 336 \wxheading{Parameters}
 337
 338 \docparam{filename}{The filename of the file to load.}
 339
 340 \wxheading{Return value}
 341
 342 TRUE if successful, FALSE otherwise.
 343
 344 \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 345
 346 \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 347
 348 Default handler for character input.
 349
 350 \wxheading{Remarks}
 351
 352 It is possible to intercept character
 353 input by overriding this member. Call this function
 354 to let the default behaviour take place; not calling
 355 it results in the character being ignored. You can
 356 replace the {\it keyCode} member of {\it event} to
 357 translate keystrokes.
 358
 359 Note that Windows and Motif have different ways
 360 of implementing the default behaviour. In Windows,
 361 calling wxTextCtrl::OnChar immediately
 362 processes the character. In Motif,
 363 calling this function simply sets a flag
 364 to let default processing happen. This might affect
 365 the way in which you write your OnChar function
 366 on different platforms.
 367
 368 \wxheading{See also}
 369
 370 \helpref{wxKeyEvent}{wxkeyevent}
 371
 372 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 373
 374 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 375
 376 This event handler function implements default drag and drop behaviour, which
 377 is to load the first dropped file into the control.
 378
 379 \wxheading{Parameters}
 380
 381 \docparam{event}{The drop files event.}
 382
 383 \wxheading{Remarks}
 384
 385 This is not yet implemented for the GTK.
 386
 387 \wxheading{See also}
 388
 389 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 390
 391 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 392
 393 \func{virtual void}{Paste}{\void}
 394
 395 Pastes text from the clipboard to the text item.
 396
 397 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 398
 399 \constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 400
 401 Converts given position to a zero-based column, line number pair.
 402
 403 \wxheading{Parameters}
 404
 405 \docparam{pos}{Position.}
 406
 407 \docparam{x}{Receives zero based column number.}
 408
 409 \docparam{y}{Receives zero based line number.}
 410
 411 \wxheading{Return value}
 412
 413 TRUE on success, FALSE on failure (most likely due to a too large position
 414 parameter).
 415
 416 \wxheading{See also}
 417
 418 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 419
 420 \pythonnote{In Python, PositionToXY() returns a tuple containing the x and
 421 y values, so (x,y) = PositionToXY() is equivalent to the call described
 422 above.}
 423
 424 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 425
 426 \func{virtual void}{Redo}{\void}
 427
 428 If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
 429 if there is no redo facility.
 430
 431 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 432
 433 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 434
 435 Removes the text starting at the first given position up to (but not including)
 436 the character at the last position.
 437
 438 \wxheading{Parameters}
 439
 440 \docparam{from}{The first position.}
 441
 442 \docparam{to}{The last position.}
 443
 444 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 445
 446 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 447
 448 Replaces the text starting at the first position up to (but not including)
 449 the character at the last position with the given text.
 450
 451 \wxheading{Parameters}
 452
 453 \docparam{from}{The first position.}
 454
 455 \docparam{to}{The last position.}
 456
 457 \docparam{value}{The value to replace the existing text with.}
 458
 459 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 460
 461 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
 462
 463 Saves the contents of the control in a text file.
 464
 465 \wxheading{Parameters}
 466
 467 \docparam{filename}{The name of the file in which to save the text.}
 468
 469 \wxheading{Return value}
 470
 471 TRUE if the operation was successful, FALSE otherwise.
 472
 473 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 474
 475 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 476
 477 Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY}
 478 flag.
 479
 480 \wxheading{Parameters}
 481
 482 \docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
 483
 484 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 485
 486 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 487
 488 Sets the insertion point at the given position.
 489
 490 \wxheading{Parameters}
 491
 492 \docparam{pos}{Position to set.}
 493
 494 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 495
 496 \func{virtual void}{SetInsertionPointEnd}{\void}
 497
 498 Sets the insertion point at the end of the text control. This is equivalent
 499 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 500
 501 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 502
 503 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 504
 505 Selects the text starting at the first position up to (but not including) the character at the last position.
 506
 507 \wxheading{Parameters}
 508
 509 \docparam{from}{The first position.}
 510
 511 \docparam{to}{The last position.}
 512
 513 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 514
 515 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 516
 517 Sets the text value.
 518
 519 \wxheading{Parameters}
 520
 521 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 522
 523 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
 524
 525 \func{void}{ShowPosition}{\param{long}{ pos}}
 526
 527 Makes the line containing the given position visible.
 528
 529 \wxheading{Parameters}
 530
 531 \docparam{pos}{The position that should be visible.}
 532
 533 \membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
 534
 535 \func{virtual void}{Undo}{\void}
 536
 537 If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
 538 if there is no undo facility.
 539
 540 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
 541
 542 \func{void}{WriteText}{\param{const wxString\& }{ text}}
 543
 544 Writes the text into the text control at the current insertion position.
 545
 546 \wxheading{Parameters}
 547
 548 \docparam{text}{Text to write to the text control.}
 549
 550 \wxheading{Remarks}
 551
 552 Newlines in the text string
 553 are the only control characters allowed, and they will cause appropriate
 554 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
 555
 556 After the write operation, the insertion point will be at the end of the inserted text, so subsequent write operations will be appended. To append text after the user may have interacted with the control, call \helpref{wxTextCtrl::SetInsertionPointEnd}{wxtextctrlsetinsertionpointend} before writing.
 557
 558 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
 559
 560 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
 561
 562 Converts the given zero based column and line number to a position.
 563
 564 \wxheading{Parameters}
 565
 566 \docparam{x}{The column number.}
 567
 568 \docparam{y}{The line number.}
 569
 570 \wxheading{Return value}
 571
 572 The position value.
 573
 574 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
 575
 576 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
 577
 578 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
 579
 580 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
 581
 582 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
 583
 584 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
 585
 586 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
 587
 588 Operator definitions for appending to a text control, for example:
 589
 590 \begin{verbatim}
 591   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
 592
 593   (*wnd) << "Welcome to text control number " << 1 << ".\n";
 594 \end{verbatim}
 595