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
 857     @event{EVT_TEXT_ENTER(id, func)}
 858         Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
 859         pressed in a text control which must have wxTE_PROCESS_ENTER style for
 860         this event to be generated.
 861
 862     @event{EVT_TEXT_URL(id, func}}
 863         A mouse event occurred over an URL in the text control (wxMSW and
 864         wxGTK2 only currently).
 865
 866     @event{EVT_TEXT_MAXLEN(id, func}}
 867         This event is generated when the user tries to enter more text into the
 868         control than the limit set by SetMaxLength(), see its description.
 869     @endEventTable
 870
 871     @library{wxcore}
 872     @category{ctrl}
 873     <!-- @appearance{textctrl.png} -->
 874
 875     @see wxTextCtrl::Create, wxValidator
 876 */
 877 class wxTextCtrl : public wxControl
 878 {
 879 public:
 880     //@{
 881     /**
 882         Constructor, creating and showing a text control.
 883
 884         @param parent
 885             Parent window. Should not be @NULL.
 886         @param id
 887             Control identifier. A value of -1 denotes a default value.
 888         @param value
 889             Default text value.
 890         @param pos
 891             Text control position.
 892         @param size
 893             Text control size.
 894         @param style
 895             Window style. See wxTextCtrl.
 896         @param validator
 897             Window validator.
 898         @param name
 899             Window name.
 900
 901         @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
 902             created for multi-line text controls. Without a horizontal
 903             scrollbar, text lines that don't fit in the control's size will be
 904             wrapped (but no newline character is inserted). Single line
 905             controls don't have a horizontal scrollbar, the text is
 906             automatically scrolled so that the insertion point is always
 907             visible.
 908
 909         @see Create(), wxValidator
 910     */
 911     wxTextCtrl();
 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     ~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     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     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     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     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     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     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     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     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     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     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     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     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     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         @param from
1439             The first position.
1440         @param to
1441             The last position.
1442
1443         @see SelectAll()
1444     */
1445     virtual void SetSelection(long from, long to);
1446
1447     /**
1448         Selects all text in the control.
1449
1450         @see SetSelection()
1451     */
1452     virtual void SelectAll();
1453
1454     /**
1455         Changes the style of the given range.
1456
1457         If any attribute within @a style is not set, the corresponding
1458         attribute from GetDefaultStyle() is used.
1459
1460         @param start
1461             The start of the range to change.
1462         @param end
1463             The end of the range to change.
1464         @param style
1465             The new style for the range.
1466
1467         @return
1468             @true on success, @false if an error occurred (this may also mean
1469             that the styles are not supported under this platform).
1470
1471         @see GetStyle(), wxTextAttr
1472     */
1473     bool SetStyle(long start, long end, const wxTextAttr& style);
1474
1475     /**
1476         Sets the text value and marks the control as not-modified (which means
1477         that IsModified() would return @false immediately after the call to
1478         SetValue).
1479
1480         Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED
1481         event, to avoid this you can use ChangeValue() instead.
1482
1483         @param value
1484             The new value to set. It may contain newline characters if the text
1485             control is multi-line.
1486     */
1487     virtual void SetValue(const wxString& value);
1488
1489     /**
1490         Makes the line containing the given position visible.
1491
1492         @param pos
1493             The position that should be visible.
1494     */
1495     void ShowPosition(long pos);
1496
1497     /**
1498         If there is an undo facility and the last operation can be undone,
1499         undoes the last operation.
1500
1501         Does nothing if there is no undo facility.
1502     */
1503     virtual void Undo();
1504
1505     /**
1506         Writes the text into the text control at the current insertion position.
1507
1508         @param text
1509             Text to write to the text control.
1510
1511         @remarks Newlines in the text string are the only control characters
1512             allowed, and they will cause appropriate line breaks. See () and
1513             AppendText() for more convenient ways of writing to the window.
1514     */
1515     void WriteText(const wxString& text);
1516
1517     /**
1518         Converts the given zero based column and line number to a position.
1519
1520         @param x
1521             The column number.
1522         @param y
1523             The line number.
1524
1525         @return
1526             The position value, or -1 if x or y was invalid.
1527     */
1528     long XYToPosition(long x, long y);
1529
1530     //@{
1531     /**
1532         Operator definitions for appending to a text control.
1533
1534         These operators can be used as with the standard C++ streams, for
1535         example:
1536         @code
1537             wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1538
1539             (*wnd) << "Welcome to text control number " << 1 << ".\n";
1540         @endcode
1541     */
1542
1543     wxTextCtrl& operator<<(const wxString& s);
1544     wxTextCtrl& operator<<(int i);
1545     wxTextCtrl& operator<<(long i);
1546     wxTextCtrl& operator<<(float f);
1547     wxTextCtrl& operator<<(double d);
1548     wxTextCtrl& operator<<(char c);
1549     wxTextCtrl& operator<<(wchar_t c);
1550     //@}
1551 };
1552
1553
1554
1555 /**
1556     @class wxStreamToTextRedirector
1557     @wxheader{textctrl.h}
1558
1559     This class can be used to (temporarily) redirect all output sent to a C++
1560     ostream object to a wxTextCtrl instead.
1561
1562     @note Some compilers and/or build configurations don't support multiply
1563     inheriting wxTextCtrl from @c std::streambuf in which
1564     case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
1565     option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
1566     specify @c --enable-std_iostreams switch when running configure for this.
1567
1568     Example of usage:
1569
1570     @code
1571     using namespace std;
1572
1573       wxTextCtrl *text = new wxTextCtrl(...);
1574
1575       {
1576         wxStreamToTextRedirector redirect(text);
1577
1578         // this goes to the text control
1579         cout  "Hello, text!"  endl;
1580       }
1581
1582       // this goes somewhere else, presumably to stdout
1583       cout  "Hello, console!"  endl;
1584     @endcode
1585
1586
1587     @library{wxcore}
1588     @category{logging}
1589
1590     @see wxTextCtrl
1591 */
1592 class wxStreamToTextRedirector
1593 {
1594 public:
1595     /**
1596         The constructor starts redirecting output sent to @a ostr or @a cout for
1597         the default parameter value to the text control @a text.
1598
1599         @param text
1600             The text control to append output too, must be non-@NULL
1601         @param ostr
1602             The C++ stream to redirect, cout is used if it is @NULL
1603     */
1604     wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
1605
1606     /**
1607         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1608         and any output sent to the C++ ostream which had been specified at the time of
1609         the object construction will go to its original destination.
1610     */
1611     ~wxStreamToTextRedirector();
1612 };
1613