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