docs/latex/wx/text.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3 \section{\class{wxTextCtrl}}\label{wxtextctrl}
   4
   5 A text control allows text to be displayed and edited. It may be
   6 single line or multi-line.
   7
   8 \wxheading{Derived from}
   9
  10 streambuf\\
  11 \helpref{wxControl}{wxcontrol}\\
  12 \helpref{wxWindow}{wxwindow}\\
  13 \helpref{wxEvtHandler}{wxevthandler}\\
  14 \helpref{wxObject}{wxobject}
  15
  16 \wxheading{Include files}
  17
  18 <wx/textctrl.h>
  19
  20 \wxheading{Window styles}
  21
  22 \twocolwidtha{5cm}
  23 \begin{twocollist}\itemsep=0pt
  24 \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
  25 the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
  26 is either processed internally by the control or used for navigation between
  27 dialog controls).}
  28 \twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receive
  29 wxEVT\_CHAR events for TAB pressed - normally, TAB is used for passing to the
  30 next control in a dialog instead. For the control created with this style,
  31 you can still use Ctrl-Enter to pass to the next control from the keyboard.}
  32 \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
  33 \twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
  34 \twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
  35 \twocolitem{\windowstyle{wxTE\_RICH}}{Use rich text control under Win32, this
  36 allows to have more than 64KB of text in the control even under Win9x. This
  37 style is ignored under other platforms.}
  38 \twocolitem{\windowstyle{wxTE\_RICH2}}{Use rich text control version 2.0 or 3.0
  39 under Win32, this style is ignored under other platforms}
  40 \twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the
  41 wxTextUrlEvents when mouse events occur over them. This style is only supported
  42 for wxTE\_RICH Win32 and multi-line wxGTK2 text controls.}
  43 \twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control
  44 doesn't show the selection when it doesn't have focus - use this style to force
  45 it to always show it. It doesn't do anything under other platforms.}
  46 \twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created and
  47 used, so that text won't be wrapped. No effect under wxGTK1.}
  48 \twocolitem{\windowstyle{wxTE\_LEFT}}{The text in the control will be left-justified (default).}
  49 \twocolitem{\windowstyle{wxTE\_CENTRE}}{The text in the control will be centered (currently wxMSW and wxGTK2 only).}
  50 \twocolitem{\windowstyle{wxTE\_RIGHT}}{The text in the control will be right-justified (currently wxMSW and wxGTK2 only).}
  51 \twocolitem{\windowstyle{wxTE\_DONTWRAP}}{Same as {\tt wxHSCROLL} style: don't wrap at all, show horizontal scrollbar instead.}
  52 \twocolitem{\windowstyle{wxTE\_CHARWRAP}}{Wrap the lines too long to be shown entirely at any position (wxUniv and wxGTK2 only).}
  53 \twocolitem{\windowstyle{wxTE\_WORDWRAP}}{Wrap the lines too long to be shown entirely at word boundaries (wxUniv and wxGTK2 only).}
  54 \twocolitem{\windowstyle{wxTE\_BESTWRAP}}{Wrap the lines at word boundaries or at any other character if there are words longer than the window width (this is the default).}
  55 \twocolitem{\windowstyle{wxTE\_CAPITALIZE}}{On PocketPC and Smartphone, causes the first letter to be capitalized.}
  56 \end{twocollist}
  57
  58 See also \helpref{window styles overview}{windowstyles} and \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}.
  59
  60 Note that alignment styles (\windowstyle{wxTE\_LEFT},
  61 \windowstyle{wxTE\_CENTRE} and \windowstyle{wxTE\_RIGHT}) can be changed
  62 dynamically after control creation on wxMSW and wxGTK.
  63 \windowstyle{wxTE\_READONLY}, \windowstyle{wxTE\_PASSWORD} and wrapping styles
  64 can be dynamically changed under wxGTK but not wxMSW. The other styles can be
  65 only set during control creation.
  66
  67
  68 \wxheading{wxTextCtrl text format}
  69
  70 The multiline text controls always store the text as a sequence of lines
  71 separated by {\tt $\backslash$n} characters, i.e. in the Unix text format even
  72 on non-Unix platforms. This allows the user code to ignore the differences
  73 between the platforms but at a price: the indices in the control such as those
  74 returned by \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} or
  75 \helpref{GetSelection}{wxtextctrlgetselection} can {\bf not} be used as
  76 indices into the string returned by \helpref{GetValue}{wxtextctrlgetvalue} as
  77 they're going to be slightly off for platforms using
  78 {\tt $\backslash$r$\backslash$n} as separator (as Windows does), for example.
  79
  80 Instead, if you need to obtain a substring between the $2$ indices obtained
  81 from the control with the help of the functions mentioned above, you should
  82 use \helpref{GetRange}{wxtextctrlgetrange}. And the indices themselves can
  83 only be passed to other methods, for example
  84 \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint} or
  85 \helpref{SetSelection}{wxtextctrlsetselection}.
  86
  87 To summarize: never use the indices returned by (multiline) wxTextCtrl as
  88 indices into the string it contains, but only as arguments to be passed back
  89 to the other wxTextCtrl methods.
  90
  91 \wxheading{wxTextCtrl styles}
  92
  93 Multi-line text controls support the styles, i.e. provide a possibility to set
  94 colours and font for individual characters in it (note that under Windows {\tt
  95 wxTE\_RICH} style is required for style support). To use the styles you can
  96 either call \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} before
  97 inserting the text or call \helpref{SetStyle}{wxtextctrlsetstyle} later to
  98 change the style of the text already in the control (the first solution is
  99 much more efficient).
 100
 101 In either case, if the style doesn't specify some of the attributes (for
 102 example you only want to set the text colour but without changing the font nor
 103 the text background), the values of the default style will be used for them.
 104 If there is no default style, the attributes of the text control itself are
 105 used.
 106
 107 So the following code correctly describes what it does: the second call
 108 to \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} doesn't change the
 109 text foreground colour (which stays red) while the last one doesn't change the
 110 background colour (which stays grey):
 111
 112 {\small%
 113 \begin{verbatim}
 114     text->SetDefaultStyle(wxTextAttr(*wxRED));
 115     text->AppendText("Red text\n");
 116     text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
 117     text->AppendText("Red on grey text\n");
 118     text->SetDefaultStyle(wxTextAttr(*wxBLUE);
 119     text->AppendText("Blue on grey text\n");
 120 \end{verbatim}
 121 }%
 122
 123 \wxheading{wxTextCtrl and C++ streams}
 124
 125 This class multiply-inherits from {\bf streambuf} where compilers allow,
 126 allowing code such as the following:
 127
 128 {\small%
 129 \begin{verbatim}
 130   wxTextCtrl *control = new wxTextCtrl(...);
 131
 132   ostream stream(control)
 133
 134   stream << 123.456 << " some text\n";
 135   stream.flush();
 136 \end{verbatim}
 137 }%
 138
 139 If your compiler does not support derivation from {\bf streambuf} and gives a
 140 compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
 141 wxTextCtrl header file.
 142
 143 Note that independently of this setting you can always use wxTextCtrl itself
 144 in a stream-like manner:
 145
 146 {\small%
 147 \begin{verbatim}
 148   wxTextCtrl *control = new wxTextCtrl(...);
 149
 150   *control << 123.456 << " some text\n";
 151 \end{verbatim}
 152 }%
 153
 154 always works. However the possibility to create an ostream associated with
 155 wxTextCtrl may be useful if you need to redirect the output of a function
 156 taking an ostream as parameter to a text control.
 157
 158 Another commonly requested need is to redirect {\bf std::cout} to the text
 159 control. This could be done in the following way:
 160
 161 {\small%
 162 \begin{verbatim}
 163   #include <iostream>
 164
 165   wxTextCtrl *control = new wxTextCtrl(...);
 166
 167   std::streambuf *sbOld = std::cout.rdbuf();
 168   std::cout.rdbuf(*control);
 169
 170   // use cout as usual, the output appears in the text control
 171   ...
 172
 173   std::cout.rdbuf(sbOld);
 174 \end{verbatim}
 175 }%
 176
 177 But wxWidgets provides a convenient class to make it even simpler so instead
 178 you may just do
 179
 180 {\small%
 181 \begin{verbatim}
 182   #include <iostream>
 183
 184   wxTextCtrl *control = new wxTextCtrl(...);
 185
 186   wxStreamToTextRedirector redirect(control);
 187
 188   // all output to cout goes into the text control until the exit from current
 189   // scope
 190 \end{verbatim}
 191 }%
 192
 193 See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
 194 details.
 195
 196 \wxheading{Constants}
 197
 198 The values below are the possible return codes of the
 199 \helpref{HitTest}{wxtextctrlhittest} method:
 200
 201 {\small
 202 \begin{verbatim}
 203 // the point asked is ...
 204 enum wxTextCtrlHitTestResult
 205 {
 206     wxTE_HT_UNKNOWN = -2,   // this means HitTest() is simply not implemented
 207     wxTE_HT_BEFORE,         // either to the left or upper
 208     wxTE_HT_ON_TEXT,        // directly on
 209     wxTE_HT_BELOW,          // below [the last line]
 210     wxTE_HT_BEYOND          // after [the end of line]
 211 };
 212 // ... the character returned
 213 \end{verbatim}
 214 }
 215
 216
 217 \wxheading{Event handling}
 218
 219 The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
 220 wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
 221 automatically, when the control has the focus.
 222
 223 To process input from a text control, use these event handler macros to direct input to member
 224 functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
 225
 226 \twocolwidtha{7cm}%
 227 \begin{twocollist}\itemsep=0pt
 228 \twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
 229 generated when the text changes. Notice that this event will be sent
 230 when the text controls contents changes - whether this is due to user input or
 231 comes from the program itself (for example, if SetValue() is called); see ChangeValue() for
 232 a function which does not send this event.}
 233 \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
 234 generated when enter is pressed in a text control (which must have
 235 wxTE\_PROCESS\_ENTER style for this event to be generated).}
 236 \twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occurred over an URL
 237 in the text control (wxMSW and wxGTK2 only)}
 238 \twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text
 239 into the control than the limit set by
 240 \helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
 241 \end{twocollist}%
 242
 243 \latexignore{\rtfignore{\wxheading{Members}}}
 244
 245
 246 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlctor}
 247
 248 \func{}{wxTextCtrl}{\void}
 249
 250 Default constructor.
 251
 252 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 253 \param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 254 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}}
 255
 256 Constructor, creating and showing a text control.
 257
 258 \wxheading{Parameters}
 259
 260 \docparam{parent}{Parent window. Should not be NULL.}
 261
 262 \docparam{id}{Control identifier. A value of -1 denotes a default value.}
 263
 264 \docparam{value}{Default text value.}
 265
 266 \docparam{pos}{Text control position.}
 267
 268 \docparam{size}{Text control size.}
 269
 270 \docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
 271
 272 \docparam{validator}{Window validator.}
 273
 274 \docparam{name}{Window name.}
 275
 276 \wxheading{Remarks}
 277
 278 The horizontal scrollbar ({\bf wxHSCROLL} style flag) will only be created
 279 for multi-line text controls.
 280 Without a horizontal scrollbar, text lines that don't fit in the control's
 281 size will be wrapped (but no newline character is inserted). Single line
 282 controls don't have a horizontal scrollbar, the text is automatically scrolled
 283 so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
 284 visible.
 285
 286 % VZ: this is no longer true
 287 %Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
 288 %as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
 289 %apply.
 290
 291 \wxheading{See also}
 292
 293 \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
 294
 295
 296 \membersection{wxTextCtrl::\destruct{wxTextCtrl}}\label{wxtextctrldtor}
 297
 298 \func{}{\destruct{wxTextCtrl}}{\void}
 299
 300 Destructor, destroying the text control.
 301
 302
 303 \membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
 304
 305 \func{void}{AppendText}{\param{const wxString\& }{ text}}
 306
 307 Appends the text to the end of the text control.
 308
 309 \wxheading{Parameters}
 310
 311 \docparam{text}{Text to write to the text control.}
 312
 313 \wxheading{Remarks}
 314
 315 After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
 316 the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
 317
 318 \wxheading{See also}
 319
 320 \helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
 321
 322
 323 \membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
 324
 325 \func{virtual bool}{CanCopy}{\void}
 326
 327 Returns {\tt true} if the selection can be copied to the clipboard.
 328
 329
 330 \membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
 331
 332 \func{virtual bool}{CanCut}{\void}
 333
 334 Returns {\tt true} if the selection can be cut to the clipboard.
 335
 336
 337 \membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
 338
 339 \func{virtual bool}{CanPaste}{\void}
 340
 341 Returns {\tt true} if the contents of the clipboard can be pasted into the
 342 text control. On some platforms (Motif, GTK) this is an approximation
 343 and returns {\tt true} if the control is editable, {\tt false} otherwise.
 344
 345
 346 \membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
 347
 348 \func{virtual bool}{CanRedo}{\void}
 349
 350 Returns {\tt true} if there is a redo facility available and the last operation
 351 can be redone.
 352
 353
 354 \membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
 355
 356 \func{virtual bool}{CanUndo}{\void}
 357
 358 Returns {\tt true} if there is an undo facility available and the last operation
 359 can be undone.
 360
 361
 362 \membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
 363
 364 \func{virtual void}{Clear}{\void}
 365
 366 Clears the text in the control.
 367
 368 Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
 369 event.
 370
 371
 372 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 373
 374 \func{virtual void}{Copy}{\void}
 375
 376 Copies the selected text to the clipboard under Motif and MS Windows.
 377
 378
 379 \membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
 380
 381 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 382 \param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 383 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}}
 384
 385 Creates the text control for two-step construction. Derived classes
 386 should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}\rtfsp
 387 for further details.
 388
 389
 390 \membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
 391
 392 \func{virtual void}{Cut}{\void}
 393
 394 Copies the selected text to the clipboard and removes the selection.
 395
 396
 397 \membersection{wxTextCtrl::DiscardEdits}\label{wxtextctrldiscardedits}
 398
 399 \func{void}{DiscardEdits}{\void}
 400
 401 Resets the internal `modified' flag as if the current edits had been saved.
 402
 403
 404 \membersection{wxTextCtrl::EmulateKeyPress}\label{wxtextctrlemulatekeypress}
 405
 406 \func{bool}{EmulateKeyPress}{\param{const wxKeyEvent\& }{event}}
 407
 408 This functions inserts into the control the character which would have been
 409 inserted if the given key event had occurred in the text control. The
 410 {\it event} object should be the same as the one passed to {\tt EVT\_KEY\_DOWN}
 411 handler previously by wxWidgets.
 412
 413 Please note that this function doesn't currently work correctly for all keys
 414 under any platform but MSW.
 415
 416 \wxheading{Return value}
 417
 418 {\tt true} if the event resulted in a change to the control, {\tt false}
 419 otherwise.
 420
 421
 422 \membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
 423
 424 \constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
 425
 426 Returns the style currently used for the new text.
 427
 428 \wxheading{See also}
 429
 430 \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle}
 431
 432
 433 \membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
 434
 435 \constfunc{virtual long}{GetInsertionPoint}{\void}
 436
 437 Returns the insertion point. This is defined as the zero based index of the
 438 character position to the right of the insertion point. For example, if
 439 the insertion point is at the end of the text control, it is equal to
 440 both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
 441 \helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
 442
 443 The following code snippet safely returns the character at the insertion
 444 point or the zero character if the point is at the end of the control.
 445
 446 {\small%
 447 \begin{verbatim}
 448   char GetCurrentChar(wxTextCtrl *tc) {
 449     if (tc->GetInsertionPoint() == tc->GetLastPosition())
 450       return '\0';
 451     return tc->GetValue[tc->GetInsertionPoint()];
 452   }
 453 \end{verbatim}
 454 }%
 455
 456
 457 \membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
 458
 459 \constfunc{virtual wxTextPos}{GetLastPosition}{\void}
 460
 461 Returns the zero based index of the last position in the text control,
 462 which is equal to the number of characters in the control.
 463
 464
 465 \membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
 466
 467 \constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
 468
 469 Gets the length of the specified line, not including any trailing newline
 470 character(s).
 471
 472 \wxheading{Parameters}
 473
 474 \docparam{lineNo}{Line number (starting from zero).}
 475
 476 \wxheading{Return value}
 477
 478 The length of the line, or -1 if {\it lineNo} was invalid.
 479
 480
 481 \membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
 482
 483 \constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
 484
 485 Returns the contents of a given line in the text control, not including
 486 any trailing newline character(s).
 487
 488 \wxheading{Parameters}
 489
 490 \docparam{lineNo}{The line number, starting from zero.}
 491
 492 \wxheading{Return value}
 493
 494 The contents of the line.
 495
 496
 497 \membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
 498
 499 \constfunc{int}{GetNumberOfLines}{\void}
 500
 501 Returns the number of lines in the text control buffer.
 502
 503 \wxheading{Remarks}
 504
 505 Note that even empty text controls have one line (where the insertion point
 506 is), so GetNumberOfLines() never returns $0$.
 507
 508 For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a multi-line
 509 text control is calculated by actually counting newline characters in the
 510 buffer, i.e. this function returns the number of logical lines and doesn't
 511 depend on whether any of them are wrapped. For all the other platforms, the
 512 number of physical lines in the control is returned.
 513
 514 Also note that you may wish to avoid using functions that work with line
 515 numbers if you are working with controls that contain large amounts of text as
 516 this function has $O(N)$ complexity for $N$ being the number of lines.
 517
 518
 519 \membersection{wxTextCtrl::GetRange}\label{wxtextctrlgetrange}
 520
 521 \constfunc{virtual wxString}{GetRange}{\param{long}{ from}, \param{long}{ to}}
 522
 523 Returns the string containing the text starting in the positions {\it from} and
 524 up to {\it to} in the control. The positions must have been returned by another
 525 wxTextCtrl method.
 526
 527 Please note that the positions in a multiline wxTextCtrl do {\bf not}
 528 correspond to the indices in the string returned by
 529 \helpref{GetValue}{wxtextctrlgetvalue} because of the different new line
 530 representations ({\tt CR} or {\tt CR LF}) and so this method should be used to
 531 obtain the correct results instead of extracting parts of the entire value. It
 532 may also be more efficient, especially if the control contains a lot of data.
 533
 534
 535 \membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
 536
 537 \constfunc{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
 538
 539 Gets the current selection span. If the returned values are equal, there was
 540 no selection.
 541
 542 Please note that the indices returned may be used with the other wxTextctrl
 543 methods but don't necessarily represent the correct indices into the string
 544 returned by \helpref{GetValue()}{wxtextctrlgetvalue} for multiline controls
 545 under Windows (at least,) you should use
 546 \helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
 547 text.
 548
 549 \wxheading{Parameters}
 550
 551 \docparam{from}{The returned first position.}
 552
 553 \docparam{to}{The returned last position.}
 554
 555 \pythonnote{The wxPython version of this method returns a tuple
 556 consisting of the from and to values.}
 557
 558 \perlnote{In wxPerl this method takes no parameter and returns a
 559 2-element list {\tt ( from, to )}.}
 560
 561
 562 \membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
 563
 564 \func{virtual wxString}{GetStringSelection}{\void}
 565
 566 Gets the text currently selected in the control. If there is no selection, the
 567 returned string is empty.
 568
 569
 570 \membersection{wxTextCtrl::GetStyle}\label{wxtextctrlgetstyle}
 571
 572 \func{bool}{GetStyle}{\param{long }{position}, \param{wxTextAttr\& }{style}}
 573
 574 Returns the style at this position in the text control. Not all platforms
 575 support this function.
 576
 577 \wxheading{Return value}
 578
 579 {\tt true} on success, {\tt false} if an error occurred - it may also mean that
 580 the styles are not supported under this platform.
 581
 582 \wxheading{See also}
 583
 584 \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle}, \helpref{wxTextAttr}{wxtextattr}
 585
 586
 587 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 588
 589 \constfunc{wxString}{GetValue}{\void}
 590
 591 Gets the contents of the control. Notice that for a multiline text control,
 592 the lines will be separated by (Unix-style) $\backslash$n characters, even
 593 under Windows where they are separated by a $\backslash$r$\backslash$n
 594 sequence in the native control.
 595
 596
 597 \membersection{wxTextCtrl::HitTest}\label{wxtextctrlhittest}
 598
 599 \constfunc{wxTextCtrlHitTestResult}{HitTest}{\param{const wxPoint\& }{pt}, \param{wxTextCoord }{*col}, \param{wxTextCoord }{*row}}
 600
 601 This function finds the character at the specified position expressed in
 602 pixels. If the return code is not \texttt{wxTE\_HT\_UNKNOWN} the row and column
 603 of the character closest to this position are returned in the \arg{col} and
 604 \arg{row} parameters (unless the pointers are {\tt NULL} which is allowed).
 605
 606 Please note that this function is currently only implemented in wxUniv,
 607 wxMSW and wxGTK2 ports.
 608
 609 \wxheading{See also}
 610
 611 \helpref{PositionToXY}{wxtextctrlpositiontoxy}, \helpref{XYToPosition}{wxtextctrlxytoposition}
 612
 613 \perlnote{In wxPerl this function takes only the position argument and
 614 returns a 3-element list \texttt{(result, col, row)}}.
 615
 616
 617 \membersection{wxTextCtrl::IsEditable}\label{wxtextctrliseditable}
 618
 619 \constfunc{bool}{IsEditable}{\void}
 620
 621 Returns {\tt true} if the controls contents may be edited by user (note that it
 622 always can be changed by the program), i.e. if the control hasn't been put in
 623 read-only mode by a previous call to
 624 \helpref{SetEditable}{wxtextctrlseteditable}.
 625
 626
 627 \membersection{wxTextCtrl::IsEmpty}\label{wxtextctrlisempty}
 628
 629 \constfunc{bool}{IsEmpty}{\void}
 630
 631 Returns \true if the control is currently empty. This is the same as
 632 \texttt{GetValue().empty()} but can be much more efficient for the multiline
 633 controls containing big amounts of text.
 634
 635 \newsince{2.7.1}
 636
 637
 638 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 639
 640 \constfunc{bool}{IsModified}{\void}
 641
 642 Returns {\tt true} if the text has been modified by user. Note that calling
 643 \helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
 644
 645 \wxheading{See also}
 646
 647 \helpref{MarkDirty}{wxtextctrlmarkdirty}
 648
 649
 650 \membersection{wxTextCtrl::IsMultiLine}\label{wxtextctrlismultiline}
 651
 652 \constfunc{bool}{IsMultiLine}{\void}
 653
 654 Returns {\tt true} if this is a multi line edit control and {\tt false}
 655 otherwise.
 656
 657 \wxheading{See also}
 658
 659 \helpref{IsSingleLine}{wxtextctrlissingleline}
 660
 661
 662 \membersection{wxTextCtrl::IsSingleLine}\label{wxtextctrlissingleline}
 663
 664 \constfunc{bool}{IsSingleLine}{\void}
 665
 666 Returns {\tt true} if this is a single line edit control and {\tt false}
 667 otherwise.
 668
 669 \wxheading{See also}
 670
 671 \helpref{IsMultiLine}{wxtextctrlissingleline}
 672
 673
 674 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 675
 676 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}, \param{int }{fileType = wxTEXT\_TYPE\_ANY}}
 677
 678 Loads and displays the named file, if it exists.
 679
 680 \wxheading{Parameters}
 681
 682 \docparam{filename}{The filename of the file to load.}
 683
 684 \docparam{fileType}{The type of file to load. This is currently ignored in wxTextCtrl.}
 685
 686 \wxheading{Return value}
 687
 688 {\tt true} if successful, {\tt false} otherwise.
 689
 690 % VZ: commenting this out as: (a) the docs are wrong (you can't replace
 691 %     anything), (b) wxTextCtrl doesn't have any OnChar() anyhow
 692 %% \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 693 %%
 694 %% \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 695 %%
 696 %% Default handler for character input.
 697 %%
 698 %% \wxheading{Remarks}
 699 %%
 700 %% It is possible to intercept character
 701 %% input by overriding this member. Call this function
 702 %% to let the default behaviour take place; not calling
 703 %% it results in the character being ignored. You can
 704 %% replace the {\it keyCode} member of {\it event} to
 705 %% translate keystrokes.
 706 %%
 707 %% Note that Windows and Motif have different ways
 708 %% of implementing the default behaviour. In Windows,
 709 %% calling wxTextCtrl::OnChar immediately
 710 %% processes the character. In Motif,
 711 %% calling this function simply sets a flag
 712 %% to let default processing happen. This might affect
 713 %% the way in which you write your OnChar function
 714 %% on different platforms.
 715 %%
 716 %% \wxheading{See also}
 717 %%
 718 %% \helpref{wxKeyEvent}{wxkeyevent}
 719
 720
 721 \membersection{wxTextCtrl::MarkDirty}\label{wxtextctrlmarkdirty}
 722
 723 \func{void}{MarkDirty}{\void}
 724
 725 Mark text as modified (dirty).
 726
 727 \wxheading{See also}
 728
 729 \helpref{IsModified}{wxtextctrlismodified}
 730
 731
 732 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 733
 734 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 735
 736 This event handler function implements default drag and drop behaviour, which
 737 is to load the first dropped file into the control.
 738
 739 \wxheading{Parameters}
 740
 741 \docparam{event}{The drop files event.}
 742
 743 \wxheading{Remarks}
 744
 745 This is not implemented on non-Windows platforms.
 746
 747 \wxheading{See also}
 748
 749 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 750
 751
 752 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 753
 754 \func{virtual void}{Paste}{\void}
 755
 756 Pastes text from the clipboard to the text item.
 757
 758
 759 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 760
 761 \constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 762
 763 Converts given position to a zero-based column, line number pair.
 764
 765 \wxheading{Parameters}
 766
 767 \docparam{pos}{Position.}
 768
 769 \docparam{x}{Receives zero based column number.}
 770
 771 \docparam{y}{Receives zero based line number.}
 772
 773 \wxheading{Return value}
 774
 775 {\tt true} on success, {\tt false} on failure (most likely due to a too large position
 776 parameter).
 777
 778 \wxheading{See also}
 779
 780 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 781
 782 \pythonnote{In Python, PositionToXY() returns a tuple containing the x and
 783 y values, so (x,y) = PositionToXY() is equivalent to the call described
 784 above.}
 785
 786 \perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
 787 returns a 2-element list {\tt ( x, y )}.}
 788
 789
 790 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 791
 792 \func{virtual void}{Redo}{\void}
 793
 794 If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
 795 if there is no redo facility.
 796
 797
 798 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 799
 800 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 801
 802 Removes the text starting at the first given position up to (but not including)
 803 the character at the last position.
 804
 805 \wxheading{Parameters}
 806
 807 \docparam{from}{The first position.}
 808
 809 \docparam{to}{The last position.}
 810
 811
 812 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 813
 814 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 815
 816 Replaces the text starting at the first position up to (but not including)
 817 the character at the last position with the given text.
 818
 819 \wxheading{Parameters}
 820
 821 \docparam{from}{The first position.}
 822
 823 \docparam{to}{The last position.}
 824
 825 \docparam{value}{The value to replace the existing text with.}
 826
 827
 828 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 829
 830 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}, \param{int }{fileType = wxTEXT\_TYPE\_ANY}}
 831
 832 Saves the contents of the control in a text file.
 833
 834 \wxheading{Parameters}
 835
 836 \docparam{filename}{The name of the file in which to save the text.}
 837
 838 \docparam{fileType}{The type of file to save. This is currently ignored in wxTextCtrl.}
 839
 840 \wxheading{Return value}
 841
 842 {\tt true} if the operation was successful, {\tt false} otherwise.
 843
 844
 845 \membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
 846
 847 \func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
 848
 849 Changes the default style to use for the new text which is going to be added
 850 to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
 851 \helpref{AppendText}{wxtextctrlappendtext}.
 852
 853 If either of the font, foreground, or background colour is not set in\rtfsp
 854 {\it style}, the values of the previous default style are used for them. If
 855 the previous default style didn't set them neither, the global font or colours
 856 of the text control itself are used as fall back.
 857
 858 However if the {\it style} parameter is the default wxTextAttr, then the
 859 default style is just reset (instead of being combined with the new style which
 860 wouldn't change it at all).
 861
 862 \wxheading{Parameters}
 863
 864 \docparam{style}{The style for the new text.}
 865
 866 \wxheading{Return value}
 867
 868 {\tt true} on success, {\tt false} if an error occurred - may also mean that
 869 the styles are not supported under this platform.
 870
 871 \wxheading{See also}
 872
 873 \helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
 874
 875
 876 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 877
 878 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 879
 880 Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
 881
 882 \wxheading{Parameters}
 883
 884 \docparam{editable}{If {\tt true}, the control is editable. If {\tt false}, the control is read-only.}
 885
 886 \wxheading{See also}
 887
 888 \helpref{IsEditable}{wxtextctrliseditable}
 889
 890
 891 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 892
 893 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 894
 895 Sets the insertion point at the given position.
 896
 897 \wxheading{Parameters}
 898
 899 \docparam{pos}{Position to set.}
 900
 901
 902 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 903
 904 \func{virtual void}{SetInsertionPointEnd}{\void}
 905
 906 Sets the insertion point at the end of the text control. This is equivalent
 907 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 908
 909
 910 \membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
 911
 912 \func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
 913
 914 This function sets the maximum number of characters the user can enter into the
 915 control. In other words, it allows to limit the text value length to {\it len}
 916 not counting the terminating {\tt NUL} character.
 917
 918 If {\it len} is $0$, the previously set max length limit, if any, is discarded
 919 and the user may enter as much text as the underlying native text control
 920 widget supports (typically at least 32Kb).
 921
 922 If the user tries to enter more characters into the text control when it
 923 already is filled up to the maximal length, a
 924 {\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
 925 (giving it the possibility to show an explanatory message, for example) and the
 926 extra input is discarded.
 927
 928 Note that under GTK+, this function may only be used with single line text controls.
 929
 930 \wxheading{Compatibility}
 931
 932 Only implemented in wxMSW/wxGTK starting with wxWidgets 2.3.2.
 933
 934
 935 \membersection{wxTextCtrl::SetModified}\label{wxtextctrlsetmodified}
 936
 937 \func{void}{SetModified}{\param{bool }{modified}}
 938
 939 Marks the control as being modified by the user or not.
 940
 941 \wxheading{See also}
 942
 943 \helpref{MarkDirty}{wxtextctrlmarkdirty}, \helpref{DiscardEdits}{wxtextctrldiscardedits}
 944
 945
 946 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 947
 948 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 949
 950 Selects the text starting at the first position up to (but not including) the
 951 character at the last position. If both parameters are equal to $-1$ all text
 952 in the control is selected.
 953
 954 \wxheading{Parameters}
 955
 956 \docparam{from}{The first position.}
 957
 958 \docparam{to}{The last position.}
 959
 960
 961 \membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
 962
 963 \func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
 964
 965 Changes the style of the given range. If any attribute within {\it style} is
 966 not set, the corresponding attribute from \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} is used.
 967
 968 \wxheading{Parameters}
 969
 970 \docparam{start}{The start of the range to change.}
 971
 972 \docparam{end}{The end of the range to change.}
 973
 974 \docparam{style}{The new style for the range.}
 975
 976 \wxheading{Return value}
 977
 978 {\tt true} on success, {\tt false} if an error occurred - it may also mean that
 979 the styles are not supported under this platform.
 980
 981 \wxheading{See also}
 982
 983 \helpref{wxTextCtrl::GetStyle}{wxtextctrlgetstyle}, \helpref{wxTextAttr}{wxtextattr}
 984
 985
 986 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 987
 988 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 989
 990 Sets the text value and marks the control as not-modified (which means that
 991 \helpref{IsModified}{wxtextctrlismodified} would return {\tt false} immediately
 992 after the call to SetValue).
 993
 994 Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
 995 event.
 996
 997 This function is deprecated and should not be used in new code. Please use the
 998 \helpref{ChangeValue}{wxtextctrlchangevalue} function instead.
 999
1000 \wxheading{Parameters}
1001
1002 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
1003
1004
1005 \membersection{wxTextCtrl::ChangeValue}\label{wxtextctrlchangevalue}
1006
1007 \func{virtual void}{ChangeValue}{\param{const wxString\& }{ value}}
1008
1009 Sets the text value and marks the control as not-modified (which means that
1010 \helpref{IsModified}{wxtextctrlismodified} would return {\tt false} immediately
1011 after the call to SetValue).
1012
1013 Note that this function will \emph{not} generate the {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
1014 event.
1015 This is the only difference with \helpref{SetValue}{wxtextctrlsetvalue}.
1016 See \helpref{this topic}{progevent} for more information.
1017
1018 \newsince{2.7.1}
1019
1020 \wxheading{Parameters}
1021
1022 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
1023
1024
1025 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
1026
1027 \func{void}{ShowPosition}{\param{long}{ pos}}
1028
1029 Makes the line containing the given position visible.
1030
1031 \wxheading{Parameters}
1032
1033 \docparam{pos}{The position that should be visible.}
1034
1035
1036 \membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
1037
1038 \func{virtual void}{Undo}{\void}
1039
1040 If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
1041 if there is no undo facility.
1042
1043
1044 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
1045
1046 \func{void}{WriteText}{\param{const wxString\& }{ text}}
1047
1048 Writes the text into the text control at the current insertion position.
1049
1050 \wxheading{Parameters}
1051
1052 \docparam{text}{Text to write to the text control.}
1053
1054 \wxheading{Remarks}
1055
1056 Newlines in the text string
1057 are the only control characters allowed, and they will cause appropriate
1058 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
1059
1060 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.
1061
1062
1063 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
1064
1065 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
1066
1067 Converts the given zero based column and line number to a position.
1068
1069 \wxheading{Parameters}
1070
1071 \docparam{x}{The column number.}
1072
1073 \docparam{y}{The line number.}
1074
1075 \wxheading{Return value}
1076
1077 The position value, or -1 if {\tt x} or {\tt y} was invalid.
1078
1079
1080 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
1081
1082 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
1083
1084 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
1085
1086 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
1087
1088 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
1089
1090 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
1091
1092 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
1093
1094 Operator definitions for appending to a text control, for example:
1095
1096 \begin{verbatim}
1097   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1098
1099   (*wnd) << "Welcome to text control number " << 1 << ".\n";
1100 \end{verbatim}
1101