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