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