interface/wx/textctrl.h

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