docs/latex/wx/text.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextAttr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3 \section{\class{wxTextAttr}}\label{wxtextattr}
   4
   5 wxTextAttr represents the attributes, or style, for a range of text in a\rtfsp
   6 \helpref{wxTextCtrl}{wxtextctrl}.
   7
   8 \wxheading{Derived from}
   9
  10 No base class
  11
  12 \wxheading{Include files}
  13
  14 <wx/textctrl.h>
  15
  16 \latexignore{\rtfignore{\wxheading{Members}}}
  17
  18 \membersection{wxTextAttr::wxTextAttr}\label{wxtextattrctor}
  19
  20 \func{}{wxTextAttr}{\void}
  21
  22 \func{}{wxTextAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour}, \param{const wxFont\& }{font = wxNullFont}}
  23
  24 The constructors initialize one or more of the text foreground and background
  25 colours and font. The values not initialized in the constructor can be set
  26 later, otherwise \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle} will use
  27 the default values for them.
  28
  29 \membersection{wxTextAttr::GetBackgroundColour}
  30
  31 \constfunc{const wxColour\&}{GetBackgroundColour}{\void}
  32
  33 Return the background colour specified by this attribute.
  34
  35 \membersection{wxTextAttr::GetFont}
  36
  37 \constfunc{const wxFont\&}{GetFont}{\void}
  38
  39 Return the text font specified by this attribute.
  40
  41 \membersection{wxTextAttr::GetTextColour}
  42
  43 \constfunc{const wxColour\&}{GetTextColour}{\void}
  44
  45 Return the text colour specified by this attribute.
  46
  47 \membersection{wxTextAttr::HasBackgroundColour}
  48
  49 \constfunc{bool}{HasBackgroundColour}{\void}
  50
  51 Returns {\tt TRUE} if this style specifies the background colour to use.
  52
  53 \membersection{wxTextAttr::HasFont}
  54
  55 \constfunc{bool}{HasFont}{\void}
  56
  57 Returns {\tt TRUE} if this style specifies the font to use.
  58
  59 \membersection{wxTextAttr::HasTextColour}
  60
  61 \constfunc{bool}{HasTextColour}{\void}
  62
  63 Returns {\tt TRUE} if this style specifies the foreground colour to use.
  64
  65 \membersection{wxTextAttr::IsDefault}
  66
  67 \constfunc{bool}{IsDefault}{\void}
  68
  69 Returns {\tt TRUE} if this style specifies any non-default attributes.
  70
  71 %%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  72
  73 \section{\class{wxTextCtrl}}\label{wxtextctrl}
  74
  75 A text control allows text to be displayed and edited. It may be
  76 single line or multi-line.
  77
  78 \wxheading{Derived from}
  79
  80 streambuf\\
  81 \helpref{wxControl}{wxcontrol}\\
  82 \helpref{wxWindow}{wxwindow}\\
  83 \helpref{wxEvtHandler}{wxevthandler}\\
  84 \helpref{wxObject}{wxobject}
  85
  86 \wxheading{Include files}
  87
  88 <wx/textctrl.h>
  89
  90 \wxheading{Window styles}
  91
  92 \twocolwidtha{5cm}
  93 \begin{twocollist}\itemsep=0pt
  94 \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
  95 the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
  96 either processed internally by the control or used for navigation between
  97 dialog controls).}
  98 \twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
  99 EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the
 100 next control in a dialog instead. For the control created with this style,
 101 you can still use Ctrl-Enter to pass to the next control from the keyboard.}
 102 \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
 103 \twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
 104 \twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
 105 \twocolitem{\windowstyle{wxTE\_RICH}}{Use rich text control under Win32, this
 106 allows to have more than 64Kb of text in the control even under Win9x. This
 107 style is ignored under other platforms.}
 108 \twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the
 109 wxTextUrlEvents when mouse events occur over them. This style is supported
 110 under Win32 only and requires wxTE\_RICH.}
 111 \twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control
 112 doesn't show the selection when it doesn't have focus - use this style to force
 113 it to always show it. It doesn't do anything under other platforms.}
 114 \twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
 115 \end{twocollist}
 116
 117 See also \helpref{window styles overview}{windowstyles} and
 118 \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
 119
 120 \wxheading{wxTextCtrl styles}
 121
 122 Multi-line text controls support the styles, i.e. provide a possibility to set
 123 colours and font for individual characters in it (note that under Windows {\tt
 124 wxTE\_RICH} style is required for style support). To use the styles you can
 125 either call \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} before
 126 inserting the text or call \helpref{SetStyle}{wxtextctrlsetstyle} later to
 127 change the style of the text already in the control (the first solution is
 128 much more efficient).
 129
 130 In either case, if the style doesn't specify some of the attributes (for
 131 example you only want to set the text colour but without changing the font nor
 132 the text background), the values of the default style will be used for them.
 133 If there is no default style, the attributes of the text control itself are
 134 used.
 135
 136 So the following code correctly describes what it does: the second call
 137 to \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} doesn't change the
 138 text foreground colour (which stays red) while the last one doesn't change the
 139 background colour (which stays grey):
 140
 141 {\small%
 142 \begin{verbatim}
 143     text->SetDefaultStyle(wxTextAttr(*wxRED));
 144     text->AppendText("Red text\n");
 145     text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
 146     text->AppendText("Red on grey text\n");
 147     text->SetDefaultStyle(wxTextAttr(*wxBLUE);
 148     text->AppendText("Blue on grey text\n");
 149 \end{verbatim}
 150 }%
 151
 152 \wxheading{wxTextCtrl and C++ streams}
 153
 154 This class multiply-inherits from {\bf streambuf} where compilers allow,
 155 allowing code such as the following:
 156
 157 {\small%
 158 \begin{verbatim}
 159   wxTextCtrl *control = new wxTextCtrl(...);
 160
 161   ostream stream(control)
 162
 163   stream << 123.456 << " some text\n";
 164   stream.flush();
 165 \end{verbatim}
 166 }%
 167
 168 If your compiler does not support derivation from {\bf streambuf} and gives a
 169 compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
 170 wxTextCtrl header file.
 171
 172 Note that independently of this setting you can always use wxTextCtrl itself
 173 in a stream-like manner:
 174
 175 {\small%
 176 \begin{verbatim}
 177   wxTextCtrl *control = new wxTextCtrl(...);
 178
 179   *control << 123.456 << " some text\n";
 180 \end{verbatim}
 181 }%
 182
 183 always works. However the possibility to create an ostream associated with
 184 wxTextCtrl may be useful if you need to redirect the output of a function
 185 taking an ostream as parameter to a text control.
 186
 187 Another commonly requested need is to redirect {\bf std::cout} to the text
 188 control. This could be done in the following way:
 189
 190 {\small%
 191 \begin{verbatim}
 192   #include <iostream>
 193
 194   wxTextCtrl *control = new wxTextCtrl(...);
 195
 196   std::streambuf *sbOld = std::cout.rdbuf();
 197   std::cout.rdbuf(*control);
 198
 199   // use cout as usual, the output appears in the text control
 200   ...
 201
 202   std::cout.rdbuf(sbOld);
 203 \end{verbatim}
 204 }%
 205
 206 But wxWindows provides a convenient class to make it even simpler so instead
 207 you may just do
 208
 209 {\small%
 210 \begin{verbatim}
 211   #include <iostream>
 212
 213   wxTextCtrl *control = new wxTextCtrl(...);
 214
 215   wxStreamToTextRedirector redirect(control);
 216
 217   // all output to cout goes into the text control until the exit from current
 218   // scope
 219 \end{verbatim}
 220 }%
 221
 222 See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
 223 details.
 224
 225 \wxheading{Event handling}
 226
 227 The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
 228 wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
 229 automatically, when the control has the focus.
 230
 231 To process input from a text control, use these event handler macros to direct input to member
 232 functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
 233
 234 \twocolwidtha{7cm}%
 235 \begin{twocollist}\itemsep=0pt
 236 \twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
 237 generated when the text changes. Notice that this event will always be sent
 238 when the text controls contents changes - whether this is due to user input or
 239 comes from the program itself (for example, if SetValue() is called)}
 240 \twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
 241 generated when enter is pressed in a single-line text control.}
 242 \twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occured over an URL
 243 in the text control (Win32 only)}
 244 \twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text
 245 into the control than the limit set by
 246 \helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
 247 \end{twocollist}%
 248
 249 \latexignore{\rtfignore{\wxheading{Members}}}
 250
 251 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
 252
 253 \func{}{wxTextCtrl}{\void}
 254
 255 Default constructor.
 256
 257 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 258 \param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 259 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
 260
 261 Constructor, creating and showing a text control.
 262
 263 \wxheading{Parameters}
 264
 265 \docparam{parent}{Parent window. Should not be NULL.}
 266
 267 \docparam{id}{Control identifier. A value of -1 denotes a default value.}
 268
 269 \docparam{value}{Default text value.}
 270
 271 \docparam{pos}{Text control position.}
 272
 273 \docparam{size}{Text control size.}
 274
 275 \docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
 276
 277 \docparam{validator}{Window validator.}
 278
 279 \docparam{name}{Window name.}
 280
 281 \wxheading{Remarks}
 282
 283 The horizontal scrollbar ({\bf wxTE\_HSCROLL} style flag) will only be created for multi-line text controls.
 284 Without a horizontal scrollbar, text lines that don't fit in the control's
 285 size will be wrapped (but no newline character is inserted). Single line
 286 controls don't have a horizontal scrollbar, the text is automatically scrolled
 287 so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
 288 visible.
 289
 290 % VZ: this is no longer true
 291 %Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
 292 %as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
 293 %apply.
 294
 295 \wxheading{See also}
 296
 297 \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
 298
 299 \membersection{wxTextCtrl::\destruct{wxTextCtrl}}
 300
 301 \func{}{\destruct{wxTextCtrl}}{\void}
 302
 303 Destructor, destroying the text control.
 304
 305 \membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
 306
 307 \func{void}{AppendText}{\param{const wxString\& }{ text}}
 308
 309 Appends the text to the end of the text control.
 310
 311 \wxheading{Parameters}
 312
 313 \docparam{text}{Text to write to the text control.}
 314
 315 \wxheading{Remarks}
 316
 317 After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
 318 the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
 319
 320 \wxheading{See also}
 321
 322 \helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
 323
 324 \membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
 325
 326 \func{virtual bool}{CanCopy}{\void}
 327
 328 Returns TRUE if the selection can be copied to the clipboard.
 329
 330 \membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
 331
 332 \func{virtual bool}{CanCut}{\void}
 333
 334 Returns TRUE if the selection can be cut to the clipboard.
 335
 336 \membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
 337
 338 \func{virtual bool}{CanPaste}{\void}
 339
 340 Returns TRUE if the contents of the clipboard can be pasted into the
 341 text control. On some platforms (Motif, GTK) this is an approximation
 342 and returns TRUE if the control is editable, FALSE otherwise.
 343
 344 \membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
 345
 346 \func{virtual bool}{CanRedo}{\void}
 347
 348 Returns TRUE if there is a redo facility available and the last operation
 349 can be redone.
 350
 351 \membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
 352
 353 \func{virtual bool}{CanUndo}{\void}
 354
 355 Returns TRUE if there is an undo facility available and the last operation
 356 can be undone.
 357
 358 \membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
 359
 360 \func{virtual void}{Clear}{\void}
 361
 362 Clears the text in the control.
 363
 364 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 365
 366 \func{virtual void}{Copy}{\void}
 367
 368 Copies the selected text to the clipboard under Motif and MS Windows.
 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}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 374 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
 375
 376 Creates the text control for two-step construction. Derived classes
 377 should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
 378 for further details.
 379
 380 \membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
 381
 382 \func{virtual void}{Cut}{\void}
 383
 384 Copies the selected text to the clipboard and removes the selection.
 385
 386 \membersection{wxTextCtrl::DiscardEdits}
 387
 388 \func{void}{DiscardEdits}{\void}
 389
 390 Resets the internal `modified' flag as if the current edits had been saved.
 391
 392 \membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
 393
 394 \constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
 395
 396 Returns the style currently used for the new text.
 397
 398 \wxheading{See also}
 399
 400 \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle}
 401
 402 \membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
 403
 404 \constfunc{virtual long}{GetInsertionPoint}{\void}
 405
 406 Returns the insertion point. This is defined as the zero based index of the
 407 character position to the right of the insertion point. For example, if
 408 the insertion point is at the end of the text control, it is equal to
 409 both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
 410 \helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
 411
 412 The following code snippet safely returns the character at the insertion
 413 point or the zero character if the point is at the end of the control.
 414
 415 {\small%
 416 \begin{verbatim}
 417   char GetCurrentChar(wxTextCtrl *tc) {
 418     if (tc->GetInsertionPoint() == tc->GetLastPosition())
 419       return '\0';
 420     return tc->GetValue[tc->GetInsertionPoint()];
 421   }
 422 \end{verbatim}
 423 }%
 424
 425 \membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
 426
 427 \constfunc{virtual long}{GetLastPosition}{\void}
 428
 429 Returns the zero based index of the last position in the text control,
 430 which is equal to the number of characters in the control.
 431
 432 \membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
 433
 434 \constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
 435
 436 Gets the length of the specified line, not including any trailing newline
 437 character(s).
 438
 439 \wxheading{Parameters}
 440
 441 \docparam{lineNo}{Line number (starting from zero).}
 442
 443 \wxheading{Return value}
 444
 445 The length of the line, or -1 if {\it lineNo} was invalid.
 446
 447 \membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
 448
 449 \constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
 450
 451 Returns the contents of a given line in the text control, not including
 452 any trailing newline character(s).
 453
 454 \wxheading{Parameters}
 455
 456 \docparam{lineNo}{The line number, starting from zero.}
 457
 458 \wxheading{Return value}
 459
 460 The contents of the line.
 461
 462 \membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
 463
 464 \constfunc{int}{GetNumberOfLines}{\void}
 465
 466 Returns the number of lines in the text control buffer.
 467
 468 \wxheading{Remarks}
 469
 470 Note that even empty text controls have one line (where the insertion point
 471 is), so GetNumberOfLines() never returns 0.
 472
 473 For gtk\_text (multi-line) controls, the number of lines is
 474 calculated by actually counting newline characters in the buffer. You
 475 may wish to avoid using functions that work with line numbers if you are
 476 working with controls that contain large amounts of text.
 477
 478 \membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
 479
 480 \func{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
 481
 482 Gets the current selection span. If the returned values are equal, there was
 483 no selection.
 484
 485 Please note that the indices returned may be used with the other wxTextctrl
 486 methods but don't necessarily represent the correct indices into the string
 487 returned by \helpref{GetValue()}{wxtextctrlgetvalue} for multiline controls
 488 under Windows (at least,) you should use
 489 \helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
 490 text.
 491
 492 \wxheading{Parameters}
 493
 494 \docparam{from}{The returned first position.}
 495
 496 \docparam{to}{The returned last position.}
 497
 498 \pythonnote{The wxPython version of this method returns a tuple
 499 consisting of the from and to values.}
 500
 501 \perlnote{In wxPerl this method takes no parameter and returns a
 502 2-element list {\tt ( from, to )}.}
 503
 504 \membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
 505
 506 \func{virtual wxString}{GetStringSelection}{\void}
 507
 508 Gets the text currently selected in the control. If there is no selection, the
 509 returned string is empty.
 510
 511 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 512
 513 \constfunc{wxString}{GetValue}{\void}
 514
 515 Gets the contents of the control. Notice that for a multiline text control,
 516 the lines will be separated by (Unix-style) $\backslash$n characters, even under
 517 Windows where they are separated by a $\backslash$r$\backslash$n sequence in the native control.
 518
 519 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 520
 521 \constfunc{bool}{IsModified}{\void}
 522
 523 Returns TRUE if the text has been modified.
 524
 525 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 526
 527 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 528
 529 Loads and displays the named file, if it exists.
 530
 531 \wxheading{Parameters}
 532
 533 \docparam{filename}{The filename of the file to load.}
 534
 535 \wxheading{Return value}
 536
 537 TRUE if successful, FALSE otherwise.
 538
 539 \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 540
 541 \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 542
 543 Default handler for character input.
 544
 545 \wxheading{Remarks}
 546
 547 It is possible to intercept character
 548 input by overriding this member. Call this function
 549 to let the default behaviour take place; not calling
 550 it results in the character being ignored. You can
 551 replace the {\it keyCode} member of {\it event} to
 552 translate keystrokes.
 553
 554 Note that Windows and Motif have different ways
 555 of implementing the default behaviour. In Windows,
 556 calling wxTextCtrl::OnChar immediately
 557 processes the character. In Motif,
 558 calling this function simply sets a flag
 559 to let default processing happen. This might affect
 560 the way in which you write your OnChar function
 561 on different platforms.
 562
 563 \wxheading{See also}
 564
 565 \helpref{wxKeyEvent}{wxkeyevent}
 566
 567 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 568
 569 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 570
 571 This event handler function implements default drag and drop behaviour, which
 572 is to load the first dropped file into the control.
 573
 574 \wxheading{Parameters}
 575
 576 \docparam{event}{The drop files event.}
 577
 578 \wxheading{Remarks}
 579
 580 This is not implemented on non-Windows platforms.
 581
 582 \wxheading{See also}
 583
 584 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 585
 586 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 587
 588 \func{virtual void}{Paste}{\void}
 589
 590 Pastes text from the clipboard to the text item.
 591
 592 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 593
 594 \constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 595
 596 Converts given position to a zero-based column, line number pair.
 597
 598 \wxheading{Parameters}
 599
 600 \docparam{pos}{Position.}
 601
 602 \docparam{x}{Receives zero based column number.}
 603
 604 \docparam{y}{Receives zero based line number.}
 605
 606 \wxheading{Return value}
 607
 608 TRUE on success, FALSE on failure (most likely due to a too large position
 609 parameter).
 610
 611 \wxheading{See also}
 612
 613 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 614
 615 \pythonnote{In Python, PositionToXY() returns a tuple containing the x and
 616 y values, so (x,y) = PositionToXY() is equivalent to the call described
 617 above.}
 618
 619 \perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
 620 returns a 2-element list {\tt ( x, y )}.}
 621
 622 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 623
 624 \func{virtual void}{Redo}{\void}
 625
 626 If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
 627 if there is no redo facility.
 628
 629 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 630
 631 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 632
 633 Removes the text starting at the first given position up to (but not including)
 634 the character at the last position.
 635
 636 \wxheading{Parameters}
 637
 638 \docparam{from}{The first position.}
 639
 640 \docparam{to}{The last position.}
 641
 642 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 643
 644 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 645
 646 Replaces the text starting at the first position up to (but not including)
 647 the character at the last position with the given text.
 648
 649 \wxheading{Parameters}
 650
 651 \docparam{from}{The first position.}
 652
 653 \docparam{to}{The last position.}
 654
 655 \docparam{value}{The value to replace the existing text with.}
 656
 657 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 658
 659 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
 660
 661 Saves the contents of the control in a text file.
 662
 663 \wxheading{Parameters}
 664
 665 \docparam{filename}{The name of the file in which to save the text.}
 666
 667 \wxheading{Return value}
 668
 669 TRUE if the operation was successful, FALSE otherwise.
 670
 671 \membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
 672
 673 \func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
 674
 675 Changes the default style to use for the new text which is going to be added
 676 to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
 677 \helpref{AppendText}{wxtextctrlappendtext}.
 678
 679 If either of the font, foreground, or background colour is not set in\rtfsp
 680 {\it style}, the values of the previous default style are used for them. If
 681 the previous default style didn't set them neither, the global font or colours
 682 of the text control itself are used as fall back.
 683
 684 However if the {\it style} parameter is the default wxTextAttr, then the
 685 default style is just reset (instead of being combined with the new style which
 686 wouldn't change it at all).
 687
 688 \wxheading{Parameters}
 689
 690 \docparam{style}{The style for the new text.}
 691
 692 \wxheading{Return value}
 693
 694 {\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
 695 the styles are not supported under this platform.
 696
 697 \wxheading{See also}
 698
 699 \helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
 700
 701 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 702
 703 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 704
 705 Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
 706
 707 \wxheading{Parameters}
 708
 709 \docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
 710
 711 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 712
 713 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 714
 715 Sets the insertion point at the given position.
 716
 717 \wxheading{Parameters}
 718
 719 \docparam{pos}{Position to set.}
 720
 721 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 722
 723 \func{virtual void}{SetInsertionPointEnd}{\void}
 724
 725 Sets the insertion point at the end of the text control. This is equivalent
 726 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 727
 728 \membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
 729
 730 \func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
 731
 732 This function sets the maximum number of characters the user can enter into the
 733 control. In other words, it allows to limit the text value length to {\it len}
 734 not counting the terminating {\tt NUL} character.
 735
 736 If {\it len} is $0$, the previously set max length limi, if any, is discarded
 737 and the user may enter as much text as the underlying native text control
 738 widget supports (typically at least 32Kb).
 739
 740 If the user tries to enter more characters into the text control when it
 741 already is filled up to the maximal length, a
 742 {\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
 743 (giving it the possibility to show an explanatory message, for example) and the
 744 extra input is discarded.
 745
 746 Note that this function may only be used with single line text controls.
 747
 748 \wxheading{Compatibility}
 749
 750 Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2.
 751
 752 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 753
 754 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 755
 756 Selects the text starting at the first position up to (but not including) the character at the last position.
 757
 758 \wxheading{Parameters}
 759
 760 \docparam{from}{The first position.}
 761
 762 \docparam{to}{The last position.}
 763
 764 \membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
 765
 766 \func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
 767
 768 Changes the style of the selection. If either of the font, foreground, or
 769 background colour is not set in {\it style}, the values of\rtfsp
 770 \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} are used.
 771
 772 \wxheading{Parameters}
 773
 774 \docparam{start}{The start of selection to change.}
 775
 776 \docparam{end}{The end of selection to change.}
 777
 778 \docparam{style}{The new style for the selection.}
 779
 780 \wxheading{Return value}
 781
 782 {\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
 783 the styles are not supported under this platform.
 784
 785 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 786
 787 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 788
 789 Sets the text value and marks the control as not-modified.
 790
 791 \wxheading{Parameters}
 792
 793 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 794
 795 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
 796
 797 \func{void}{ShowPosition}{\param{long}{ pos}}
 798
 799 Makes the line containing the given position visible.
 800
 801 \wxheading{Parameters}
 802
 803 \docparam{pos}{The position that should be visible.}
 804
 805 \membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
 806
 807 \func{virtual void}{Undo}{\void}
 808
 809 If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
 810 if there is no undo facility.
 811
 812 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
 813
 814 \func{void}{WriteText}{\param{const wxString\& }{ text}}
 815
 816 Writes the text into the text control at the current insertion position.
 817
 818 \wxheading{Parameters}
 819
 820 \docparam{text}{Text to write to the text control.}
 821
 822 \wxheading{Remarks}
 823
 824 Newlines in the text string
 825 are the only control characters allowed, and they will cause appropriate
 826 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
 827
 828 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.
 829
 830 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
 831
 832 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
 833
 834 Converts the given zero based column and line number to a position.
 835
 836 \wxheading{Parameters}
 837
 838 \docparam{x}{The column number.}
 839
 840 \docparam{y}{The line number.}
 841
 842 \wxheading{Return value}
 843
 844 The position value.
 845
 846 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
 847
 848 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
 849
 850 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
 851
 852 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
 853
 854 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
 855
 856 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
 857
 858 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
 859
 860 Operator definitions for appending to a text control, for example:
 861
 862 \begin{verbatim}
 863   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
 864
 865   (*wnd) << "Welcome to text control number " << 1 << ".\n";
 866 \end{verbatim}
 867