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