interface/wx/textctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        textctrl.h
   3 // Purpose:     interface of wxTextAttr
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTextAttr
  11
  12     wxTextAttr represents the character and paragraph attributes, or style,
  13     for a range of text in a wxTextCtrl or wxRichTextCtrl.
  14
  15     When setting up a wxTextAttr object, pass a bitlist mask to
  16     wxTextAttr::SetFlags to indicate which style elements should be changed. As
  17     a convenience, when you call a setter such as SetFont, the relevant bit
  18     will be set.
  19
  20     @library{wxcore}
  21     @category{richtext}
  22
  23     @see wxTextCtrl, wxRichTextCtrl
  24 */
  25 class wxTextAttr
  26 {
  27 public:
  28     //@{
  29     /**
  30         Constructors.
  31     */
  32     wxTextAttr();
  33     wxTextAttr(const wxColour& colText,
  34                const wxColour& colBack = wxNullColour,
  35                const wxFont& font = wxNullFont,
  36                wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT);
  37     wxTextAttr(const wxTextAttr& attr);
  38     //@}
  39
  40     /**
  41         Applies the attributes in @a style to the original object, but not those
  42         attributes from @a style that are the same as those in @a compareWith (if passed).
  43     */
  44     bool Apply(const wxTextAttr& style,
  45                const wxTextAttr* compareWith = NULL);
  46
  47     /**
  48         Creates a font from the font attributes.
  49     */
  50     wxFont CreateFont() const;
  51
  52     /**
  53         Returns the alignment flags.
  54         See SetAlignment() for a list of available styles.
  55     */
  56     wxTextAttrAlignment GetAlignment() const;
  57
  58     /**
  59         Returns the background colour.
  60     */
  61     const wxColour GetBackgroundColour() const;
  62
  63     /**
  64         Returns a string containing the name of the font associated with the bullet
  65         symbol.
  66         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
  67     */
  68     const wxString GetBulletFont() const;
  69
  70     /**
  71         Returns the standard bullet name, applicable if the bullet style is
  72         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
  73         Currently the following standard bullet names are supported:
  74          @c standard/circle
  75          @c standard/square
  76          @c standard/diamond
  77          @c standard/triangle
  78         For wxRichTextCtrl users only: if you wish your rich text controls to support
  79         further bullet graphics, you can derive a
  80         class from wxRichTextRenderer or wxRichTextStdRenderer, override @c
  81         DrawStandardBullet and @c EnumerateStandardBulletNames, and
  82         set an instance of the class using wxRichTextBuffer::SetRenderer.
  83     */
  84     const wxString GetBulletName() const;
  85
  86     /**
  87         Returns the bullet number.
  88     */
  89     int GetBulletNumber() const;
  90
  91     /**
  92         Returns the bullet style.
  93         See SetBulletStyle() for a list of available styles.
  94     */
  95     int GetBulletStyle() const;
  96
  97     /**
  98         Returns the bullet text, which could be a symbol, or (for example) cached
  99         outline text.
 100     */
 101     const wxString GetBulletText() const;
 102
 103     /**
 104         Returns the name of the character style.
 105     */
 106     const wxString GetCharacterStyleName() const;
 107
 108     /**
 109         Returns flags indicating which attributes are applicable.
 110         See SetFlags() for a list of available flags.
 111     */
 112     long GetFlags() const;
 113
 114     /**
 115         Creates and returns a font specified by the font attributes in the wxTextAttr
 116         object. Note that
 117         wxTextAttr does not store a wxFont object, so this is only a temporary font.
 118         For greater
 119         efficiency, access the font attributes directly.
 120     */
 121     wxFont GetFont() const;
 122
 123     /**
 124         Gets the font attributes from the given font, using only the attributes
 125         specified by @a flags.
 126     */
 127     bool GetFontAttributes(const wxFont& font,
 128                            int flags = wxTEXT_ATTR_FONT);
 129
 130     /**
 131         Returns the font encoding.
 132     */
 133     wxFontEncoding GetFontEncoding() const;
 134
 135     /**
 136         Returns the font face name.
 137     */
 138     const wxString GetFontFaceName() const;
 139
 140     /**
 141         Returns the font size in points.
 142     */
 143     int GetFontSize() const;
 144
 145     /**
 146         Returns the font style.
 147     */
 148     int GetFontStyle() const;
 149
 150     /**
 151         Returns @true if the font is underlined.
 152     */
 153     bool GetFontUnderlined() const;
 154
 155     /**
 156         Returns the font weight.
 157     */
 158     int GetFontWeight() const;
 159
 160     /**
 161         Returns the left indent in tenths of a millimetre.
 162     */
 163     long GetLeftIndent() const;
 164
 165     /**
 166         Returns the left sub-indent in tenths of a millimetre.
 167     */
 168     long GetLeftSubIndent() const;
 169
 170     /**
 171         Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL,
 172         wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE.
 173     */
 174     int GetLineSpacing() const;
 175
 176     /**
 177         Returns the name of the list style.
 178     */
 179     const wxString GetListStyleName() const;
 180
 181     /**
 182         Returns the outline level.
 183     */
 184     bool GetOutlineLevel() const;
 185
 186     /**
 187         Returns the space in tenths of a millimeter after the paragraph.
 188     */
 189     int GetParagraphSpacingAfter() const;
 190
 191     /**
 192         Returns the space in tenths of a millimeter before the paragraph.
 193     */
 194     int GetParagraphSpacingBefore() const;
 195
 196     /**
 197         Returns the name of the paragraph style.
 198     */
 199     const wxString GetParagraphStyleName() const;
 200
 201     /**
 202         Returns the right indent in tenths of a millimeter.
 203     */
 204     long GetRightIndent() const;
 205
 206     /**
 207         Returns an array of tab stops, each expressed in tenths of a millimeter. Each
 208         stop
 209         is measured from the left margin and therefore each value must be larger than
 210         the last.
 211     */
 212     const wxArrayInt GetTabs() const;
 213
 214     /**
 215         Returns the text foreground colour.
 216     */
 217     const wxColour GetTextColour() const;
 218
 219     /**
 220         Returns the text effect bits of interest. See SetFlags() for further
 221         information.
 222     */
 223     int GetTextEffectFlags() const;
 224
 225     /**
 226         Returns the text effects, a bit list of styles. See SetTextEffects() for
 227         details.
 228     */
 229     int GetTextEffects() const;
 230
 231     /**
 232         Returns the URL for the content. Content with wxTEXT_ATTR_URL style
 233         causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
 234         generates
 235         a wxTextUrlEvent when the content is clicked.
 236     */
 237     const wxString GetURL() const;
 238
 239     /**
 240         Returns @true if the attribute object specifies alignment.
 241     */
 242     bool HasAlignment() const;
 243
 244     /**
 245         Returns @true if the attribute object specifies a background colour.
 246     */
 247     bool HasBackgroundColour() const;
 248
 249     /**
 250         Returns @true if the attribute object specifies a standard bullet name.
 251     */
 252     bool HasBulletName() const;
 253
 254     /**
 255         Returns @true if the attribute object specifies a bullet number.
 256     */
 257     bool HasBulletNumber() const;
 258
 259     /**
 260         Returns @true if the attribute object specifies a bullet style.
 261     */
 262     bool HasBulletStyle() const;
 263
 264     /**
 265         Returns @true if the attribute object specifies bullet text (usually
 266         specifying a symbol).
 267     */
 268     bool HasBulletText() const;
 269
 270     /**
 271         Returns @true if the attribute object specifies a character style name.
 272     */
 273     bool HasCharacterStyleName() const;
 274
 275     /**
 276         Returns @true if the @a flag is present in the attribute object's flag
 277         bitlist.
 278     */
 279     bool HasFlag(long flag) const;
 280
 281     /**
 282         Returns @true if the attribute object specifies any font attributes.
 283     */
 284     bool HasFont() const;
 285
 286     /**
 287         Returns @true if the attribute object specifies an encoding.
 288     */
 289     bool HasFontEncoding() const;
 290
 291     /**
 292         Returns @true if the attribute object specifies a font face name.
 293     */
 294     bool HasFontFaceName() const;
 295
 296     /**
 297         Returns @true if the attribute object specifies italic style.
 298     */
 299     bool HasFontItalic() const;
 300
 301     /**
 302         Returns @true if the attribute object specifies a font point size.
 303     */
 304     bool HasFontSize() const;
 305
 306     /**
 307         Returns @true if the attribute object specifies either underlining or no
 308         underlining.
 309     */
 310     bool HasFontUnderlined() const;
 311
 312     /**
 313         Returns @true if the attribute object specifies font weight (bold, light or
 314         normal).
 315     */
 316     bool HasFontWeight() const;
 317
 318     /**
 319         Returns @true if the attribute object specifies a left indent.
 320     */
 321     bool HasLeftIndent() const;
 322
 323     /**
 324         Returns @true if the attribute object specifies line spacing.
 325     */
 326     bool HasLineSpacing() const;
 327
 328     /**
 329         Returns @true if the attribute object specifies a list style name.
 330     */
 331     bool HasListStyleName() const;
 332
 333     /**
 334         Returns @true if the attribute object specifies an outline level.
 335     */
 336     bool HasOutlineLevel() const;
 337
 338     /**
 339         Returns @true if the attribute object specifies a page break before this
 340         paragraph.
 341     */
 342     bool HasPageBreak() const;
 343
 344     /**
 345         Returns @true if the attribute object specifies spacing after a paragraph.
 346     */
 347     bool HasParagraphSpacingAfter() const;
 348
 349     /**
 350         Returns @true if the attribute object specifies spacing before a paragraph.
 351     */
 352     bool HasParagraphSpacingBefore() const;
 353
 354     /**
 355         Returns @true if the attribute object specifies a paragraph style name.
 356     */
 357     bool HasParagraphStyleName() const;
 358
 359     /**
 360         Returns @true if the attribute object specifies a right indent.
 361     */
 362     bool HasRightIndent() const;
 363
 364     /**
 365         Returns @true if the attribute object specifies tab stops.
 366     */
 367     bool HasTabs() const;
 368
 369     /**
 370         Returns @true if the attribute object specifies a text foreground colour.
 371     */
 372     bool HasTextColour() const;
 373
 374     /**
 375         Returns @true if the attribute object specifies text effects.
 376     */
 377     bool HasTextEffects() const;
 378
 379     /**
 380         Returns @true if the attribute object specifies a URL.
 381     */
 382     bool HasURL() const;
 383
 384     /**
 385         Returns @true if the object represents a character style, that is,
 386         the flags specify a font or a text background or foreground colour.
 387     */
 388     bool IsCharacterStyle() const;
 389
 390     /**
 391         Returns @false if we have any attributes set, @true otherwise.
 392     */
 393     bool IsDefault() const;
 394
 395     /**
 396         Returns @true if the object represents a paragraph style, that is,
 397         the flags specify alignment, indentation, tabs, paragraph spacing, or
 398         bullet style.
 399     */
 400     bool IsParagraphStyle() const;
 401
 402     //@{
 403     /**
 404         Creates a new @c wxTextAttr which is a merge of @a base and
 405         @a overlay. Properties defined in @a overlay take precedence over those
 406         in @a base. Properties undefined/invalid in both are undefined in the
 407         result.
 408     */
 409     void Merge(const wxTextAttr& overlay);
 410     static wxTextAttr Merge(const wxTextAttr& base,
 411                             const wxTextAttr& overlay);
 412     //@}
 413
 414     /**
 415         Sets the paragraph alignment. These are the possible values for @a alignment:
 416
 417         Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification
 418         may be supported
 419         when printing or previewing, only.
 420     */
 421     void SetAlignment(wxTextAttrAlignment alignment);
 422
 423     /**
 424         Sets the background colour.
 425     */
 426     void SetBackgroundColour(const wxColour& colBack);
 427
 428     /**
 429         Sets the name of the font associated with the bullet symbol.
 430         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
 431     */
 432     void SetBulletFont(const wxString& font);
 433
 434     /**
 435         Sets the standard bullet name, applicable if the bullet style is
 436         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
 437         See GetBulletName() for a list
 438         of supported names, and how to expand the range of supported types.
 439     */
 440     void SetBulletName(const wxString& name);
 441
 442     /**
 443         Sets the bullet number.
 444     */
 445     void SetBulletNumber(int n);
 446
 447     /**
 448         Sets the bullet style. The following styles can be passed:
 449
 450         Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported.
 451     */
 452     void SetBulletStyle(int style);
 453
 454     /**
 455         Sets the bullet text, which could be a symbol, or (for example) cached outline
 456         text.
 457     */
 458     void SetBulletText(const wxString text);
 459
 460     /**
 461         Sets the character style name.
 462     */
 463     void SetCharacterStyleName(const wxString& name);
 464
 465     /**
 466         Sets the flags determining which styles are being specified. The following
 467         flags can be passed in a bitlist:
 468     */
 469     void SetFlags(long flags);
 470
 471     /**
 472         Sets the attributes for the given font. Note that wxTextAttr does not store an
 473         actual wxFont object.
 474     */
 475     void SetFont(const wxFont& font);
 476
 477     /**
 478         Sets the font encoding.
 479     */
 480     void SetFontEncoding(wxFontEncoding encoding);
 481
 482     /**
 483         Sets the paragraph alignment.
 484     */
 485     void SetFontFaceName(const wxString& faceName);
 486
 487     /**
 488         Sets the font size in points.
 489     */
 490     void SetFontSize(int pointSize);
 491
 492     /**
 493         Sets the font style (normal, italic or slanted).
 494     */
 495     void SetFontStyle(int fontStyle);
 496
 497     /**
 498         Sets the font underlining.
 499     */
 500     void SetFontUnderlined(bool underlined);
 501
 502     /**
 503         Sets the font weight.
 504     */
 505     void SetFontWeight(int fontWeight);
 506
 507     /**
 508         Sets the left indent and left subindent in tenths of a millimetre.
 509         The sub-indent is an offset from the left of the paragraph, and is used for all
 510         but the
 511         first line in a paragraph. A positive value will cause the first line to appear
 512         to the left
 513         of the subsequent lines, and a negative value will cause the first line to be
 514         indented
 515         relative to the subsequent lines.
 516         wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
 517         the distance between
 518         the margin and the bullet. The content of the paragraph, including the first
 519         line, starts
 520         at leftMargin + leftSubIndent. So the distance between the left edge of the
 521         bullet and the
 522         left of the actual paragraph is leftSubIndent.
 523     */
 524     void SetLeftIndent(int indent, int subIndent = 0);
 525
 526     /**
 527         Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
 528         15 means 1.5 spacing, and 20 means double spacing. The following constants are
 529         defined for convenience:
 530     */
 531     void SetLineSpacing(int spacing);
 532
 533     /**
 534         Sets the list style name.
 535     */
 536     void SetListStyleName(const wxString& name);
 537
 538     /**
 539         Specifies the outline level. Zero represents normal text. At present, the
 540         outline level is
 541         not used, but may be used in future for determining list levels and for
 542         applications
 543         that need to store document structure information.
 544     */
 545     void SetOutlineLevel(int level);
 546
 547     /**
 548         Specifies a page break before this paragraph.
 549     */
 550     void SetPageBreak(bool pageBreak = true);
 551
 552     /**
 553         Sets the spacing after a paragraph, in tenths of a millimetre.
 554     */
 555     void SetParagraphSpacingAfter(int spacing);
 556
 557     /**
 558         Sets the spacing before a paragraph, in tenths of a millimetre.
 559     */
 560     void SetParagraphSpacingBefore(int spacing);
 561
 562     /**
 563         Sets the name of the paragraph style.
 564     */
 565     void SetParagraphStyleName(const wxString& name);
 566
 567     /**
 568         Sets the right indent in tenths of a millimetre.
 569     */
 570     void SetRightIndent(int indent);
 571
 572     /**
 573         Sets the tab stops, expressed in tenths of a millimetre.
 574         Each stop is measured from the left margin and therefore each value must be
 575         larger than the last.
 576     */
 577     void SetTabs(const wxArrayInt& tabs);
 578
 579     /**
 580         Sets the text foreground colout.
 581     */
 582     void SetTextColour(const wxColour& colText);
 583
 584     /**
 585         Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS
 586         to SetFlags().
 587         See SetFlags() for further information.
 588     */
 589     void SetTextEffectFlags(int flags);
 590
 591     /**
 592         Sets the text effects, a bit list of styles.
 593         The following styles can be passed:
 594
 595         Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
 596         are implemented.
 597         wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
 598         of the actual buffer
 599         text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text.
 600         To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
 601         SetTextEffectFlags() with the styles (taken from the
 602         above set) that you are interested in setting.
 603     */
 604     void SetTextEffects(int effects);
 605
 606     /**
 607         Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
 608         style
 609         causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
 610         generates
 611         a wxTextUrlEvent when the content is clicked.
 612     */
 613     void SetURL(const wxString& url);
 614
 615     /**
 616         Assignment from a wxTextAttr object.
 617     */
 618     void operator operator=(const wxTextAttr& attr);
 619 };
 620
 621 /**
 622     Describes the possible return values of wxTextCtrl::HitTest().
 623
 624     The element names correspond to the relationship between the point asked
 625     for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
 626     is before (leftward or upward) it and so on.
 627  */
 628 enum wxTextCtrlHitTestResult
 629 {
 630     /// Indicates that wxTextCtrl::HitTest() is not implemented on this
 631     /// platform.
 632     wxTE_HT_UNKNOWN = -2,
 633
 634     /// The point is before the character returned.
 635     wxTE_HT_BEFORE,
 636
 637     /// The point is directly on the character returned.
 638     wxTE_HT_ON_TEXT,
 639
 640     /// The point is below the last line of the control.
 641     wxTE_HT_BELOW,
 642
 643     /// The point is beyond the end of line containing the character returned.
 644     wxTE_HT_BEYOND
 645 };
 646
 647
 648 /**
 649     @class wxTextCtrl
 650
 651     A text control allows text to be displayed and edited.
 652
 653     It may be single line or multi-line.
 654
 655     @beginStyleTable
 656     @style{wxTE_PROCESS_ENTER}
 657            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
 658            (otherwise pressing Enter key is either processed internally by the
 659            control or used for navigation between dialog controls).
 660     @style{wxTE_PROCESS_TAB}
 661            The control will receive wxEVT_CHAR events for TAB pressed -
 662            normally, TAB is used for passing to the next control in a dialog
 663            instead. For the control created with this style, you can still use
 664            Ctrl-Enter to pass to the next control from the keyboard.
 665     @style{wxTE_MULTILINE}
 666            The text control allows multiple lines.
 667     @style{wxTE_PASSWORD}
 668            The text will be echoed as asterisks.
 669     @style{wxTE_READONLY}
 670            The text will not be user-editable.
 671     @style{wxTE_RICH}
 672            Use rich text control under Win32, this allows to have more than
 673            64KB of text in the control even under Win9x. This style is ignored
 674            under other platforms.
 675     @style{wxTE_RICH2}
 676            Use rich text control version 2.0 or 3.0 under Win32, this style is
 677            ignored under other platforms
 678     @style{wxTE_AUTO_URL}
 679            Highlight the URLs and generate the wxTextUrlEvents when mouse
 680            events occur over them. This style is only supported for wxTE_RICH
 681            Win32 and multi-line wxGTK2 text controls.
 682     @style{wxTE_NOHIDESEL}
 683            By default, the Windows text control doesn't show the selection
 684            when it doesn't have focus - use this style to force it to always
 685            show it. It doesn't do anything under other platforms.
 686     @style{wxHSCROLL}
 687            A horizontal scrollbar will be created and used, so that text won't
 688            be wrapped. No effect under wxGTK1.
 689     @style{wxTE_NO_VSCROLL}
 690            For multiline controls only: vertical scrollbar will never be
 691            created. This limits the amount of text which can be entered into
 692            the control to what can be displayed in it under MSW but not under
 693            GTK2. Currently not implemented for the other platforms.
 694     @style{wxTE_LEFT}
 695            The text in the control will be left-justified (default).
 696     @style{wxTE_CENTRE}
 697            The text in the control will be centered (currently wxMSW and
 698            wxGTK2 only).
 699     @style{wxTE_RIGHT}
 700            The text in the control will be right-justified (currently wxMSW
 701            and wxGTK2 only).
 702     @style{wxTE_DONTWRAP}
 703            Same as wxHSCROLL style: don't wrap at all, show horizontal
 704            scrollbar instead.
 705     @style{wxTE_CHARWRAP}
 706            Wrap the lines too long to be shown entirely at any position
 707            (wxUniv and wxGTK2 only).
 708     @style{wxTE_WORDWRAP}
 709            Wrap the lines too long to be shown entirely at word boundaries
 710            (wxUniv and wxGTK2 only).
 711     @style{wxTE_BESTWRAP}
 712            Wrap the lines at word boundaries or at any other character if
 713            there are words longer than the window width (this is the default).
 714     @style{wxTE_CAPITALIZE}
 715            On PocketPC and Smartphone, causes the first letter to be
 716            capitalized.
 717     @endStyleTable
 718
 719
 720     @section textctrl_text_format wxTextCtrl Text Format
 721
 722     The multiline text controls always store the text as a sequence of lines
 723     separated by @c '\\n' characters, i.e. in the Unix text format even on
 724     non-Unix platforms. This allows the user code to ignore the differences
 725     between the platforms but at a price: the indices in the control such as
 726     those returned by GetInsertionPoint() or GetSelection() can @b not be used
 727     as indices into the string returned by GetValue() as they're going to be
 728     slightly off for platforms using @c "\\r\\n" as separator (as Windows
 729     does).
 730
 731     Instead, if you need to obtain a substring between the 2 indices obtained
 732     from the control with the help of the functions mentioned above, you should
 733     use GetRange(). And the indices themselves can only be passed to other
 734     methods, for example SetInsertionPoint() or SetSelection().
 735
 736     To summarize: never use the indices returned by (multiline) wxTextCtrl as
 737     indices into the string it contains, but only as arguments to be passed
 738     back to the other wxTextCtrl methods. This problem doesn't arise for
 739     single-line platforms however where the indices in the control do
 740     correspond to the positions in the value string.
 741
 742
 743     @section textctrl_styles wxTextCtrl Styles.
 744
 745     Multi-line text controls support styling, i.e. provide a possibility to set
 746     colours and font for individual characters in it (note that under Windows
 747     @c wxTE_RICH style is required for style support). To use the styles you
 748     can either call SetDefaultStyle() before inserting the text or call
 749     SetStyle() later to change the style of the text already in the control
 750     (the first solution is much more efficient).
 751
 752     In either case, if the style doesn't specify some of the attributes (for
 753     example you only want to set the text colour but without changing the font
 754     nor the text background), the values of the default style will be used for
 755     them. If there is no default style, the attributes of the text control
 756     itself are used.
 757
 758     So the following code correctly describes what it does: the second call to
 759     SetDefaultStyle() doesn't change the text foreground colour (which stays
 760     red) while the last one doesn't change the background colour (which stays
 761     grey):
 762
 763     @code
 764     text->SetDefaultStyle(wxTextAttr(*wxRED));
 765     text->AppendText("Red text\n");
 766     text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
 767     text->AppendText("Red on grey text\n");
 768     text->SetDefaultStyle(wxTextAttr(*wxBLUE);
 769     text->AppendText("Blue on grey text\n");
 770     @endcode
 771
 772
 773     @section textctrl_cpp_streams wxTextCtrl and C++ Streams
 774
 775     This class multiply-inherits from @c std::streambuf (except for some really
 776     old compilers using non-standard iostream library), allowing code such as
 777     the following:
 778
 779     @code
 780     wxTextCtrl *control = new wxTextCtrl(...);
 781
 782     ostream stream(control)
 783
 784     stream << 123.456 << " some text\n";
 785     stream.flush();
 786     @endcode
 787
 788     Note that even if your compiler doesn't support this (the symbol
 789     @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use
 790     wxTextCtrl itself in a stream-like manner:
 791
 792     @code
 793     wxTextCtrl *control = new wxTextCtrl(...);
 794
 795     *control << 123.456 << " some text\n";
 796     @endcode
 797
 798     However the possibility to create an ostream associated with wxTextCtrl may
 799     be useful if you need to redirect the output of a function taking an
 800     ostream as parameter to a text control.
 801
 802     Another commonly requested need is to redirect @c std::cout to the text
 803     control. This may be done in the following way:
 804
 805     @code
 806     #include <iostream>
 807
 808     wxTextCtrl *control = new wxTextCtrl(...);
 809
 810     std::streambuf *sbOld = std::cout.rdbuf();
 811     std::cout.rdbuf(control);
 812
 813     // use cout as usual, the output appears in the text control
 814     ...
 815
 816     std::cout.rdbuf(sbOld);
 817     @endcode
 818
 819     But wxWidgets provides a convenient class to make it even simpler so
 820     instead you may just do
 821
 822     @code
 823     #include <iostream>
 824
 825     wxTextCtrl *control = new wxTextCtrl(...);
 826
 827     wxStreamToTextRedirector redirect(control);
 828
 829     // all output to cout goes into the text control until the exit from
 830     // current scope
 831     @endcode
 832
 833     See wxStreamToTextRedirector for more details.
 834
 835
 836     @section textctrl_event_handling Event Handling.
 837
 838     The following commands are processed by default event handlers in
 839     wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c
 840     wxID_REDO. The associated UI update events are also processed
 841     automatically, when the control has the focus.
 842
 843     To process input from a text control, use these event handler macros to
 844     direct input to member functions that take a wxCommandEvent argument.
 845
 846     @beginEventTable{wxCommandEvent}
 847     @event{EVT_TEXT(id, func)}
 848         Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
 849         changes. Notice that this event will be sent when the text controls
 850         contents changes -- whether this is due to user input or comes from the
 851         program itself (for example, if SetValue() is called); see
 852         ChangeValue() for a function which does not send this event. This
 853         event is however not sent during the control creation.
 854     @event{EVT_TEXT_ENTER(id, func)}
 855         Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
 856         pressed in a text control which must have wxTE_PROCESS_ENTER style for
 857         this event to be generated.
 858     @event{EVT_TEXT_URL(id, func)}
 859         A mouse event occurred over an URL in the text control (wxMSW and
 860         wxGTK2 only currently).
 861     @event{EVT_TEXT_MAXLEN(id, func)}
 862         This event is generated when the user tries to enter more text into the
 863         control than the limit set by SetMaxLength(), see its description.
 864     @endEventTable
 865
 866     @library{wxcore}
 867     @category{ctrl}
 868     <!-- @appearance{textctrl.png} -->
 869
 870     @see wxTextCtrl::Create, wxValidator
 871 */
 872 class wxTextCtrl : public wxControl
 873 {
 874 public:
 875     //@{
 876     /**
 877        Constructor, creating and showing a text control.
 878        @see Create()
 879     */
 880          wxTextCtrl();
 881
 882     /**
 883         Constructor, creating and showing a text control.
 884
 885         @param parent
 886             Parent window. Should not be @NULL.
 887         @param id
 888             Control identifier. A value of -1 denotes a default value.
 889         @param value
 890             Default text value.
 891         @param pos
 892             Text control position.
 893         @param size
 894             Text control size.
 895         @param style
 896             Window style. See wxTextCtrl.
 897         @param validator
 898             Window validator.
 899         @param name
 900             Window name.
 901
 902         @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
 903             created for multi-line text controls. Without a horizontal
 904             scrollbar, text lines that don't fit in the control's size will be
 905             wrapped (but no newline character is inserted). Single line
 906             controls don't have a horizontal scrollbar, the text is
 907             automatically scrolled so that the insertion point is always
 908             visible.
 909
 910         @see Create(), wxValidator
 911     */
 912     wxTextCtrl(wxWindow* parent, wxWindowID id,
 913                const wxString& value = "",
 914                const wxPoint& pos = wxDefaultPosition,
 915                const wxSize& size = wxDefaultSize,
 916                long style = 0,
 917                const wxValidator& validator = wxDefaultValidator,
 918                const wxString& name = wxTextCtrlNameStr);
 919     //@}
 920
 921     /**
 922         Destructor, destroying the text control.
 923     */
 924     virtual ~wxTextCtrl();
 925
 926     /**
 927         Appends the text to the end of the text control.
 928
 929         @param text
 930             Text to write to the text control.
 931
 932         @remarks After the text is appended, the insertion point will be at the
 933             end of the text control. If this behaviour is not desired, the
 934             programmer should use GetInsertionPoint and SetInsertionPoint.
 935
 936         @see WriteText()
 937     */
 938     void AppendText(const wxString& text);
 939
 940     /**
 941         Call this function to enable auto-completion of the text typed in a
 942         single-line text control using the given @a choices.
 943
 944         Notice that currently this function is only implemented in wxGTK2 and
 945         wxMSW ports and does nothing under the other platforms.
 946
 947         @since 2.9.0
 948
 949         @return
 950             @true if the auto-completion was enabled or @false if the operation
 951             failed, typically because auto-completion is not supported by the
 952             current platform.
 953
 954         @see AutoCompleteFileNames()
 955     */
 956     bool AutoComplete(const wxArrayString& choices);
 957
 958     /**
 959         Call this function to enable auto-completion of the text typed in a
 960         single-line text control using all valid file system paths.
 961
 962         Notice that currently this function is only implemented in wxGTK2 port
 963         and does nothing under the other platforms.
 964
 965         @since 2.9.0
 966
 967         @return
 968             @true if the auto-completion was enabled or @false if the operation
 969             failed, typically because auto-completion is not supported by the
 970             current platform.
 971
 972         @see AutoComplete()
 973     */
 974     bool AutoCompleteFileNames();
 975
 976     /**
 977         Returns @true if the selection can be copied to the clipboard.
 978     */
 979     virtual bool CanCopy();
 980
 981     /**
 982         Returns @true if the selection can be cut to the clipboard.
 983     */
 984     virtual bool CanCut();
 985
 986     /**
 987         Returns @true if the contents of the clipboard can be pasted into the
 988         text control.
 989
 990         On some platforms (Motif, GTK) this is an approximation and returns
 991         @true if the control is editable, @false otherwise.
 992     */
 993     virtual bool CanPaste();
 994
 995     /**
 996         Returns @true if there is a redo facility available and the last
 997         operation can be redone.
 998     */
 999     virtual bool CanRedo();
1000
1001     /**
1002         Returns @true if there is an undo facility available and the last
1003         operation can be undone.
1004     */
1005     virtual bool CanUndo();
1006
1007     /**
1008         Sets the text value and marks the control as not-modified (which means
1009         that IsModified() would return @false immediately after the call to
1010         SetValue).
1011
1012         This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
1013         event but otherwise is identical to SetValue().
1014         See @ref overview_progevent "this topic" for more information.
1015
1016         @since 2.7.1
1017
1018         @param value
1019             The new value to set. It may contain newline characters if the text
1020             control is multi-line.
1021     */
1022     virtual void ChangeValue(const wxString& value);
1023
1024     /**
1025         Clears the text in the control.
1026
1027         Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
1028         event, i.e. its effect is identical to calling @c SetValue("").
1029     */
1030     virtual void Clear();
1031
1032     /**
1033         Copies the selected text to the clipboard.
1034     */
1035     virtual void Copy();
1036
1037     /**
1038         Creates the text control for two-step construction.
1039
1040         This method should be called if the default constructor was used for
1041         the control creation. Its parameters have the same meaning as for the
1042         non-default constructor.
1043     */
1044     bool Create(wxWindow* parent, wxWindowID id,
1045                 const wxString& value = "",
1046                 const wxPoint& pos = wxDefaultPosition,
1047                 const wxSize& size = wxDefaultSize,
1048                 long style = 0,
1049                 const wxValidator& validator = wxDefaultValidator,
1050                 const wxString& name = wxTextCtrlNameStr);
1051
1052     /**
1053         Copies the selected text to the clipboard and removes the selection.
1054     */
1055     virtual void Cut();
1056
1057     /**
1058         Resets the internal modified flag as if the current changes had been
1059         saved.
1060     */
1061     virtual void DiscardEdits();
1062
1063     /**
1064         This functions inserts into the control the character which would have
1065         been inserted if the given key event had occurred in the text control.
1066
1067         The @a event object should be the same as the one passed to @c
1068         EVT_KEY_DOWN handler previously by wxWidgets. Please note that this
1069         function doesn't currently work correctly for all keys under any
1070         platform but MSW.
1071
1072         @return
1073             @true if the event resulted in a change to the control, @false
1074             otherwise.
1075     */
1076     virtual bool EmulateKeyPress(const wxKeyEvent& event);
1077
1078     /**
1079         Returns the style currently used for the new text.
1080
1081         @see SetDefaultStyle()
1082     */
1083     const wxTextAttr GetDefaultStyle() const;
1084
1085     /**
1086         Returns the insertion point, or cursor, position.
1087
1088         This is defined as the zero based index of the character position to
1089         the right of the insertion point. For example, if the insertion point
1090         is at the end of the single-line text control, it is equal to both
1091         GetLastPosition() and GetValue().length() (but notice that the latter
1092         equality is not necessarily true for multiline edit controls which may
1093         use multiple new line characters).
1094     */
1095     virtual long GetInsertionPoint() const;
1096
1097     /**
1098         Returns the zero based index of the last position in the text control,
1099         which is equal to the number of characters in the control.
1100     */
1101     virtual wxTextPos GetLastPosition() const;
1102
1103     /**
1104         Gets the length of the specified line, not including any trailing
1105         newline character(s).
1106
1107         @param lineNo
1108             Line number (starting from zero).
1109
1110         @return
1111             The length of the line, or -1 if @a lineNo was invalid.
1112     */
1113     virtual int GetLineLength(long lineNo) const;
1114
1115     /**
1116         Returns the contents of a given line in the text control, not including
1117         any trailing newline character(s).
1118
1119         @param lineNo
1120             The line number, starting from zero.
1121
1122         @return
1123             The contents of the line.
1124     */
1125     virtual wxString GetLineText(long lineNo) const;
1126
1127     /**
1128         Returns the number of lines in the text control buffer.
1129
1130         @remarks Note that even empty text controls have one line (where the
1131                  insertion point is), so GetNumberOfLines() never
1132                  returns 0.
1133     */
1134     virtual int GetNumberOfLines() const;
1135
1136     /**
1137         Returns the string containing the text starting in the positions
1138         @a from and up to @a to in the control.
1139
1140         The positions must have been returned by another wxTextCtrl method.
1141         Please note that the positions in a multiline wxTextCtrl do @b not
1142         correspond to the indices in the string returned by GetValue() because
1143         of the different new line representations (@c CR or @c CR LF) and so
1144         this method should be used to obtain the correct results instead of
1145         extracting parts of the entire value. It may also be more efficient,
1146         especially if the control contains a lot of data.
1147     */
1148     virtual wxString GetRange(long from, long to) const;
1149
1150     /**
1151         Gets the current selection span.
1152
1153         If the returned values are equal, there was no selection. Please note
1154         that the indices returned may be used with the other wxTextCtrl methods
1155         but don't necessarily represent the correct indices into the string
1156         returned by GetValue() for multiline controls under Windows (at least,)
1157         you should use GetStringSelection() to get the selected text.
1158
1159         @param from
1160             The returned first position.
1161         @param to
1162             The returned last position.
1163     */
1164     virtual void GetSelection(long* from, long* to) const;
1165
1166     /**
1167         Gets the text currently selected in the control.
1168
1169         If there is no selection, the returned string is empty.
1170     */
1171     virtual wxString GetStringSelection();
1172
1173     /**
1174         Returns the style at this position in the text control.
1175
1176         Not all platforms support this function.
1177
1178         @return
1179             @true on success, @false if an error occurred (this may also mean
1180             that the styles are not supported under this platform).
1181
1182         @see SetStyle(), wxTextAttr
1183     */
1184     virtual bool GetStyle(long position, wxTextAttr& style);
1185
1186     /**
1187         Gets the contents of the control.
1188         Notice that for a multiline text control, the lines will be separated
1189         by (Unix-style) @c \\n characters, even under Windows where they are
1190         separated by a @c \\r\\n sequence in the native control.
1191     */
1192     virtual wxString GetValue() const;
1193
1194     /**
1195         This function finds the character at the specified position expressed
1196         in pixels.
1197
1198         If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
1199         character closest to this position are returned in the @a col and @a
1200         row parameters (unless the pointers are @NULL which is allowed). Please
1201         note that this function is currently only implemented in wxUniv, wxMSW
1202         and wxGTK2 ports.
1203
1204         @see PositionToXY(), XYToPosition()
1205     */
1206     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1207                                     wxTextCoord col,
1208                                     wxTextCoord row) const;
1209
1210     /**
1211         Returns @true if the controls contents may be edited by user (note that
1212         it always can be changed by the program).
1213
1214         In other words, this functions returns @true if the control hasn't been
1215         put in read-only mode by a previous call to SetEditable().
1216     */
1217     virtual bool IsEditable() const;
1218
1219     /**
1220         Returns @true if the control is currently empty.
1221
1222         This is the same as @c GetValue().empty() but can be much more
1223         efficient for the multiline controls containing big amounts of text.
1224
1225         @since 2.7.1
1226     */
1227     virtual bool IsEmpty() const;
1228
1229     /**
1230         Returns @true if the text has been modified by user.
1231
1232         Note that calling SetValue() doesn't make the control modified.
1233
1234         @see MarkDirty()
1235     */
1236     virtual bool IsModified() const;
1237
1238     /**
1239         Returns @true if this is a multi line edit control and @false
1240         otherwise.
1241
1242         @see IsSingleLine()
1243     */
1244     bool IsMultiLine() const;
1245
1246     /**
1247         Returns @true if this is a single line edit control and @false
1248         otherwise.
1249
1250         @see @ref IsSingleLine() IsMultiLine
1251     */
1252     bool IsSingleLine() const;
1253
1254     /**
1255         Loads and displays the named file, if it exists.
1256
1257         @param filename
1258             The filename of the file to load.
1259         @param fileType
1260             The type of file to load. This is currently ignored in wxTextCtrl.
1261
1262         @return
1263             @true if successful, @false otherwise.
1264     */
1265     bool LoadFile(const wxString& filename,
1266                   int fileType = wxTEXT_TYPE_ANY);
1267
1268     /**
1269         Mark text as modified (dirty).
1270
1271         @see IsModified()
1272     */
1273     virtual void MarkDirty();
1274
1275     /**
1276         This event handler function implements default drag and drop behaviour,
1277         which is to load the first dropped file into the control.
1278
1279         @param event
1280             The drop files event.
1281
1282         @remarks This is not implemented on non-Windows platforms.
1283
1284         @see wxDropFilesEvent
1285     */
1286     void OnDropFiles(wxDropFilesEvent& event);
1287
1288     /**
1289         Pastes text from the clipboard to the text item.
1290     */
1291     virtual void Paste();
1292
1293     /**
1294         Converts given position to a zero-based column, line number pair.
1295
1296         @param pos
1297             Position.
1298         @param x
1299             Receives zero based column number.
1300         @param y
1301             Receives zero based line number.
1302
1303         @return
1304             @true on success, @false on failure (most likely due to a too large
1305             position parameter).
1306
1307         @see XYToPosition()
1308     */
1309     virtual bool PositionToXY(long pos, long* x, long* y) const;
1310
1311     /**
1312         If there is a redo facility and the last operation can be redone,
1313         redoes the last operation.
1314
1315         Does nothing if there is no redo facility.
1316     */
1317     virtual void Redo();
1318
1319     /**
1320         Removes the text starting at the first given position up to (but not
1321         including) the character at the last position.
1322
1323         @param from
1324             The first position.
1325         @param to
1326             The last position.
1327     */
1328     virtual void Remove(long from, long to);
1329
1330     /**
1331         Replaces the text starting at the first position up to (but not
1332         including) the character at the last position with the given text.
1333
1334         @param from
1335             The first position.
1336         @param to
1337             The last position.
1338         @param value
1339             The value to replace the existing text with.
1340     */
1341     virtual void Replace(long from, long to, const wxString& value);
1342
1343     /**
1344         Saves the contents of the control in a text file.
1345
1346         @param filename
1347             The name of the file in which to save the text.
1348         @param fileType
1349             The type of file to save. This is currently ignored in wxTextCtrl.
1350
1351         @return
1352             @true if the operation was successful, @false otherwise.
1353     */
1354     bool SaveFile(const wxString& filename,
1355                   int fileType = wxTEXT_TYPE_ANY);
1356
1357     /**
1358         Changes the default style to use for the new text which is going to be
1359         added to the control using WriteText() or AppendText().
1360
1361         If either of the font, foreground, or background colour is not set in
1362         @a style, the values of the previous default style are used for them.
1363         If the previous default style didn't set them neither, the global font
1364         or colours of the text control itself are used as fall back. However if
1365         the @a style parameter is the default wxTextAttr, then the default
1366         style is just reset (instead of being combined with the new style which
1367         wouldn't change it at all).
1368
1369         @param style
1370             The style for the new text.
1371
1372         @return
1373             @true on success, @false if an error occurred (this may also mean
1374             that the styles are not supported under this platform).
1375
1376         @see GetDefaultStyle()
1377     */
1378     virtual bool SetDefaultStyle(const wxTextAttr& style);
1379
1380     /**
1381         Makes the text item editable or read-only, overriding the
1382         @b wxTE_READONLY flag.
1383
1384         @param editable
1385             If @true, the control is editable. If @false, the control is
1386             read-only.
1387
1388         @see IsEditable()
1389     */
1390     virtual void SetEditable(const bool editable);
1391
1392     /**
1393         Sets the insertion point at the given position.
1394
1395         @param pos
1396             Position to set.
1397     */
1398     virtual void SetInsertionPoint(long pos);
1399
1400     /**
1401         Sets the insertion point at the end of the text control.
1402
1403         This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
1404         wxTextCtrl::GetLastPosition() argument.
1405     */
1406     virtual void SetInsertionPointEnd();
1407
1408     /**
1409         This function sets the maximum number of characters the user can enter
1410         into the control.
1411
1412         In other words, it allows to limit the text value length to @a len not
1413         counting the terminating @c NUL character. If @a len is 0, the
1414         previously set max length limit, if any, is discarded and the user may
1415         enter as much text as the underlying native text control widget
1416         supports (typically at least 32Kb). If the user tries to enter more
1417         characters into the text control when it already is filled up to the
1418         maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify
1419         the program about it (giving it the possibility to show an explanatory
1420         message, for example) and the extra input is discarded. Note that in
1421         wxGTK this function may only be used with single line text controls.
1422     */
1423     virtual void SetMaxLength(unsigned long len);
1424
1425     /**
1426         Marks the control as being modified by the user or not.
1427
1428         @see MarkDirty(), DiscardEdits()
1429     */
1430     void SetModified(bool modified);
1431
1432     /**
1433         Selects the text starting at the first position up to (but not
1434         including) the character at the last position.
1435
1436         If both parameters are equal to -1 all text in the control is selected.
1437
1438         Notice that the insertion point will be moved to @a from by this
1439         function.
1440
1441         @param from
1442             The first position.
1443         @param to
1444             The last position.
1445
1446         @see SelectAll()
1447     */
1448     virtual void SetSelection(long from, long to);
1449
1450     /**
1451         Selects all text in the control.
1452
1453         @see SetSelection()
1454     */
1455     virtual void SelectAll();
1456
1457     /**
1458         Changes the style of the given range.
1459
1460         If any attribute within @a style is not set, the corresponding
1461         attribute from GetDefaultStyle() is used.
1462
1463         @param start
1464             The start of the range to change.
1465         @param end
1466             The end of the range to change.
1467         @param style
1468             The new style for the range.
1469
1470         @return
1471             @true on success, @false if an error occurred (this may also mean
1472             that the styles are not supported under this platform).
1473
1474         @see GetStyle(), wxTextAttr
1475     */
1476     virtual bool SetStyle(long start, long end, const wxTextAttr& style);
1477
1478     /**
1479         Sets the text value and marks the control as not-modified (which means
1480         that IsModified() would return @false immediately after the call to
1481         SetValue).
1482
1483         Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED
1484         event, to avoid this you can use ChangeValue() instead.
1485
1486         @param value
1487             The new value to set. It may contain newline characters if the text
1488             control is multi-line.
1489     */
1490     virtual void SetValue(const wxString& value);
1491
1492     /**
1493         Makes the line containing the given position visible.
1494
1495         @param pos
1496             The position that should be visible.
1497     */
1498     virtual void ShowPosition(long pos);
1499
1500     /**
1501         If there is an undo facility and the last operation can be undone,
1502         undoes the last operation.
1503
1504         Does nothing if there is no undo facility.
1505     */
1506     virtual void Undo();
1507
1508     /**
1509         Writes the text into the text control at the current insertion position.
1510
1511         @param text
1512             Text to write to the text control.
1513
1514         @remarks Newlines in the text string are the only control characters
1515             allowed, and they will cause appropriate line breaks. See () and
1516             AppendText() for more convenient ways of writing to the window.
1517     */
1518     virtual void WriteText(const wxString& text);
1519
1520     /**
1521         Converts the given zero based column and line number to a position.
1522
1523         @param x
1524             The column number.
1525         @param y
1526             The line number.
1527
1528         @return
1529             The position value, or -1 if x or y was invalid.
1530     */
1531     virtual long XYToPosition(long x, long y) const;
1532
1533     //@{
1534     /**
1535         Operator definitions for appending to a text control.
1536
1537         These operators can be used as with the standard C++ streams, for
1538         example:
1539         @code
1540             wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1541
1542             (*wnd) << "Welcome to text control number " << 1 << ".\n";
1543         @endcode
1544     */
1545
1546     wxTextCtrl& operator<<(const wxString& s);
1547     wxTextCtrl& operator<<(int i);
1548     wxTextCtrl& operator<<(long i);
1549     wxTextCtrl& operator<<(float f);
1550     wxTextCtrl& operator<<(double d);
1551     wxTextCtrl& operator<<(char c);
1552     wxTextCtrl& operator<<(wchar_t c);
1553     //@}
1554 };
1555
1556
1557
1558 /**
1559     @class wxStreamToTextRedirector
1560
1561     This class can be used to (temporarily) redirect all output sent to a C++
1562     ostream object to a wxTextCtrl instead.
1563
1564     @note Some compilers and/or build configurations don't support multiply
1565     inheriting wxTextCtrl from @c std::streambuf in which
1566     case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
1567     option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
1568     specify @c --enable-std_iostreams switch when running configure for this.
1569
1570     Example of usage:
1571
1572     @code
1573     using namespace std;
1574     wxTextCtrl* text = new wxTextCtrl(...);
1575     {
1576         wxStreamToTextRedirector redirect(text);
1577
1578         // this goes to the text control
1579         cout << "Hello, text!" << endl;
1580     }
1581     // this goes somewhere else, presumably to stdout
1582     cout << "Hello, console!" << endl;
1583     @endcode
1584
1585     @library{wxcore}
1586     @category{logging}
1587
1588     @see wxTextCtrl
1589 */
1590 class wxStreamToTextRedirector
1591 {
1592 public:
1593     /**
1594         The constructor starts redirecting output sent to @a ostr or @a cout for
1595         the default parameter value to the text control @a text.
1596
1597         @param text
1598             The text control to append output too, must be non-@NULL
1599         @param ostr
1600             The C++ stream to redirect, cout is used if it is @NULL
1601     */
1602     wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
1603
1604     /**
1605         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1606         and any output sent to the C++ ostream which had been specified at the time of
1607         the object construction will go to its original destination.
1608     */
1609     ~wxStreamToTextRedirector();
1610 };
1611