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