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