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