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