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