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