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 {\tt 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 {\tt 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 {\tt 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 {\tt TRUE} if the control is editable, {\tt FALSE} otherwise.
 343
 344 \membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
 345
 346 \func{virtual bool}{CanRedo}{\void}
 347
 348 Returns {\tt 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 {\tt 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 {\tt TRUE} if the text has been modified by user. Note that calling
 524 \helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
 525
 526 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 527
 528 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 529
 530 Loads and displays the named file, if it exists.
 531
 532 \wxheading{Parameters}
 533
 534 \docparam{filename}{The filename of the file to load.}
 535
 536 \wxheading{Return value}
 537
 538 {\tt TRUE} if successful, {\tt FALSE} otherwise.
 539
 540 \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 541
 542 \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 543
 544 Default handler for character input.
 545
 546 \wxheading{Remarks}
 547
 548 It is possible to intercept character
 549 input by overriding this member. Call this function
 550 to let the default behaviour take place; not calling
 551 it results in the character being ignored. You can
 552 replace the {\it keyCode} member of {\it event} to
 553 translate keystrokes.
 554
 555 Note that Windows and Motif have different ways
 556 of implementing the default behaviour. In Windows,
 557 calling wxTextCtrl::OnChar immediately
 558 processes the character. In Motif,
 559 calling this function simply sets a flag
 560 to let default processing happen. This might affect
 561 the way in which you write your OnChar function
 562 on different platforms.
 563
 564 \wxheading{See also}
 565
 566 \helpref{wxKeyEvent}{wxkeyevent}
 567
 568 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 569
 570 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 571
 572 This event handler function implements default drag and drop behaviour, which
 573 is to load the first dropped file into the control.
 574
 575 \wxheading{Parameters}
 576
 577 \docparam{event}{The drop files event.}
 578
 579 \wxheading{Remarks}
 580
 581 This is not implemented on non-Windows platforms.
 582
 583 \wxheading{See also}
 584
 585 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 586
 587 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 588
 589 \func{virtual void}{Paste}{\void}
 590
 591 Pastes text from the clipboard to the text item.
 592
 593 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 594
 595 \constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 596
 597 Converts given position to a zero-based column, line number pair.
 598
 599 \wxheading{Parameters}
 600
 601 \docparam{pos}{Position.}
 602
 603 \docparam{x}{Receives zero based column number.}
 604
 605 \docparam{y}{Receives zero based line number.}
 606
 607 \wxheading{Return value}
 608
 609 {\tt TRUE} on success, {\tt FALSE} on failure (most likely due to a too large position
 610 parameter).
 611
 612 \wxheading{See also}
 613
 614 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 615
 616 \pythonnote{In Python, PositionToXY() returns a tuple containing the x and
 617 y values, so (x,y) = PositionToXY() is equivalent to the call described
 618 above.}
 619
 620 \perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
 621 returns a 2-element list {\tt ( x, y )}.}
 622
 623 \membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
 624
 625 \func{virtual void}{Redo}{\void}
 626
 627 If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
 628 if there is no redo facility.
 629
 630 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 631
 632 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 633
 634 Removes the text starting at the first given position up to (but not including)
 635 the character at the last position.
 636
 637 \wxheading{Parameters}
 638
 639 \docparam{from}{The first position.}
 640
 641 \docparam{to}{The last position.}
 642
 643 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 644
 645 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 646
 647 Replaces the text starting at the first position up to (but not including)
 648 the character at the last position with the given text.
 649
 650 \wxheading{Parameters}
 651
 652 \docparam{from}{The first position.}
 653
 654 \docparam{to}{The last position.}
 655
 656 \docparam{value}{The value to replace the existing text with.}
 657
 658 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 659
 660 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
 661
 662 Saves the contents of the control in a text file.
 663
 664 \wxheading{Parameters}
 665
 666 \docparam{filename}{The name of the file in which to save the text.}
 667
 668 \wxheading{Return value}
 669
 670 {\tt TRUE} if the operation was successful, {\tt FALSE} otherwise.
 671
 672 \membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
 673
 674 \func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
 675
 676 Changes the default style to use for the new text which is going to be added
 677 to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
 678 \helpref{AppendText}{wxtextctrlappendtext}.
 679
 680 If either of the font, foreground, or background colour is not set in\rtfsp
 681 {\it style}, the values of the previous default style are used for them. If
 682 the previous default style didn't set them neither, the global font or colours
 683 of the text control itself are used as fall back.
 684
 685 However if the {\it style} parameter is the default wxTextAttr, then the
 686 default style is just reset (instead of being combined with the new style which
 687 wouldn't change it at all).
 688
 689 \wxheading{Parameters}
 690
 691 \docparam{style}{The style for the new text.}
 692
 693 \wxheading{Return value}
 694
 695 {\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
 696 the styles are not supported under this platform.
 697
 698 \wxheading{See also}
 699
 700 \helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
 701
 702 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 703
 704 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 705
 706 Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
 707
 708 \wxheading{Parameters}
 709
 710 \docparam{editable}{If {\tt TRUE}, the control is editable. If {\tt FALSE}, the control is read-only.}
 711
 712 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 713
 714 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 715
 716 Sets the insertion point at the given position.
 717
 718 \wxheading{Parameters}
 719
 720 \docparam{pos}{Position to set.}
 721
 722 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 723
 724 \func{virtual void}{SetInsertionPointEnd}{\void}
 725
 726 Sets the insertion point at the end of the text control. This is equivalent
 727 to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
 728
 729 \membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
 730
 731 \func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
 732
 733 This function sets the maximum number of characters the user can enter into the
 734 control. In other words, it allows to limit the text value length to {\it len}
 735 not counting the terminating {\tt NUL} character.
 736
 737 If {\it len} is $0$, the previously set max length limi, if any, is discarded
 738 and the user may enter as much text as the underlying native text control
 739 widget supports (typically at least 32Kb).
 740
 741 If the user tries to enter more characters into the text control when it
 742 already is filled up to the maximal length, a
 743 {\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
 744 (giving it the possibility to show an explanatory message, for example) and the
 745 extra input is discarded.
 746
 747 Note that this function may only be used with single line text controls.
 748
 749 \wxheading{Compatibility}
 750
 751 Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2.
 752
 753 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 754
 755 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 756
 757 Selects the text starting at the first position up to (but not including) the character at the last position.
 758
 759 \wxheading{Parameters}
 760
 761 \docparam{from}{The first position.}
 762
 763 \docparam{to}{The last position.}
 764
 765 \membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
 766
 767 \func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
 768
 769 Changes the style of the selection. If either of the font, foreground, or
 770 background colour is not set in {\it style}, the values of\rtfsp
 771 \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} are used.
 772
 773 \wxheading{Parameters}
 774
 775 \docparam{start}{The start of selection to change.}
 776
 777 \docparam{end}{The end of selection to change.}
 778
 779 \docparam{style}{The new style for the selection.}
 780
 781 \wxheading{Return value}
 782
 783 {\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
 784 the styles are not supported under this platform.
 785
 786 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 787
 788 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 789
 790 Sets the text value and marks the control as not-modified (which means that
 791 \helpref{IsModified}{wxtextctrlismodified} would return {\tt FALSE} immediately
 792 after the call to SetValue).
 793
 794 \wxheading{Parameters}
 795
 796 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 797
 798 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
 799
 800 \func{void}{ShowPosition}{\param{long}{ pos}}
 801
 802 Makes the line containing the given position visible.
 803
 804 \wxheading{Parameters}
 805
 806 \docparam{pos}{The position that should be visible.}
 807
 808 \membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
 809
 810 \func{virtual void}{Undo}{\void}
 811
 812 If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
 813 if there is no undo facility.
 814
 815 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
 816
 817 \func{void}{WriteText}{\param{const wxString\& }{ text}}
 818
 819 Writes the text into the text control at the current insertion position.
 820
 821 \wxheading{Parameters}
 822
 823 \docparam{text}{Text to write to the text control.}
 824
 825 \wxheading{Remarks}
 826
 827 Newlines in the text string
 828 are the only control characters allowed, and they will cause appropriate
 829 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
 830
 831 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.
 832
 833 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
 834
 835 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
 836
 837 Converts the given zero based column and line number to a position.
 838
 839 \wxheading{Parameters}
 840
 841 \docparam{x}{The column number.}
 842
 843 \docparam{y}{The line number.}
 844
 845 \wxheading{Return value}
 846
 847 The position value.
 848
 849 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
 850
 851 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
 852
 853 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
 854
 855 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
 856
 857 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
 858
 859 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
 860
 861 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
 862
 863 Operator definitions for appending to a text control, for example:
 864
 865 \begin{verbatim}
 866   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
 867
 868   (*wnd) << "Welcome to text control number " << 1 << ".\n";
 869 \end{verbatim}
 870