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 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 306
 307 \constfunc{wxString}{GetValue}{\void}
 308
 309 Gets the contents of the control.
 310
 311 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 312
 313 \constfunc{bool}{IsModified}{\void}
 314
 315 Returns TRUE if the text has been modified.
 316
 317 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 318
 319 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 320
 321 Loads and displays the named file, if it exists.
 322
 323 \wxheading{Parameters}
 324
 325 \docparam{filename}{The filename of the file to load.}
 326
 327 \wxheading{Return value}
 328
 329 TRUE if successful, FALSE otherwise.
 330
 331 \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 332
 333 \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 334
 335 Default handler for character input.
 336
 337 \wxheading{Remarks}
 338
 339 It is possible to intercept character
 340 input by overriding this member. Call this function
 341 to let the default behaviour take place; not calling
 342 it results in the character being ignored. You can
 343 replace the {\it keyCode} member of {\it event} to
 344 translate keystrokes.
 345
 346 Note that Windows and Motif have different ways
 347 of implementing the default behaviour. In Windows,
 348 calling wxTextCtrl::OnChar immediately
 349 processes the character. In Motif,
 350 calling this function simply sets a flag
 351 to let default processing happen. This might affect
 352 the way in which you write your OnChar function
 353 on different platforms.
 354
 355 \wxheading{See also}
 356
 357 \helpref{wxKeyEvent}{wxkeyevent}
 358
 359 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 360
 361 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 362
 363 This event handler function implements default drag and drop behaviour, which
 364 is to load the first dropped file into the control.
 365
 366 \wxheading{Parameters}
 367
 368 \docparam{event}{The drop files event.}
 369
 370 \wxheading{Remarks}
 371
 372 This is not yet implemented for the GTK.
 373
 374 \wxheading{See also}
 375
 376 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 377
 378 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 379
 380 \func{virtual void}{Paste}{\void}
 381
 382 Pastes text from the clipboard to the text item.
 383
 384 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 385
 386 \constfunc{long}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 387
 388 Converts given position to a zero-based column, line number pair.
 389
 390 \wxheading{Parameters}
 391
 392 \docparam{pos}{Position.}
 393
 394 \docparam{x}{Receives zero based column number.}
 395
 396 \docparam{y}{Receives zero based line number.}
 397
 398 \wxheading{Return value}
 399
 400 Non-zero on success, zero on failure (most likely due to a too large position
 401 parameter).
 402
 403 \wxheading{See also}
 404
 405 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 406
 407 \pythonnote{In Python, PositionToXY() returns a tuple containing the x and
 408 y values, so (x,y) = PositionToXY() is equivalent to the call described
 409 above.}
 410
 411 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 412
 413 \func{virtual void}{Redo}{\void}
 414
 415 If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
 416 if there is no redo facility.
 417
 418 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 419
 420 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 421
 422 Removes the text starting at the first given position up to (but not including)
 423 the character at the last position.
 424
 425 \wxheading{Parameters}
 426
 427 \docparam{from}{The first position.}
 428
 429 \docparam{to}{The last position.}
 430
 431 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 432
 433 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 434
 435 Replaces the text starting at the first position up to (but not including)
 436 the character at the last position with the given text.
 437
 438 \wxheading{Parameters}
 439
 440 \docparam{from}{The first position.}
 441
 442 \docparam{to}{The last position.}
 443
 444 \docparam{value}{The value to replace the existing text with.}
 445
 446 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 447
 448 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
 449
 450 Saves the contents of the control in a text file.
 451
 452 \wxheading{Parameters}
 453
 454 \docparam{filename}{The name of the file in which to save the text.}
 455
 456 \wxheading{Return value}
 457
 458 TRUE if the operation was successful, FALSE otherwise.
 459
 460 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 461
 462 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 463
 464 Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY}
 465 flag.
 466
 467 \wxheading{Parameters}
 468
 469 \docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
 470
 471 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 472
 473 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 474
 475 Sets the insertion point at the given position.
 476
 477 \wxheading{Parameters}
 478
 479 \docparam{pos}{Position to set.}
 480
 481 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 482
 483 \func{virtual void}{SetInsertionPointEnd}{\void}
 484
 485 Sets the insertion point at the end of the text control. This is equivalent
 486 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 487
 488 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 489
 490 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 491
 492 Selects the text starting at the first position up to (but not including) the character at the last position.
 493
 494 \wxheading{Parameters}
 495
 496 \docparam{from}{The first position.}
 497
 498 \docparam{to}{The last position.}
 499
 500 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 501
 502 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 503
 504 Sets the text value.
 505
 506 \wxheading{Parameters}
 507
 508 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 509
 510 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
 511
 512 \func{void}{ShowPosition}{\param{long}{ pos}}
 513
 514 Makes the line containing the given position visible.
 515
 516 \wxheading{Parameters}
 517
 518 \docparam{pos}{The position that should be visible.}
 519
 520 \membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
 521
 522 \func{virtual void}{Undo}{\void}
 523
 524 If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
 525 if there is no undo facility.
 526
 527 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
 528
 529 \func{void}{WriteText}{\param{const wxString\& }{ text}}
 530
 531 Writes the text into the text control at the current insertion position.
 532
 533 \wxheading{Parameters}
 534
 535 \docparam{text}{Text to write to the text control.}
 536
 537 \wxheading{Remarks}
 538
 539 Newlines in the text string
 540 are the only control characters allowed, and they will cause appropriate
 541 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
 542
 543 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.
 544
 545 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
 546
 547 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
 548
 549 Converts the given zero based column and line number to a position.
 550
 551 \wxheading{Parameters}
 552
 553 \docparam{x}{The column number.}
 554
 555 \docparam{y}{The line number.}
 556
 557 \wxheading{Return value}
 558
 559 The position value.
 560
 561 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
 562
 563 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
 564
 565 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
 566
 567 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
 568
 569 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
 570
 571 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
 572
 573 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
 574
 575 Operator definitions for appending to a text control, for example:
 576
 577 \begin{verbatim}
 578   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
 579
 580   (*wnd) << "Welcome to text control number " << 1 << ".\n";
 581 \end{verbatim}
 582