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