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