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