interface/wx/textctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        textctrl.h
   3 // Purpose:     interface of wxTextAttr
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  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         Creates a font from the font attributes.
 225     */
 226     wxFont CreateFont() const;
 227
 228     /**
 229         Copies all defined/valid properties from overlay to current object.
 230     */
 231     void Merge(const wxTextAttr& overlay);
 232
 233     /**
 234         Creates a new @c wxTextAttr which is a merge of @a base and @a overlay.
 235
 236         Properties defined in @a overlay take precedence over those in @a base.
 237         Properties undefined/invalid in both are undefined in the result.
 238     */
 239     static wxTextAttr Merge(const wxTextAttr& base,
 240                             const wxTextAttr& overlay);
 241
 242
 243     /**
 244         @name GetXXX functions
 245      */
 246
 247     //@{
 248
 249     /**
 250         Returns the alignment flags.
 251         See ::wxTextAttrAlignment for a list of available styles.
 252     */
 253     wxTextAttrAlignment GetAlignment() const;
 254
 255     /**
 256         Returns the background colour.
 257     */
 258     const wxColour& GetBackgroundColour() const;
 259
 260     /**
 261         Returns a string containing the name of the font associated with the bullet symbol.
 262         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
 263     */
 264     const wxString& GetBulletFont() const;
 265
 266     /**
 267         Returns the standard bullet name, applicable if the bullet style is
 268         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
 269
 270         Currently the following standard bullet names are supported:
 271          - @c standard/circle
 272          - @c standard/square
 273          - @c standard/diamond
 274          - @c standard/triangle
 275
 276         @note
 277         For wxRichTextCtrl users only: if you wish your rich text controls to support
 278         further bullet graphics, you can derive a class from wxRichTextRenderer or
 279         wxRichTextStdRenderer, override @c DrawStandardBullet and @c EnumerateStandardBulletNames,
 280         and set an instance of the class using wxRichTextBuffer::SetRenderer.
 281     */
 282     const wxString& GetBulletName() const;
 283
 284     /**
 285         Returns the bullet number.
 286     */
 287     int GetBulletNumber() const;
 288
 289     /**
 290         Returns the bullet style.
 291         See ::wxTextAttrBulletStyle for a list of available styles.
 292     */
 293     int GetBulletStyle() const;
 294
 295     /**
 296         Returns the bullet text, which could be a symbol, or (for example) cached
 297         outline text.
 298     */
 299     const wxString& GetBulletText() const;
 300
 301     /**
 302         Returns the name of the character style.
 303     */
 304     const wxString& GetCharacterStyleName() const;
 305
 306     /**
 307         Returns flags indicating which attributes are applicable.
 308         See SetFlags() for a list of available flags.
 309     */
 310     long GetFlags() const;
 311
 312     /**
 313         Creates and returns a font specified by the font attributes in the wxTextAttr
 314         object. Note that wxTextAttr does not store a wxFont object, so this is only
 315         a temporary font.
 316
 317         For greater efficiency, access the font attributes directly.
 318     */
 319     wxFont GetFont() const;
 320
 321     /**
 322         Gets the font attributes from the given font, using only the attributes
 323         specified by @a flags.
 324     */
 325     bool GetFontAttributes(const wxFont& font,
 326                            int flags = wxTEXT_ATTR_FONT);
 327
 328     /**
 329         Returns the font encoding.
 330     */
 331     wxFontEncoding GetFontEncoding() const;
 332
 333     /**
 334         Returns the font face name.
 335     */
 336     const wxString& GetFontFaceName() const;
 337
 338     /**
 339         Returns the font family.
 340     */
 341     wxFontFamily GetFontFamily() const;
 342
 343     /**
 344         Returns the font size in points.
 345     */
 346     int GetFontSize() const;
 347
 348     /**
 349         Returns the font style.
 350     */
 351     wxFontStyle GetFontStyle() const;
 352
 353     /**
 354         Returns @true if the font is underlined.
 355     */
 356     bool GetFontUnderlined() const;
 357
 358     /**
 359         Returns the font weight.
 360     */
 361     wxFontWeight GetFontWeight() const;
 362
 363     /**
 364         Returns the left indent in tenths of a millimetre.
 365     */
 366     long GetLeftIndent() const;
 367
 368     /**
 369         Returns the left sub-indent in tenths of a millimetre.
 370     */
 371     long GetLeftSubIndent() const;
 372
 373     /**
 374         Returns the line spacing value, one of ::wxTextAttrLineSpacing values.
 375     */
 376     int GetLineSpacing() const;
 377
 378     /**
 379         Returns the name of the list style.
 380     */
 381     const wxString& GetListStyleName() const;
 382
 383     /**
 384         Returns the outline level.
 385     */
 386     int GetOutlineLevel() const;
 387
 388     /**
 389         Returns the space in tenths of a millimeter after the paragraph.
 390     */
 391     int GetParagraphSpacingAfter() const;
 392
 393     /**
 394         Returns the space in tenths of a millimeter before the paragraph.
 395     */
 396     int GetParagraphSpacingBefore() const;
 397
 398     /**
 399         Returns the name of the paragraph style.
 400     */
 401     const wxString& GetParagraphStyleName() const;
 402
 403     /**
 404         Returns the right indent in tenths of a millimeter.
 405     */
 406     long GetRightIndent() const;
 407
 408     /**
 409         Returns an array of tab stops, each expressed in tenths of a millimeter.
 410
 411         Each stop is measured from the left margin and therefore each value must
 412         be larger than the last.
 413     */
 414     const wxArrayInt& GetTabs() const;
 415
 416     /**
 417         Returns the text foreground colour.
 418     */
 419     const wxColour& GetTextColour() const;
 420
 421     /**
 422         Returns the text effect bits of interest.
 423         See SetFlags() for further information.
 424     */
 425     int GetTextEffectFlags() const;
 426
 427     /**
 428         Returns the text effects, a bit list of styles.
 429         See SetTextEffects() for details.
 430     */
 431     int GetTextEffects() const;
 432
 433     /**
 434         Returns the URL for the content.
 435
 436         Content with @a wxTEXT_ATTR_URL style causes wxRichTextCtrl to show a
 437         hand cursor over it, and wxRichTextCtrl generates a wxTextUrlEvent
 438         when the content is clicked.
 439     */
 440     const wxString& GetURL() const;
 441
 442     //@}
 443
 444
 445
 446     /**
 447         @name HasXXX and IsXXX functions
 448      */
 449
 450     //@{
 451
 452     /**
 453         Returns @true if the attribute object specifies alignment.
 454     */
 455     bool HasAlignment() const;
 456
 457     /**
 458         Returns @true if the attribute object specifies a background colour.
 459     */
 460     bool HasBackgroundColour() const;
 461
 462     /**
 463         Returns @true if the attribute object specifies a standard bullet name.
 464     */
 465     bool HasBulletName() const;
 466
 467     /**
 468         Returns @true if the attribute object specifies a bullet number.
 469     */
 470     bool HasBulletNumber() const;
 471
 472     /**
 473         Returns @true if the attribute object specifies a bullet style.
 474     */
 475     bool HasBulletStyle() const;
 476
 477     /**
 478         Returns @true if the attribute object specifies bullet text (usually
 479         specifying a symbol).
 480     */
 481     bool HasBulletText() const;
 482
 483     /**
 484         Returns @true if the attribute object specifies a character style name.
 485     */
 486     bool HasCharacterStyleName() const;
 487
 488     /**
 489         Returns @true if the @a flag is present in the attribute object's flag
 490         bitlist.
 491     */
 492     bool HasFlag(long flag) const;
 493
 494     /**
 495         Returns @true if the attribute object specifies any font attributes.
 496     */
 497     bool HasFont() const;
 498
 499     /**
 500         Returns @true if the attribute object specifies an encoding.
 501     */
 502     bool HasFontEncoding() const;
 503
 504     /**
 505         Returns @true if the attribute object specifies a font face name.
 506     */
 507     bool HasFontFaceName() const;
 508
 509     /**
 510         Returns @true if the attribute object specifies a font family.
 511     */
 512     bool HasFontFamily() const;
 513
 514     /**
 515         Returns @true if the attribute object specifies italic style.
 516     */
 517     bool HasFontItalic() const;
 518
 519     /**
 520         Returns @true if the attribute object specifies a font point size.
 521     */
 522     bool HasFontSize() const;
 523
 524     /**
 525         Returns @true if the attribute object specifies either underlining or no
 526         underlining.
 527     */
 528     bool HasFontUnderlined() const;
 529
 530     /**
 531         Returns @true if the attribute object specifies font weight (bold, light or
 532         normal).
 533     */
 534     bool HasFontWeight() const;
 535
 536     /**
 537         Returns @true if the attribute object specifies a left indent.
 538     */
 539     bool HasLeftIndent() const;
 540
 541     /**
 542         Returns @true if the attribute object specifies line spacing.
 543     */
 544     bool HasLineSpacing() const;
 545
 546     /**
 547         Returns @true if the attribute object specifies a list style name.
 548     */
 549     bool HasListStyleName() const;
 550
 551     /**
 552         Returns @true if the attribute object specifies an outline level.
 553     */
 554     bool HasOutlineLevel() const;
 555
 556     /**
 557         Returns @true if the attribute object specifies a page break before this
 558         paragraph.
 559     */
 560     bool HasPageBreak() const;
 561
 562     /**
 563         Returns @true if the attribute object specifies spacing after a paragraph.
 564     */
 565     bool HasParagraphSpacingAfter() const;
 566
 567     /**
 568         Returns @true if the attribute object specifies spacing before a paragraph.
 569     */
 570     bool HasParagraphSpacingBefore() const;
 571
 572     /**
 573         Returns @true if the attribute object specifies a paragraph style name.
 574     */
 575     bool HasParagraphStyleName() const;
 576
 577     /**
 578         Returns @true if the attribute object specifies a right indent.
 579     */
 580     bool HasRightIndent() const;
 581
 582     /**
 583         Returns @true if the attribute object specifies tab stops.
 584     */
 585     bool HasTabs() const;
 586
 587     /**
 588         Returns @true if the attribute object specifies a text foreground colour.
 589     */
 590     bool HasTextColour() const;
 591
 592     /**
 593         Returns @true if the attribute object specifies text effects.
 594     */
 595     bool HasTextEffects() const;
 596
 597     /**
 598         Returns @true if the attribute object specifies a URL.
 599     */
 600     bool HasURL() const;
 601
 602     /**
 603         Returns @true if the object represents a character style, that is,
 604         the flags specify a font or a text background or foreground colour.
 605     */
 606     bool IsCharacterStyle() const;
 607
 608     /**
 609         Returns @false if we have any attributes set, @true otherwise.
 610     */
 611     bool IsDefault() const;
 612
 613     /**
 614         Returns @true if the object represents a paragraph style, that is,
 615         the flags specify alignment, indentation, tabs, paragraph spacing, or
 616         bullet style.
 617     */
 618     bool IsParagraphStyle() const;
 619
 620     //@}
 621
 622
 623     /**
 624         @name SetXXX functions
 625      */
 626
 627     //@{
 628
 629     /**
 630         Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.
 631
 632         Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
 633         In future justification may be supported when printing or previewing, only.
 634     */
 635     void SetAlignment(wxTextAttrAlignment alignment);
 636
 637     /**
 638         Sets the background colour.
 639     */
 640     void SetBackgroundColour(const wxColour& colBack);
 641
 642     /**
 643         Sets the name of the font associated with the bullet symbol.
 644         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
 645     */
 646     void SetBulletFont(const wxString& font);
 647
 648     /**
 649         Sets the standard bullet name, applicable if the bullet style is
 650         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
 651
 652         See GetBulletName() for a list of supported names, and how
 653         to expand the range of supported types.
 654     */
 655     void SetBulletName(const wxString& name);
 656
 657     /**
 658         Sets the bullet number.
 659     */
 660     void SetBulletNumber(int n);
 661
 662     /**
 663         Sets the bullet style.
 664
 665         The ::wxTextAttrBulletStyle enumeration values are all supported,
 666         except for wxTEXT_ATTR_BULLET_STYLE_BITMAP.
 667     */
 668     void SetBulletStyle(int style);
 669
 670     /**
 671         Sets the bullet text, which could be a symbol, or (for example) cached
 672         outline text.
 673     */
 674     void SetBulletText(const wxString& text);
 675
 676     /**
 677         Sets the character style name.
 678     */
 679     void SetCharacterStyleName(const wxString& name);
 680
 681     /**
 682         Sets the flags determining which styles are being specified.
 683         The ::wxTextAttrFlags values can be passed in a bitlist.
 684     */
 685     void SetFlags(long flags);
 686
 687     /**
 688         Sets the attributes for the given font.
 689         Note that wxTextAttr does not store an actual wxFont object.
 690     */
 691     void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT);
 692
 693     /**
 694         Sets the font encoding.
 695     */
 696     void SetFontEncoding(wxFontEncoding encoding);
 697
 698     /**
 699         Sets the font face name.
 700     */
 701     void SetFontFaceName(const wxString& faceName);
 702
 703     /**
 704         Sets the font family.
 705     */
 706     void SetFontFamily(wxFontFamily family);
 707
 708     /**
 709         Sets the font size in points.
 710     */
 711     void SetFontSize(int pointSize);
 712
 713     /**
 714         Sets the font style (normal, italic or slanted).
 715     */
 716     void SetFontStyle(wxFontStyle fontStyle);
 717
 718     /**
 719         Sets the font underlining.
 720     */
 721     void SetFontUnderlined(bool underlined);
 722
 723     /**
 724         Sets the font weight.
 725     */
 726     void SetFontWeight(wxFontWeight fontWeight);
 727
 728     /**
 729         Sets the left indent and left subindent in tenths of a millimetre.
 730         The sub-indent is an offset from the left of the paragraph, and is used for all
 731         but the first line in a paragraph.
 732
 733         A positive value will cause the first line to appear to the left
 734         of the subsequent lines, and a negative value will cause the first line to be
 735         indented relative to the subsequent lines.
 736
 737         wxRichTextBuffer uses indentation to render a bulleted item.
 738         The left indent is the distance between the margin and the bullet.
 739         The content of the paragraph, including the first line, starts
 740         at leftMargin + leftSubIndent.
 741         So the distance between the left edge of the bullet and the
 742         left of the actual paragraph is leftSubIndent.
 743     */
 744     void SetLeftIndent(int indent, int subIndent = 0);
 745
 746     /**
 747         Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
 748         15 means 1.5 spacing, and 20 means double spacing.
 749         The ::wxTextAttrLineSpacing values are defined for convenience.
 750     */
 751     void SetLineSpacing(int spacing);
 752
 753     /**
 754         Sets the list style name.
 755     */
 756     void SetListStyleName(const wxString& name);
 757
 758     /**
 759         Specifies the outline level. Zero represents normal text.
 760         At present, the outline level is not used, but may be used in future for
 761         determining list levels and for applications that need to store document
 762         structure information.
 763     */
 764     void SetOutlineLevel(int level);
 765
 766     /**
 767         Specifies a page break before this paragraph.
 768     */
 769     void SetPageBreak(bool pageBreak = true);
 770
 771     /**
 772         Sets the spacing after a paragraph, in tenths of a millimetre.
 773     */
 774     void SetParagraphSpacingAfter(int spacing);
 775
 776     /**
 777         Sets the spacing before a paragraph, in tenths of a millimetre.
 778     */
 779     void SetParagraphSpacingBefore(int spacing);
 780
 781     /**
 782         Sets the name of the paragraph style.
 783     */
 784     void SetParagraphStyleName(const wxString& name);
 785
 786     /**
 787         Sets the right indent in tenths of a millimetre.
 788     */
 789     void SetRightIndent(int indent);
 790
 791     /**
 792         Sets the tab stops, expressed in tenths of a millimetre.
 793         Each stop is measured from the left margin and therefore each value must be
 794         larger than the last.
 795     */
 796     void SetTabs(const wxArrayInt& tabs);
 797
 798     /**
 799         Sets the text foreground colout.
 800     */
 801     void SetTextColour(const wxColour& colText);
 802
 803     /**
 804         Sets the text effect bits of interest.
 805
 806         You should also pass wxTEXT_ATTR_EFFECTS to SetFlags().
 807         See SetFlags() for further information.
 808     */
 809     void SetTextEffectFlags(int flags);
 810
 811     /**
 812         Sets the text effects, a bit list of styles.
 813         The ::wxTextAttrEffects enumeration values can be used.
 814
 815         Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
 816         are implemented.
 817
 818         wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
 819         of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws
 820         a line through text.
 821
 822         To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
 823         SetTextEffectFlags() with the styles (taken from the above set) that you
 824         are interested in setting.
 825     */
 826     void SetTextEffects(int effects);
 827
 828     /**
 829         Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
 830         style causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
 831         generates a wxTextUrlEvent when the content is clicked.
 832     */
 833     void SetURL(const wxString& url);
 834
 835     //@}
 836
 837
 838     /**
 839         Assignment from a wxTextAttr object.
 840     */
 841     void operator operator=(const wxTextAttr& attr);
 842 };
 843
 844
 845 /**
 846     @class wxTextCtrl
 847
 848     A text control allows text to be displayed and edited.
 849
 850     It may be single line or multi-line.
 851
 852     @beginStyleTable
 853     @style{wxTE_PROCESS_ENTER}
 854            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
 855            (otherwise pressing Enter key is either processed internally by the
 856            control or used for navigation between dialog controls).
 857     @style{wxTE_PROCESS_TAB}
 858            The control will receive wxEVT_CHAR events for TAB pressed -
 859            normally, TAB is used for passing to the next control in a dialog
 860            instead. For the control created with this style, you can still use
 861            Ctrl-Enter to pass to the next control from the keyboard.
 862     @style{wxTE_MULTILINE}
 863            The text control allows multiple lines.
 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     @beginEventTable{wxCommandEvent}
1046     @event{EVT_TEXT(id, func)}
1047         Respond to a 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 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 {
1073 public:
1074     /**
1075         Default ctor.
1076     */
1077     wxTextCtrl();
1078
1079     /**
1080         Constructor, creating and showing a text control.
1081
1082         @param parent
1083             Parent window. Should not be @NULL.
1084         @param id
1085             Control identifier. A value of -1 denotes a default value.
1086         @param value
1087             Default text value.
1088         @param pos
1089             Text control position.
1090         @param size
1091             Text control size.
1092         @param style
1093             Window style. See wxTextCtrl.
1094         @param validator
1095             Window validator.
1096         @param name
1097             Window name.
1098
1099         @remarks
1100             The horizontal scrollbar (wxHSCROLL style flag) will only be
1101             created for multi-line text controls. Without a horizontal
1102             scrollbar, text lines that don't fit in the control's size will be
1103             wrapped (but no newline character is inserted).
1104             Single line controls don't have a horizontal scrollbar, the text is
1105             automatically scrolled so that the insertion point is always visible.
1106
1107         @see Create(), wxValidator
1108     */
1109     wxTextCtrl(wxWindow* parent, wxWindowID id,
1110                const wxString& value = wxEmptyString,
1111                const wxPoint& pos = wxDefaultPosition,
1112                const wxSize& size = wxDefaultSize,
1113                long style = 0,
1114                const wxValidator& validator = wxDefaultValidator,
1115                const wxString& name = wxTextCtrlNameStr);
1116
1117     /**
1118         Destructor, destroying the text control.
1119     */
1120     virtual ~wxTextCtrl();
1121
1122     /**
1123         Appends the text to the end of the text control.
1124
1125         @param text
1126             Text to write to the text control.
1127
1128         @remarks
1129             After the text is appended, the insertion point will be at the
1130             end of the text control. If this behaviour is not desired, the
1131             programmer should use GetInsertionPoint() and SetInsertionPoint().
1132
1133         @see WriteText()
1134     */
1135     virtual void AppendText(const wxString& text);
1136
1137     /**
1138         Call this function to enable auto-completion of the text typed in a
1139         single-line text control using the given @a choices.
1140
1141         Notice that currently this function is only implemented in wxGTK2 and
1142         wxMSW ports and does nothing under the other platforms.
1143
1144         @since 2.9.0
1145
1146         @return
1147             @true if the auto-completion was enabled or @false if the operation
1148             failed, typically because auto-completion is not supported by the
1149             current platform.
1150
1151         @see AutoCompleteFileNames()
1152     */
1153     virtual bool AutoComplete(const wxArrayString& choices);
1154
1155     /**
1156         Call this function to enable auto-completion of the text typed in a
1157         single-line text control using all valid file system paths.
1158
1159         Notice that currently this function is only implemented in wxGTK2 port
1160         and does nothing under the other platforms.
1161
1162         @since 2.9.0
1163
1164         @return
1165             @true if the auto-completion was enabled or @false if the operation
1166             failed, typically because auto-completion is not supported by the
1167             current platform.
1168
1169         @see AutoComplete()
1170     */
1171     virtual bool AutoCompleteFileNames();
1172
1173     /**
1174         Returns @true if the selection can be copied to the clipboard.
1175     */
1176     virtual bool CanCopy() const;
1177
1178     /**
1179         Returns @true if the selection can be cut to the clipboard.
1180     */
1181     virtual bool CanCut() const;
1182
1183     /**
1184         Returns @true if the contents of the clipboard can be pasted into the
1185         text control.
1186
1187         On some platforms (Motif, GTK) this is an approximation and returns
1188         @true if the control is editable, @false otherwise.
1189     */
1190     virtual bool CanPaste() const;
1191
1192     /**
1193         Returns @true if there is a redo facility available and the last
1194         operation can be redone.
1195     */
1196     virtual bool CanRedo() const;
1197
1198     /**
1199         Returns @true if there is an undo facility available and the last
1200         operation can be undone.
1201     */
1202     virtual bool CanUndo() const;
1203
1204     /**
1205         Sets the new text control value.
1206
1207         It also marks the control as not-modified which means that IsModified()
1208         would return @false immediately after the call to SetValue().
1209
1210         The insertion point is set to the start of the control (i.e. position
1211         0) by this function.
1212
1213         This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
1214         event but otherwise is identical to SetValue().
1215
1216         See @ref overview_eventhandling_prog for more information.
1217
1218         @since 2.7.1
1219
1220         @param value
1221             The new value to set. It may contain newline characters if the text
1222             control is multi-line.
1223     */
1224     virtual void ChangeValue(const wxString& value);
1225
1226     /**
1227         Clears the text in the control.
1228
1229         Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
1230         event, i.e. its effect is identical to calling @c SetValue("").
1231     */
1232     virtual void Clear();
1233
1234     /**
1235         Copies the selected text to the clipboard.
1236     */
1237     virtual void Copy();
1238
1239     /**
1240         Creates the text control for two-step construction.
1241
1242         This method should be called if the default constructor was used for
1243         the control creation. Its parameters have the same meaning as for the
1244         non-default constructor.
1245     */
1246     bool Create(wxWindow* parent, wxWindowID id,
1247                 const wxString& value = wxEmptyString,
1248                 const wxPoint& pos = wxDefaultPosition,
1249                 const wxSize& size = wxDefaultSize, long style = 0,
1250                 const wxValidator& validator = wxDefaultValidator,
1251                 const wxString& name = wxTextCtrlNameStr);
1252
1253     /**
1254         Copies the selected text to the clipboard and removes the selection.
1255     */
1256     virtual void Cut();
1257
1258     /**
1259         Resets the internal modified flag as if the current changes had been
1260         saved.
1261     */
1262     virtual void DiscardEdits();
1263
1264     /**
1265         This functions inserts into the control the character which would have
1266         been inserted if the given key event had occurred in the text control.
1267
1268         The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
1269         handler previously by wxWidgets. Please note that this function doesn't
1270         currently work correctly for all keys under any platform but MSW.
1271
1272         @return
1273             @true if the event resulted in a change to the control, @false otherwise.
1274     */
1275     virtual bool EmulateKeyPress(const wxKeyEvent& event);
1276
1277     /**
1278         Returns the style currently used for the new text.
1279
1280         @see SetDefaultStyle()
1281     */
1282     virtual const wxTextAttr& GetDefaultStyle() const;
1283
1284     /**
1285         Returns the insertion point, or cursor, position.
1286
1287         This is defined as the zero based index of the character position to
1288         the right of the insertion point. For example, if the insertion point
1289         is at the end of the single-line text control, it is equal to both
1290         GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
1291         equality is not necessarily true for multiline edit controls which may
1292         use multiple new line characters).
1293
1294         The following code snippet safely returns the character at the insertion
1295         point or the zero character if the point is at the end of the control.
1296
1297         @code
1298         char GetCurrentChar(wxTextCtrl *tc) {
1299             if (tc->GetInsertionPoint() == tc->GetLastPosition())
1300             return '\0';
1301             return tc->GetValue[tc->GetInsertionPoint()];
1302         }
1303         @endcode
1304     */
1305     virtual long GetInsertionPoint() const;
1306
1307     /**
1308         Returns the zero based index of the last position in the text control,
1309         which is equal to the number of characters in the control.
1310     */
1311     virtual wxTextPos GetLastPosition() const;
1312
1313     /**
1314         Gets the length of the specified line, not including any trailing
1315         newline character(s).
1316
1317         @param lineNo
1318             Line number (starting from zero).
1319
1320         @return
1321             The length of the line, or -1 if @a lineNo was invalid.
1322     */
1323     virtual int GetLineLength(long lineNo) const;
1324
1325     /**
1326         Returns the contents of a given line in the text control, not including
1327         any trailing newline character(s).
1328
1329         @param lineNo
1330             The line number, starting from zero.
1331
1332         @return
1333             The contents of the line.
1334     */
1335     virtual wxString GetLineText(long lineNo) const;
1336
1337     /**
1338         Returns the number of lines in the text control buffer.
1339
1340         @remarks
1341             Note that even empty text controls have one line (where the
1342             insertion point is), so GetNumberOfLines() never returns 0.
1343             For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a
1344             multi-line text control is calculated by actually counting newline
1345             characters in the buffer, i.e. this function returns the number of
1346             logical lines and doesn't depend on whether any of them are wrapped.
1347             For all the other platforms, the number of physical lines in the
1348             control is returned.
1349             Also note that you may wish to avoid using functions that work with
1350             line numbers if you are working with controls that contain large
1351             amounts of text as this function has O(N) complexity for N being
1352             the number of lines.
1353     */
1354     virtual int GetNumberOfLines() const;
1355
1356     /**
1357         Returns the string containing the text starting in the positions
1358         @a from and up to @a to in the control.
1359
1360         The positions must have been returned by another wxTextCtrl method.
1361         Please note that the positions in a multiline wxTextCtrl do @b not
1362         correspond to the indices in the string returned by GetValue() because
1363         of the different new line representations (@c CR or @c CR LF) and so
1364         this method should be used to obtain the correct results instead of
1365         extracting parts of the entire value. It may also be more efficient,
1366         especially if the control contains a lot of data.
1367     */
1368     virtual wxString GetRange(long from, long to) const;
1369
1370     /**
1371         Gets the current selection span.
1372
1373         If the returned values are equal, there was no selection. Please note
1374         that the indices returned may be used with the other wxTextCtrl methods
1375         but don't necessarily represent the correct indices into the string
1376         returned by GetValue() for multiline controls under Windows (at least,)
1377         you should use GetStringSelection() to get the selected text.
1378
1379         @param from
1380             The returned first position.
1381         @param to
1382             The returned last position.
1383     */
1384     virtual void GetSelection(long* from, long* to) const;
1385
1386     /**
1387         Gets the text currently selected in the control.
1388
1389         If there is no selection, the returned string is empty.
1390     */
1391     virtual wxString GetStringSelection() const;
1392
1393     /**
1394         Returns the style at this position in the text control.
1395
1396         Not all platforms support this function.
1397
1398         @return
1399             @true on success, @false if an error occurred (this may also mean
1400             that the styles are not supported under this platform).
1401
1402         @see SetStyle(), wxTextAttr
1403     */
1404     virtual bool GetStyle(long position, wxTextAttr& style);
1405
1406     /**
1407         Gets the contents of the control.
1408
1409         Notice that for a multiline text control, the lines will be separated
1410         by (Unix-style) @c \\n characters, even under Windows where they are
1411         separated by a @c \\r\\n sequence in the native control.
1412     */
1413     virtual wxString GetValue() const;
1414
1415     /**
1416         This function finds the character at the specified position expressed
1417         in pixels.
1418
1419         If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
1420         character closest to this position are returned in the @a col and @a
1421         row parameters (unless the pointers are @NULL which is allowed).
1422         Please note that this function is currently only implemented in wxUniv, wxMSW
1423         and wxGTK2 ports.
1424
1425         @see PositionToXY(), XYToPosition()
1426     */
1427     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1428                                     wxTextCoord col,
1429                                     wxTextCoord row) const;
1430
1431     /**
1432         Returns @true if the controls contents may be edited by user (note that
1433         it always can be changed by the program).
1434
1435         In other words, this functions returns @true if the control hasn't been
1436         put in read-only mode by a previous call to SetEditable().
1437     */
1438     virtual bool IsEditable() const;
1439
1440     /**
1441         Returns @true if the control is currently empty.
1442
1443         This is the same as @c GetValue().empty() but can be much more
1444         efficient for the multiline controls containing big amounts of text.
1445
1446         @since 2.7.1
1447     */
1448     virtual bool IsEmpty() const;
1449
1450     /**
1451         Returns @true if the text has been modified by user.
1452
1453         Note that calling SetValue() doesn't make the control modified.
1454
1455         @see MarkDirty()
1456     */
1457     virtual bool IsModified() const;
1458
1459     /**
1460         Returns @true if this is a multi line edit control and @false otherwise.
1461
1462         @see IsSingleLine()
1463     */
1464     bool IsMultiLine() const;
1465
1466     /**
1467         Returns @true if this is a single line edit control and @false otherwise.
1468
1469         @see IsSingleLine(), IsMultiLine()
1470     */
1471     bool IsSingleLine() const;
1472
1473     /**
1474         Loads and displays the named file, if it exists.
1475
1476         @param filename
1477             The filename of the file to load.
1478         @param fileType
1479             The type of file to load. This is currently ignored in wxTextCtrl.
1480
1481         @return
1482             @true if successful, @false otherwise.
1483     */
1484     bool LoadFile(const wxString& filename,
1485                   int fileType = wxTEXT_TYPE_ANY);
1486
1487     /**
1488         Mark text as modified (dirty).
1489
1490         @see IsModified()
1491     */
1492     virtual void MarkDirty();
1493
1494     /**
1495         This event handler function implements default drag and drop behaviour,
1496         which is to load the first dropped file into the control.
1497
1498         @param event
1499             The drop files event.
1500
1501         @remarks This is not implemented on non-Windows platforms.
1502
1503         @see wxDropFilesEvent
1504     */
1505     void OnDropFiles(wxDropFilesEvent& event);
1506
1507     /**
1508         Pastes text from the clipboard to the text item.
1509     */
1510     virtual void Paste();
1511
1512     /**
1513         Converts given position to a zero-based column, line number pair.
1514
1515         @param pos
1516             Position.
1517         @param x
1518             Receives zero based column number.
1519         @param y
1520             Receives zero based line number.
1521
1522         @return
1523             @true on success, @false on failure (most likely due to a too large
1524             position parameter).
1525
1526         @see XYToPosition()
1527     */
1528     virtual bool PositionToXY(long pos, long* x, long* y) const;
1529
1530     /**
1531         If there is a redo facility and the last operation can be redone,
1532         redoes the last operation.
1533
1534         Does nothing if there is no redo facility.
1535     */
1536     virtual void Redo();
1537
1538     /**
1539         Removes the text starting at the first given position up to
1540         (but not including) the character at the last position.
1541
1542         This function puts the current insertion point position at @a to as a
1543         side effect.
1544
1545         @param from
1546             The first position.
1547         @param to
1548             The last position.
1549     */
1550     virtual void Remove(long from, long to);
1551
1552     /**
1553         Replaces the text starting at the first position up to
1554         (but not including) the character at the last position with the given text.
1555
1556         This function puts the current insertion point position at @a to as a
1557         side effect.
1558
1559         @param from
1560             The first position.
1561         @param to
1562             The last position.
1563         @param value
1564             The value to replace the existing text with.
1565     */
1566     virtual void Replace(long from, long to, const wxString& value);
1567
1568     /**
1569         Saves the contents of the control in a text file.
1570
1571         @param filename
1572             The name of the file in which to save the text.
1573         @param fileType
1574             The type of file to save. This is currently ignored in wxTextCtrl.
1575
1576         @return
1577             @true if the operation was successful, @false otherwise.
1578     */
1579     bool SaveFile(const wxString& filename = wxEmptyString,
1580                   int fileType = wxTEXT_TYPE_ANY);
1581
1582     /**
1583         Changes the default style to use for the new text which is going to be
1584         added to the control using WriteText() or AppendText().
1585
1586         If either of the font, foreground, or background colour is not set in
1587         @a style, the values of the previous default style are used for them.
1588         If the previous default style didn't set them neither, the global font
1589         or colours of the text control itself are used as fall back.
1590
1591         However if the @a style parameter is the default wxTextAttr, then the default
1592         style is just reset (instead of being combined with the new style which
1593         wouldn't change it at all).
1594
1595         @param style
1596             The style for the new text.
1597
1598         @return
1599             @true on success, @false if an error occurred (this may also mean
1600             that the styles are not supported under this platform).
1601
1602         @see GetDefaultStyle()
1603     */
1604     virtual bool SetDefaultStyle(const wxTextAttr& style);
1605
1606     /**
1607         Makes the text item editable or read-only, overriding the
1608         @b wxTE_READONLY flag.
1609
1610         @param editable
1611             If @true, the control is editable. If @false, the control is
1612             read-only.
1613
1614         @see IsEditable()
1615     */
1616     virtual void SetEditable(bool editable);
1617
1618     /**
1619         Sets the insertion point at the given position.
1620
1621         @param pos
1622             Position to set, in the range from 0 to GetLastPosition() inclusive.
1623     */
1624     virtual void SetInsertionPoint(long pos);
1625
1626     /**
1627         Sets the insertion point at the end of the text control.
1628
1629         This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
1630         wxTextCtrl::GetLastPosition() argument.
1631     */
1632     virtual void SetInsertionPointEnd();
1633
1634     /**
1635         This function sets the maximum number of characters the user can enter
1636         into the control.
1637
1638         In other words, it allows to limit the text value length to @a len not
1639         counting the terminating @c NUL character.
1640
1641         If @a len is 0, the previously set max length limit, if any, is discarded
1642         and the user may enter as much text as the underlying native text control widget
1643         supports (typically at least 32Kb).
1644         If the user tries to enter more characters into the text control when it
1645         already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
1646         event is sent to notify the program about it (giving it the possibility
1647         to show an explanatory message, for example) and the extra input is discarded.
1648
1649         Note that in wxGTK this function may only be used with single line text controls.
1650     */
1651     virtual void SetMaxLength(unsigned long len);
1652
1653     /**
1654         Marks the control as being modified by the user or not.
1655
1656         @see MarkDirty(), DiscardEdits()
1657     */
1658     void SetModified(bool modified);
1659
1660     /**
1661         Selects the text starting at the first position up to (but not
1662         including) the character at the last position.
1663
1664         If both parameters are equal to -1 all text in the control is selected.
1665
1666         Notice that the insertion point will be moved to @a from by this
1667         function.
1668
1669         @param from
1670             The first position.
1671         @param to
1672             The last position.
1673
1674         @see SelectAll()
1675     */
1676     virtual void SetSelection(long from, long to);
1677
1678     /**
1679         Selects all text in the control.
1680
1681         @see SetSelection()
1682     */
1683     virtual void SelectAll();
1684
1685     /**
1686         Changes the style of the given range.
1687
1688         If any attribute within @a style is not set, the corresponding
1689         attribute from GetDefaultStyle() is used.
1690
1691         @param start
1692             The start of the range to change.
1693         @param end
1694             The end of the range to change.
1695         @param style
1696             The new style for the range.
1697
1698         @return
1699             @true on success, @false if an error occurred (this may also mean
1700             that the styles are not supported under this platform).
1701
1702         @see GetStyle(), wxTextAttr
1703     */
1704     virtual bool SetStyle(long start, long end, const wxTextAttr& style);
1705
1706     /**
1707         Sets the new text control value.
1708
1709         It also marks the control as not-modified which means that IsModified()
1710         would return @false immediately after the call to SetValue().
1711
1712         The insertion point is set to the start of the control (i.e. position
1713         0) by this function.
1714
1715         Note that, unlike most other functions changing the controls values,
1716         this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
1717         this you can use ChangeValue() instead.
1718
1719         @param value
1720             The new value to set. It may contain newline characters if the text
1721             control is multi-line.
1722     */
1723     virtual void SetValue(const wxString& value);
1724
1725     /**
1726         Makes the line containing the given position visible.
1727
1728         @param pos
1729             The position that should be visible.
1730     */
1731     virtual void ShowPosition(long pos);
1732
1733     /**
1734         If there is an undo facility and the last operation can be undone,
1735         undoes the last operation.
1736
1737         Does nothing if there is no undo facility.
1738     */
1739     virtual void Undo();
1740
1741     /**
1742         Writes the text into the text control at the current insertion position.
1743
1744         @param text
1745             Text to write to the text control.
1746
1747         @remarks
1748             Newlines in the text string are the only control characters
1749             allowed, and they will cause appropriate line breaks.
1750             See operator<<() and AppendText() for more convenient ways of
1751             writing to the window.
1752             After the write operation, the insertion point will be at the end
1753             of the inserted text, so subsequent write operations will be appended.
1754             To append text after the user may have interacted with the control,
1755             call wxTextCtrl::SetInsertionPointEnd() before writing.
1756     */
1757     virtual void WriteText(const wxString& text);
1758
1759     /**
1760         Converts the given zero based column and line number to a position.
1761
1762         @param x
1763             The column number.
1764         @param y
1765             The line number.
1766
1767         @return
1768             The position value, or -1 if x or y was invalid.
1769     */
1770     virtual long XYToPosition(long x, long y) const;
1771
1772     //@{
1773     /**
1774         Operator definitions for appending to a text control.
1775
1776         These operators can be used as with the standard C++ streams, for
1777         example:
1778         @code
1779             wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1780
1781             (*wnd) << "Welcome to text control number " << 1 << ".\n";
1782         @endcode
1783     */
1784
1785     wxTextCtrl& operator<<(const wxString& s);
1786     wxTextCtrl& operator<<(int i);
1787     wxTextCtrl& operator<<(long i);
1788     wxTextCtrl& operator<<(float f);
1789     wxTextCtrl& operator<<(double d);
1790     wxTextCtrl& operator<<(char c);
1791     wxTextCtrl& operator<<(wchar_t c);
1792     //@}
1793 };
1794
1795
1796
1797 /**
1798     @class wxStreamToTextRedirector
1799
1800     This class can be used to (temporarily) redirect all output sent to a C++
1801     ostream object to a wxTextCtrl instead.
1802
1803     @note
1804         Some compilers and/or build configurations don't support multiply
1805         inheriting wxTextCtrl from @c std::streambuf in which case this class is
1806         not compiled in.
1807         You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your
1808         @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams
1809         switch when running configure for this.
1810
1811     Example of usage:
1812
1813     @code
1814     using namespace std;
1815     wxTextCtrl* text = new wxTextCtrl(...);
1816     {
1817         wxStreamToTextRedirector redirect(text);
1818
1819         // this goes to the text control
1820         cout << "Hello, text!" << endl;
1821     }
1822     // this goes somewhere else, presumably to stdout
1823     cout << "Hello, console!" << endl;
1824     @endcode
1825
1826     @library{wxcore}
1827     @category{logging}
1828
1829     @see wxTextCtrl
1830 */
1831 class wxStreamToTextRedirector
1832 {
1833 public:
1834     /**
1835         The constructor starts redirecting output sent to @a ostr or @a cout for
1836         the default parameter value to the text control @a text.
1837
1838         @param text
1839             The text control to append output too, must be non-@NULL
1840         @param ostr
1841             The C++ stream to redirect, cout is used if it is @NULL
1842     */
1843     wxStreamToTextRedirector(wxTextCtrl *text, ostream* ostr);
1844
1845     /**
1846         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1847         and any output sent to the C++ ostream which had been specified at the time of
1848         the object construction will go to its original destination.
1849     */
1850     ~wxStreamToTextRedirector();
1851 };
1852