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