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     virtual 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     virtual 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     virtual bool AutoCompleteFileNames();
1109
1110     /**
1111         Returns @true if the selection can be copied to the clipboard.
1112     */
1113     virtual bool CanCopy() const;
1114
1115     /**
1116         Returns @true if the selection can be cut to the clipboard.
1117     */
1118     virtual bool CanCut() const;
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() const;
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() const;
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() const;
1140
1141     /**
1142         Sets the new text control value.
1143
1144         It also marks the control as not-modified which means that IsModified()
1145         would return @false immediately after the call to SetValue().
1146
1147         The insertion point is set to the start of the control (i.e. position
1148         0) by this function.
1149
1150         This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
1151         event but otherwise is identical to SetValue().
1152
1153         See @ref overview_eventhandling_prog for more information.
1154
1155         @since 2.7.1
1156
1157         @param value
1158             The new value to set. It may contain newline characters if the text
1159             control is multi-line.
1160     */
1161     virtual void ChangeValue(const wxString& value);
1162
1163     /**
1164         Clears the text in the control.
1165
1166         Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
1167         event, i.e. its effect is identical to calling @c SetValue("").
1168     */
1169     virtual void Clear();
1170
1171     /**
1172         Copies the selected text to the clipboard.
1173     */
1174     virtual void Copy();
1175
1176     /**
1177         Creates the text control for two-step construction.
1178
1179         This method should be called if the default constructor was used for
1180         the control creation. Its parameters have the same meaning as for the
1181         non-default constructor.
1182     */
1183     bool Create(wxWindow* parent, wxWindowID id,
1184                 const wxString& value = "",
1185                 const wxPoint& pos = wxDefaultPosition,
1186                 const wxSize& size = wxDefaultSize,
1187                 long style = 0,
1188                 const wxValidator& validator = wxDefaultValidator,
1189                 const wxString& name = wxTextCtrlNameStr);
1190
1191     /**
1192         Copies the selected text to the clipboard and removes the selection.
1193     */
1194     virtual void Cut();
1195
1196     /**
1197         Resets the internal modified flag as if the current changes had been
1198         saved.
1199     */
1200     virtual void DiscardEdits();
1201
1202     /**
1203         This functions inserts into the control the character which would have
1204         been inserted if the given key event had occurred in the text control.
1205
1206         The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
1207         handler previously by wxWidgets. Please note that this function doesn't
1208         currently work correctly for all keys under any platform but MSW.
1209
1210         @return
1211             @true if the event resulted in a change to the control, @false otherwise.
1212     */
1213     virtual bool EmulateKeyPress(const wxKeyEvent& event);
1214
1215     /**
1216         Returns the style currently used for the new text.
1217
1218         @see SetDefaultStyle()
1219     */
1220     const wxTextAttr GetDefaultStyle() const;
1221
1222     /**
1223         Returns the insertion point, or cursor, position.
1224
1225         This is defined as the zero based index of the character position to
1226         the right of the insertion point. For example, if the insertion point
1227         is at the end of the single-line text control, it is equal to both
1228         GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
1229         equality is not necessarily true for multiline edit controls which may
1230         use multiple new line characters).
1231
1232         The following code snippet safely returns the character at the insertion
1233         point or the zero character if the point is at the end of the control.
1234
1235         @code
1236         char GetCurrentChar(wxTextCtrl *tc) {
1237             if (tc->GetInsertionPoint() == tc->GetLastPosition())
1238             return '\0';
1239             return tc->GetValue[tc->GetInsertionPoint()];
1240         }
1241         @endcode
1242     */
1243     virtual long GetInsertionPoint() const;
1244
1245     /**
1246         Returns the zero based index of the last position in the text control,
1247         which is equal to the number of characters in the control.
1248     */
1249     virtual wxTextPos GetLastPosition() const;
1250
1251     /**
1252         Gets the length of the specified line, not including any trailing
1253         newline character(s).
1254
1255         @param lineNo
1256             Line number (starting from zero).
1257
1258         @return
1259             The length of the line, or -1 if @a lineNo was invalid.
1260     */
1261     virtual int GetLineLength(long lineNo) const;
1262
1263     /**
1264         Returns the contents of a given line in the text control, not including
1265         any trailing newline character(s).
1266
1267         @param lineNo
1268             The line number, starting from zero.
1269
1270         @return
1271             The contents of the line.
1272     */
1273     virtual wxString GetLineText(long lineNo) const;
1274
1275     /**
1276         Returns the number of lines in the text control buffer.
1277
1278         @remarks
1279             Note that even empty text controls have one line (where the
1280             insertion point is), so GetNumberOfLines() never returns 0.
1281             For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a
1282             multi-line text control is calculated by actually counting newline
1283             characters in the buffer, i.e. this function returns the number of
1284             logical lines and doesn't depend on whether any of them are wrapped.
1285             For all the other platforms, the number of physical lines in the
1286             control is returned.
1287             Also note that you may wish to avoid using functions that work with
1288             line numbers if you are working with controls that contain large
1289             amounts of text as this function has O(N) complexity for N being
1290             the number of lines.
1291     */
1292     virtual int GetNumberOfLines() const;
1293
1294     /**
1295         Returns the string containing the text starting in the positions
1296         @a from and up to @a to in the control.
1297
1298         The positions must have been returned by another wxTextCtrl method.
1299         Please note that the positions in a multiline wxTextCtrl do @b not
1300         correspond to the indices in the string returned by GetValue() because
1301         of the different new line representations (@c CR or @c CR LF) and so
1302         this method should be used to obtain the correct results instead of
1303         extracting parts of the entire value. It may also be more efficient,
1304         especially if the control contains a lot of data.
1305     */
1306     virtual wxString GetRange(long from, long to) const;
1307
1308     /**
1309         Gets the current selection span.
1310
1311         If the returned values are equal, there was no selection. Please note
1312         that the indices returned may be used with the other wxTextCtrl methods
1313         but don't necessarily represent the correct indices into the string
1314         returned by GetValue() for multiline controls under Windows (at least,)
1315         you should use GetStringSelection() to get the selected text.
1316
1317         @param from
1318             The returned first position.
1319         @param to
1320             The returned last position.
1321     */
1322     virtual void GetSelection(long* from, long* to) const;
1323
1324     /**
1325         Gets the text currently selected in the control.
1326
1327         If there is no selection, the returned string is empty.
1328     */
1329     virtual wxString GetStringSelection() const;
1330
1331     /**
1332         Returns the style at this position in the text control.
1333
1334         Not all platforms support this function.
1335
1336         @return
1337             @true on success, @false if an error occurred (this may also mean
1338             that the styles are not supported under this platform).
1339
1340         @see SetStyle(), wxTextAttr
1341     */
1342     virtual bool GetStyle(long position, wxTextAttr& style);
1343
1344     /**
1345         Gets the contents of the control.
1346
1347         Notice that for a multiline text control, the lines will be separated
1348         by (Unix-style) @c \\n characters, even under Windows where they are
1349         separated by a @c \\r\\n sequence in the native control.
1350     */
1351     virtual wxString GetValue() const;
1352
1353     /**
1354         This function finds the character at the specified position expressed
1355         in pixels.
1356
1357         If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
1358         character closest to this position are returned in the @a col and @a
1359         row parameters (unless the pointers are @NULL which is allowed).
1360         Please note that this function is currently only implemented in wxUniv, wxMSW
1361         and wxGTK2 ports.
1362
1363         @see PositionToXY(), XYToPosition()
1364     */
1365     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1366                                     wxTextCoord col,
1367                                     wxTextCoord row) const;
1368
1369     /**
1370         Returns @true if the controls contents may be edited by user (note that
1371         it always can be changed by the program).
1372
1373         In other words, this functions returns @true if the control hasn't been
1374         put in read-only mode by a previous call to SetEditable().
1375     */
1376     virtual bool IsEditable() const;
1377
1378     /**
1379         Returns @true if the control is currently empty.
1380
1381         This is the same as @c GetValue().empty() but can be much more
1382         efficient for the multiline controls containing big amounts of text.
1383
1384         @since 2.7.1
1385     */
1386     virtual bool IsEmpty() const;
1387
1388     /**
1389         Returns @true if the text has been modified by user.
1390
1391         Note that calling SetValue() doesn't make the control modified.
1392
1393         @see MarkDirty()
1394     */
1395     virtual bool IsModified() const;
1396
1397     /**
1398         Returns @true if this is a multi line edit control and @false otherwise.
1399
1400         @see IsSingleLine()
1401     */
1402     bool IsMultiLine() const;
1403
1404     /**
1405         Returns @true if this is a single line edit control and @false otherwise.
1406
1407         @see IsSingleLine(), IsMultiLine()
1408     */
1409     bool IsSingleLine() const;
1410
1411     /**
1412         Loads and displays the named file, if it exists.
1413
1414         @param filename
1415             The filename of the file to load.
1416         @param fileType
1417             The type of file to load. This is currently ignored in wxTextCtrl.
1418
1419         @return
1420             @true if successful, @false otherwise.
1421     */
1422     bool LoadFile(const wxString& filename,
1423                   int fileType = wxTEXT_TYPE_ANY);
1424
1425     /**
1426         Mark text as modified (dirty).
1427
1428         @see IsModified()
1429     */
1430     virtual void MarkDirty();
1431
1432     /**
1433         This event handler function implements default drag and drop behaviour,
1434         which is to load the first dropped file into the control.
1435
1436         @param event
1437             The drop files event.
1438
1439         @remarks This is not implemented on non-Windows platforms.
1440
1441         @see wxDropFilesEvent
1442     */
1443     void OnDropFiles(wxDropFilesEvent& event);
1444
1445     /**
1446         Pastes text from the clipboard to the text item.
1447     */
1448     virtual void Paste();
1449
1450     /**
1451         Converts given position to a zero-based column, line number pair.
1452
1453         @param pos
1454             Position.
1455         @param x
1456             Receives zero based column number.
1457         @param y
1458             Receives zero based line number.
1459
1460         @return
1461             @true on success, @false on failure (most likely due to a too large
1462             position parameter).
1463
1464         @see XYToPosition()
1465     */
1466     virtual bool PositionToXY(long pos, long* x, long* y) const;
1467
1468     /**
1469         If there is a redo facility and the last operation can be redone,
1470         redoes the last operation.
1471
1472         Does nothing if there is no redo facility.
1473     */
1474     virtual void Redo();
1475
1476     /**
1477         Removes the text starting at the first given position up to
1478         (but not including) the character at the last position.
1479
1480         @param from
1481             The first position.
1482         @param to
1483             The last position.
1484     */
1485     virtual void Remove(long from, long to);
1486
1487     /**
1488         Replaces the text starting at the first position up to
1489         (but not including) the character at the last position with the given text.
1490
1491         @param from
1492             The first position.
1493         @param to
1494             The last position.
1495         @param value
1496             The value to replace the existing text with.
1497     */
1498     virtual void Replace(long from, long to, const wxString& value);
1499
1500     /**
1501         Saves the contents of the control in a text file.
1502
1503         @param filename
1504             The name of the file in which to save the text.
1505         @param fileType
1506             The type of file to save. This is currently ignored in wxTextCtrl.
1507
1508         @return
1509             @true if the operation was successful, @false otherwise.
1510     */
1511     bool SaveFile(const wxString& filename,
1512                   int fileType = wxTEXT_TYPE_ANY);
1513
1514     /**
1515         Changes the default style to use for the new text which is going to be
1516         added to the control using WriteText() or AppendText().
1517
1518         If either of the font, foreground, or background colour is not set in
1519         @a style, the values of the previous default style are used for them.
1520         If the previous default style didn't set them neither, the global font
1521         or colours of the text control itself are used as fall back.
1522
1523         However if the @a style parameter is the default wxTextAttr, then the default
1524         style is just reset (instead of being combined with the new style which
1525         wouldn't change it at all).
1526
1527         @param style
1528             The style for the new text.
1529
1530         @return
1531             @true on success, @false if an error occurred (this may also mean
1532             that the styles are not supported under this platform).
1533
1534         @see GetDefaultStyle()
1535     */
1536     virtual bool SetDefaultStyle(const wxTextAttr& style);
1537
1538     /**
1539         Makes the text item editable or read-only, overriding the
1540         @b wxTE_READONLY flag.
1541
1542         @param editable
1543             If @true, the control is editable. If @false, the control is
1544             read-only.
1545
1546         @see IsEditable()
1547     */
1548     virtual void SetEditable(const bool editable);
1549
1550     /**
1551         Sets the insertion point at the given position.
1552
1553         @param pos
1554             Position to set, in the range from 0 to GetLastPosition() inclusive.
1555     */
1556     virtual void SetInsertionPoint(long pos);
1557
1558     /**
1559         Sets the insertion point at the end of the text control.
1560
1561         This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
1562         wxTextCtrl::GetLastPosition() argument.
1563     */
1564     virtual void SetInsertionPointEnd();
1565
1566     /**
1567         This function sets the maximum number of characters the user can enter
1568         into the control.
1569
1570         In other words, it allows to limit the text value length to @a len not
1571         counting the terminating @c NUL character.
1572
1573         If @a len is 0, the previously set max length limit, if any, is discarded
1574         and the user may enter as much text as the underlying native text control widget
1575         supports (typically at least 32Kb).
1576         If the user tries to enter more characters into the text control when it
1577         already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
1578         event is sent to notify the program about it (giving it the possibility
1579         to show an explanatory message, for example) and the extra input is discarded.
1580
1581         Note that in wxGTK this function may only be used with single line text controls.
1582     */
1583     virtual void SetMaxLength(unsigned long len);
1584
1585     /**
1586         Marks the control as being modified by the user or not.
1587
1588         @see MarkDirty(), DiscardEdits()
1589     */
1590     void SetModified(bool modified);
1591
1592     /**
1593         Selects the text starting at the first position up to (but not
1594         including) the character at the last position.
1595
1596         If both parameters are equal to -1 all text in the control is selected.
1597
1598         Notice that the insertion point will be moved to @a from by this
1599         function.
1600
1601         @param from
1602             The first position.
1603         @param to
1604             The last position.
1605
1606         @see SelectAll()
1607     */
1608     virtual void SetSelection(long from, long to);
1609
1610     /**
1611         Selects all text in the control.
1612
1613         @see SetSelection()
1614     */
1615     virtual void SelectAll();
1616
1617     /**
1618         Changes the style of the given range.
1619
1620         If any attribute within @a style is not set, the corresponding
1621         attribute from GetDefaultStyle() is used.
1622
1623         @param start
1624             The start of the range to change.
1625         @param end
1626             The end of the range to change.
1627         @param style
1628             The new style for the range.
1629
1630         @return
1631             @true on success, @false if an error occurred (this may also mean
1632             that the styles are not supported under this platform).
1633
1634         @see GetStyle(), wxTextAttr
1635     */
1636     virtual bool SetStyle(long start, long end, const wxTextAttr& style);
1637
1638     /**
1639         Sets the new text control value.
1640
1641         It also marks the control as not-modified which means that IsModified()
1642         would return @false immediately after the call to SetValue().
1643
1644         The insertion point is set to the start of the control (i.e. position
1645         0) by this function.
1646
1647         Note that, unlike most other functions changing the controls values,
1648         this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
1649         this you can use ChangeValue() instead.
1650
1651         @param value
1652             The new value to set. It may contain newline characters if the text
1653             control is multi-line.
1654     */
1655     virtual void SetValue(const wxString& value);
1656
1657     /**
1658         Makes the line containing the given position visible.
1659
1660         @param pos
1661             The position that should be visible.
1662     */
1663     virtual void ShowPosition(long pos);
1664
1665     /**
1666         If there is an undo facility and the last operation can be undone,
1667         undoes the last operation.
1668
1669         Does nothing if there is no undo facility.
1670     */
1671     virtual void Undo();
1672
1673     /**
1674         Writes the text into the text control at the current insertion position.
1675
1676         @param text
1677             Text to write to the text control.
1678
1679         @remarks
1680             Newlines in the text string are the only control characters
1681             allowed, and they will cause appropriate line breaks.
1682             See operator<<() and AppendText() for more convenient ways of
1683             writing to the window.
1684             After the write operation, the insertion point will be at the end
1685             of the inserted text, so subsequent write operations will be appended.
1686             To append text after the user may have interacted with the control,
1687             call wxTextCtrl::SetInsertionPointEnd() before writing.
1688     */
1689     virtual void WriteText(const wxString& text);
1690
1691     /**
1692         Converts the given zero based column and line number to a position.
1693
1694         @param x
1695             The column number.
1696         @param y
1697             The line number.
1698
1699         @return
1700             The position value, or -1 if x or y was invalid.
1701     */
1702     virtual long XYToPosition(long x, long y) const;
1703
1704     //@{
1705     /**
1706         Operator definitions for appending to a text control.
1707
1708         These operators can be used as with the standard C++ streams, for
1709         example:
1710         @code
1711             wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1712
1713             (*wnd) << "Welcome to text control number " << 1 << ".\n";
1714         @endcode
1715     */
1716
1717     wxTextCtrl& operator<<(const wxString& s);
1718     wxTextCtrl& operator<<(int i);
1719     wxTextCtrl& operator<<(long i);
1720     wxTextCtrl& operator<<(float f);
1721     wxTextCtrl& operator<<(double d);
1722     wxTextCtrl& operator<<(char c);
1723     wxTextCtrl& operator<<(wchar_t c);
1724     //@}
1725 };
1726
1727
1728
1729 /**
1730     @class wxStreamToTextRedirector
1731
1732     This class can be used to (temporarily) redirect all output sent to a C++
1733     ostream object to a wxTextCtrl instead.
1734
1735     @note
1736         Some compilers and/or build configurations don't support multiply
1737         inheriting wxTextCtrl from @c std::streambuf in which case this class is
1738         not compiled in.
1739         You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your
1740         @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams
1741         switch when running configure for this.
1742
1743     Example of usage:
1744
1745     @code
1746     using namespace std;
1747     wxTextCtrl* text = new wxTextCtrl(...);
1748     {
1749         wxStreamToTextRedirector redirect(text);
1750
1751         // this goes to the text control
1752         cout << "Hello, text!" << endl;
1753     }
1754     // this goes somewhere else, presumably to stdout
1755     cout << "Hello, console!" << endl;
1756     @endcode
1757
1758     @library{wxcore}
1759     @category{logging}
1760
1761     @see wxTextCtrl
1762 */
1763 class wxStreamToTextRedirector
1764 {
1765 public:
1766     /**
1767         The constructor starts redirecting output sent to @a ostr or @a cout for
1768         the default parameter value to the text control @a text.
1769
1770         @param text
1771             The text control to append output too, must be non-@NULL
1772         @param ostr
1773             The C++ stream to redirect, cout is used if it is @NULL
1774     */
1775     wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
1776
1777     /**
1778         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1779         and any output sent to the C++ ostream which had been specified at the time of
1780         the object construction will go to its original destination.
1781     */
1782     ~wxStreamToTextRedirector();
1783 };
1784