interface/textctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        textctrl.h
   3 // Purpose:     interface of wxTextAttr
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTextAttr
  11     @wxheader{textctrl.h}
  12
  13     wxTextAttr represents the character and paragraph attributes, or style,
  14     for a range of text in a wxTextCtrl or wxRichTextCtrl.
  15
  16     When setting up a wxTextAttr object, pass a bitlist mask to
  17     wxTextAttr::SetFlags to
  18     indicate which style elements should be changed. As a convenience, when you
  19     call a setter such
  20     as SetFont, the relevant bit will be set.
  21
  22     @library{wxcore}
  23     @category{richtext}
  24
  25     @see wxTextCtrl, wxRichTextCtrl
  26 */
  27 class wxTextAttr
  28 {
  29 public:
  30     //@{
  31     /**
  32         Constructors.
  33     */
  34     wxTextAttr();
  35     wxTextAttr(const wxColour& colText,
  36                const wxColour& colBack = wxNullColour,
  37                const wxFont& font = wxNullFont,
  38                wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT);
  39     wxTextAttr(const wxTextAttr& attr);
  40     //@}
  41
  42     /**
  43         Applies the attributes in @a style to the original object, but not those
  44         attributes from @a style that are the same as those in @a compareWith (if passed).
  45     */
  46     bool Apply(const wxTextAttr& style,
  47                const wxTextAttr* compareWith = NULL);
  48
  49     /**
  50         Creates a font from the font attributes.
  51     */
  52     wxFont CreateFont() const;
  53
  54     /**
  55         Returns the alignment flags.
  56         See SetAlignment() for a list of available styles.
  57     */
  58     wxTextAttrAlignment GetAlignment() const;
  59
  60     /**
  61         Returns the background colour.
  62     */
  63     const wxColour GetBackgroundColour() const;
  64
  65     /**
  66         Returns a string containing the name of the font associated with the bullet
  67         symbol.
  68         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
  69     */
  70     const wxString GetBulletFont() const;
  71
  72     /**
  73         Returns the standard bullet name, applicable if the bullet style is
  74         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
  75         Currently the following standard bullet names are supported:
  76          @c standard/circle
  77          @c standard/square
  78          @c standard/diamond
  79          @c standard/triangle
  80         For wxRichTextCtrl users only: if you wish your rich text controls to support
  81         further bullet graphics, you can derive a
  82         class from wxRichTextRenderer or wxRichTextStdRenderer, override @c
  83         DrawStandardBullet and @c EnumerateStandardBulletNames, and
  84         set an instance of the class using wxRichTextBuffer::SetRenderer.
  85     */
  86     const wxString GetBulletName() const;
  87
  88     /**
  89         Returns the bullet number.
  90     */
  91     int GetBulletNumber() const;
  92
  93     /**
  94         Returns the bullet style.
  95         See SetBulletStyle() for a list of available styles.
  96     */
  97     int GetBulletStyle() const;
  98
  99     /**
 100         Returns the bullet text, which could be a symbol, or (for example) cached
 101         outline text.
 102     */
 103     const wxString GetBulletText() const;
 104
 105     /**
 106         Returns the name of the character style.
 107     */
 108     const wxString GetCharacterStyleName() const;
 109
 110     /**
 111         Returns flags indicating which attributes are applicable.
 112         See SetFlags() for a list of available flags.
 113     */
 114     long GetFlags() const;
 115
 116     /**
 117         Creates and returns a font specified by the font attributes in the wxTextAttr
 118         object. Note that
 119         wxTextAttr does not store a wxFont object, so this is only a temporary font.
 120         For greater
 121         efficiency, access the font attributes directly.
 122     */
 123     wxFont GetFont() const;
 124
 125     /**
 126         Gets the font attributes from the given font, using only the attributes
 127         specified by @e flags.
 128     */
 129     bool GetFontAttributes(const wxFont& font,
 130                            int flags = wxTEXT_ATTR_FONT);
 131
 132     /**
 133         Returns the font encoding.
 134     */
 135     wxFontEncoding GetFontEncoding() const;
 136
 137     /**
 138         Returns the font face name.
 139     */
 140     const wxString GetFontFaceName() const;
 141
 142     /**
 143         Returns the font size in points.
 144     */
 145     int GetFontSize() const;
 146
 147     /**
 148         Returns the font style.
 149     */
 150     int GetFontStyle() const;
 151
 152     /**
 153         Returns @true if the font is underlined.
 154     */
 155     bool GetFontUnderlined() const;
 156
 157     /**
 158         Returns the font weight.
 159     */
 160     int GetFontWeight() const;
 161
 162     /**
 163         Returns the left indent in tenths of a millimetre.
 164     */
 165     long GetLeftIndent() const;
 166
 167     /**
 168         Returns the left sub-indent in tenths of a millimetre.
 169     */
 170     long GetLeftSubIndent() const;
 171
 172     /**
 173         Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL,
 174         wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE.
 175     */
 176     int GetLineSpacing() const;
 177
 178     /**
 179         Returns the name of the list style.
 180     */
 181     const wxString GetListStyleName() const;
 182
 183     /**
 184         Returns the outline level.
 185     */
 186     bool GetOutlineLevel() const;
 187
 188     /**
 189         Returns the space in tenths of a millimeter after the paragraph.
 190     */
 191     int GetParagraphSpacingAfter() const;
 192
 193     /**
 194         Returns the space in tenths of a millimeter before the paragraph.
 195     */
 196     int GetParagraphSpacingBefore() const;
 197
 198     /**
 199         Returns the name of the paragraph style.
 200     */
 201     const wxString GetParagraphStyleName() const;
 202
 203     /**
 204         Returns the right indent in tenths of a millimeter.
 205     */
 206     long GetRightIndent() const;
 207
 208     /**
 209         Returns an array of tab stops, each expressed in tenths of a millimeter. Each
 210         stop
 211         is measured from the left margin and therefore each value must be larger than
 212         the last.
 213     */
 214     const wxArrayInt GetTabs() const;
 215
 216     /**
 217         Returns the text foreground colour.
 218     */
 219     const wxColour GetTextColour() const;
 220
 221     /**
 222         Returns the text effect bits of interest. See SetFlags() for further
 223         information.
 224     */
 225     int GetTextEffectFlags() const;
 226
 227     /**
 228         Returns the text effects, a bit list of styles. See SetTextEffects() for
 229         details.
 230     */
 231     int GetTextEffects() const;
 232
 233     /**
 234         Returns the URL for the content. Content with wxTEXT_ATTR_URL style
 235         causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
 236         generates
 237         a wxTextUrlEvent when the content is clicked.
 238     */
 239     const wxString GetURL() const;
 240
 241     /**
 242         Returns @true if the attribute object specifies alignment.
 243     */
 244     bool HasAlignment() const;
 245
 246     /**
 247         Returns @true if the attribute object specifies a background colour.
 248     */
 249     bool HasBackgroundColour() const;
 250
 251     /**
 252         Returns @true if the attribute object specifies a standard bullet name.
 253     */
 254     bool HasBulletName() const;
 255
 256     /**
 257         Returns @true if the attribute object specifies a bullet number.
 258     */
 259     bool HasBulletNumber() const;
 260
 261     /**
 262         Returns @true if the attribute object specifies a bullet style.
 263     */
 264     bool HasBulletStyle() const;
 265
 266     /**
 267         Returns @true if the attribute object specifies bullet text (usually
 268         specifying a symbol).
 269     */
 270     bool HasBulletText() const;
 271
 272     /**
 273         Returns @true if the attribute object specifies a character style name.
 274     */
 275     bool HasCharacterStyleName() const;
 276
 277     /**
 278         Returns @true if the @a flag is present in the attribute object's flag
 279         bitlist.
 280     */
 281     bool HasFlag(long flag) const;
 282
 283     /**
 284         Returns @true if the attribute object specifies any font attributes.
 285     */
 286     bool HasFont() const;
 287
 288     /**
 289         Returns @true if the attribute object specifies an encoding.
 290     */
 291     bool HasFontEncoding() const;
 292
 293     /**
 294         Returns @true if the attribute object specifies a font face name.
 295     */
 296     bool HasFontFaceName() const;
 297
 298     /**
 299         Returns @true if the attribute object specifies italic style.
 300     */
 301     bool HasFontItalic() const;
 302
 303     /**
 304         Returns @true if the attribute object specifies a font point size.
 305     */
 306     bool HasFontSize() const;
 307
 308     /**
 309         Returns @true if the attribute object specifies either underlining or no
 310         underlining.
 311     */
 312     bool HasFontUnderlined() const;
 313
 314     /**
 315         Returns @true if the attribute object specifies font weight (bold, light or
 316         normal).
 317     */
 318     bool HasFontWeight() const;
 319
 320     /**
 321         Returns @true if the attribute object specifies a left indent.
 322     */
 323     bool HasLeftIndent() const;
 324
 325     /**
 326         Returns @true if the attribute object specifies line spacing.
 327     */
 328     bool HasLineSpacing() const;
 329
 330     /**
 331         Returns @true if the attribute object specifies a list style name.
 332     */
 333     bool HasListStyleName() const;
 334
 335     /**
 336         Returns @true if the attribute object specifies an outline level.
 337     */
 338     bool HasOutlineLevel() const;
 339
 340     /**
 341         Returns @true if the attribute object specifies a page break before this
 342         paragraph.
 343     */
 344     bool HasPageBreak() const;
 345
 346     /**
 347         Returns @true if the attribute object specifies spacing after a paragraph.
 348     */
 349     bool HasParagraphSpacingAfter() const;
 350
 351     /**
 352         Returns @true if the attribute object specifies spacing before a paragraph.
 353     */
 354     bool HasParagraphSpacingBefore() const;
 355
 356     /**
 357         Returns @true if the attribute object specifies a paragraph style name.
 358     */
 359     bool HasParagraphStyleName() const;
 360
 361     /**
 362         Returns @true if the attribute object specifies a right indent.
 363     */
 364     bool HasRightIndent() const;
 365
 366     /**
 367         Returns @true if the attribute object specifies tab stops.
 368     */
 369     bool HasTabs() const;
 370
 371     /**
 372         Returns @true if the attribute object specifies a text foreground colour.
 373     */
 374     bool HasTextColour() const;
 375
 376     /**
 377         Returns @true if the attribute object specifies text effects.
 378     */
 379     bool HasTextEffects() const;
 380
 381     /**
 382         Returns @true if the attribute object specifies a URL.
 383     */
 384     bool HasURL() const;
 385
 386     /**
 387         Returns @true if the object represents a character style, that is,
 388         the flags specify a font or a text background or foreground colour.
 389     */
 390     bool IsCharacterStyle() const;
 391
 392     /**
 393         Returns @false if we have any attributes set, @true otherwise.
 394     */
 395     bool IsDefault() const;
 396
 397     /**
 398         Returns @true if the object represents a paragraph style, that is,
 399         the flags specify alignment, indentation, tabs, paragraph spacing, or
 400         bullet style.
 401     */
 402     bool IsParagraphStyle() const;
 403
 404     //@{
 405     /**
 406         Creates a new @c wxTextAttr which is a merge of @a base and
 407         @e overlay. Properties defined in @a overlay take precedence over those
 408         in @e base. Properties undefined/invalid in both are undefined in the
 409         result.
 410     */
 411     void Merge(const wxTextAttr& overlay);
 412     static wxTextAttr Merge(const wxTextAttr& base,
 413                             const wxTextAttr& overlay);
 414     //@}
 415
 416     /**
 417         Sets the paragraph alignment. These are the possible values for @e alignment:
 418
 419         Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification
 420         may be supported
 421         when printing or previewing, only.
 422     */
 423     void SetAlignment(wxTextAttrAlignment alignment);
 424
 425     /**
 426         Sets the background colour.
 427     */
 428     void SetBackgroundColour(const wxColour& colBack);
 429
 430     /**
 431         Sets the name of the font associated with the bullet symbol.
 432         Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
 433     */
 434     void SetBulletFont(const wxString& font);
 435
 436     /**
 437         Sets the standard bullet name, applicable if the bullet style is
 438         wxTEXT_ATTR_BULLET_STYLE_STANDARD.
 439         See GetBulletName() for a list
 440         of supported names, and how to expand the range of supported types.
 441     */
 442     void SetBulletName(const wxString& name);
 443
 444     /**
 445         Sets the bullet number.
 446     */
 447     void SetBulletNumber(int n);
 448
 449     /**
 450         Sets the bullet style. The following styles can be passed:
 451
 452         Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported.
 453     */
 454     void SetBulletStyle(int style);
 455
 456     /**
 457         Sets the bullet text, which could be a symbol, or (for example) cached outline
 458         text.
 459     */
 460     void SetBulletText(const wxString text);
 461
 462     /**
 463         Sets the character style name.
 464     */
 465     void SetCharacterStyleName(const wxString& name);
 466
 467     /**
 468         Sets the flags determining which styles are being specified. The following
 469         flags can be passed in a bitlist:
 470     */
 471     void SetFlags(long flags);
 472
 473     /**
 474         Sets the attributes for the given font. Note that wxTextAttr does not store an
 475         actual wxFont object.
 476     */
 477     void SetFont(const wxFont& font);
 478
 479     /**
 480         Sets the font encoding.
 481     */
 482     void SetFontEncoding(wxFontEncoding encoding);
 483
 484     /**
 485         Sets the paragraph alignment.
 486     */
 487     void SetFontFaceName(const wxString& faceName);
 488
 489     /**
 490         Sets the font size in points.
 491     */
 492     void SetFontSize(int pointSize);
 493
 494     /**
 495         Sets the font style (normal, italic or slanted).
 496     */
 497     void SetFontStyle(int fontStyle);
 498
 499     /**
 500         Sets the font underlining.
 501     */
 502     void SetFontUnderlined(bool underlined);
 503
 504     /**
 505         Sets the font weight.
 506     */
 507     void SetFontWeight(int fontWeight);
 508
 509     /**
 510         Sets the left indent and left subindent in tenths of a millimetre.
 511         The sub-indent is an offset from the left of the paragraph, and is used for all
 512         but the
 513         first line in a paragraph. A positive value will cause the first line to appear
 514         to the left
 515         of the subsequent lines, and a negative value will cause the first line to be
 516         indented
 517         relative to the subsequent lines.
 518         wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
 519         the distance between
 520         the margin and the bullet. The content of the paragraph, including the first
 521         line, starts
 522         at leftMargin + leftSubIndent. So the distance between the left edge of the
 523         bullet and the
 524         left of the actual paragraph is leftSubIndent.
 525     */
 526     void SetLeftIndent(int indent, int subIndent = 0);
 527
 528     /**
 529         Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
 530         15 means 1.5 spacing, and 20 means double spacing. The following constants are
 531         defined for convenience:
 532     */
 533     void SetLineSpacing(int spacing);
 534
 535     /**
 536         Sets the list style name.
 537     */
 538     void SetListStyleName(const wxString& name);
 539
 540     /**
 541         Specifies the outline level. Zero represents normal text. At present, the
 542         outline level is
 543         not used, but may be used in future for determining list levels and for
 544         applications
 545         that need to store document structure information.
 546     */
 547     void SetOutlineLevel(int level);
 548
 549     /**
 550         Specifies a page break before this paragraph.
 551     */
 552     void SetPageBreak(bool pageBreak = true);
 553
 554     /**
 555         Sets the spacing after a paragraph, in tenths of a millimetre.
 556     */
 557     void SetParagraphSpacingAfter(int spacing);
 558
 559     /**
 560         Sets the spacing before a paragraph, in tenths of a millimetre.
 561     */
 562     void SetParagraphSpacingBefore(int spacing);
 563
 564     /**
 565         Sets the name of the paragraph style.
 566     */
 567     void SetParagraphStyleName(const wxString& name);
 568
 569     /**
 570         Sets the right indent in tenths of a millimetre.
 571     */
 572     void SetRightIndent(int indent);
 573
 574     /**
 575         Sets the tab stops, expressed in tenths of a millimetre.
 576         Each stop is measured from the left margin and therefore each value must be
 577         larger than the last.
 578     */
 579     void SetTabs(const wxArrayInt& tabs);
 580
 581     /**
 582         Sets the text foreground colout.
 583     */
 584     void SetTextColour(const wxColour& colText);
 585
 586     /**
 587         Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS
 588         to SetFlags().
 589         See SetFlags() for further information.
 590     */
 591     void SetTextEffectFlags(int flags);
 592
 593     /**
 594         Sets the text effects, a bit list of styles.
 595         The following styles can be passed:
 596
 597         Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
 598         are implemented.
 599         wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
 600         of the actual buffer
 601         text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text.
 602         To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
 603         SetTextEffectFlags() with the styles (taken from the
 604         above set) that you are interested in setting.
 605     */
 606     void SetTextEffects(int effects);
 607
 608     /**
 609         Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
 610         style
 611         causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
 612         generates
 613         a wxTextUrlEvent when the content is clicked.
 614     */
 615     void SetURL(const wxString& url);
 616
 617     /**
 618         Assignment from a wxTextAttr object.
 619     */
 620     void operator operator=(const wxTextAttr& attr);
 621 };
 622
 623
 624
 625 /**
 626     @class wxTextCtrl
 627     @wxheader{textctrl.h}
 628
 629     A text control allows text to be displayed and edited. It may be
 630     single line or multi-line.
 631
 632     @beginStyleTable
 633     @style{wxTE_PROCESS_ENTER}:
 634            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
 635            (otherwise pressing Enter key is either processed internally by the
 636            control or used for navigation between dialog controls).
 637     @style{wxTE_PROCESS_TAB}:
 638            The control will receive wxEVT_CHAR events for TAB pressed -
 639            normally, TAB is used for passing to the next control in a dialog
 640            instead. For the control created with this style, you can still use
 641            Ctrl-Enter to pass to the next control from the keyboard.
 642     @style{wxTE_MULTILINE}:
 643            The text control allows multiple lines.
 644     @style{wxTE_PASSWORD}:
 645            The text will be echoed as asterisks.
 646     @style{wxTE_READONLY}:
 647            The text will not be user-editable.
 648     @style{wxTE_RICH}:
 649            Use rich text control under Win32, this allows to have more than
 650            64KB of text in the control even under Win9x. This style is ignored
 651            under other platforms.
 652     @style{wxTE_RICH2}:
 653            Use rich text control version 2.0 or 3.0 under Win32, this style is
 654            ignored under other platforms
 655     @style{wxTE_AUTO_URL}:
 656            Highlight the URLs and generate the wxTextUrlEvents when mouse
 657            events occur over them. This style is only supported for wxTE_RICH
 658            Win32 and multi-line wxGTK2 text controls.
 659     @style{wxTE_NOHIDESEL}:
 660            By default, the Windows text control doesn't show the selection
 661            when it doesn't have focus - use this style to force it to always
 662            show it. It doesn't do anything under other platforms.
 663     @style{wxHSCROLL}:
 664            A horizontal scrollbar will be created and used, so that text won't
 665            be wrapped. No effect under wxGTK1.
 666     @style{wxTE_NO_VSCROLL}:
 667            For multiline controls only: vertical scrollbar will never be
 668            created. This limits the amount of text which can be entered into
 669            the control to what can be displayed in it under MSW but not under
 670            GTK2. Currently not implemented for the other platforms.
 671     @style{wxTE_LEFT}:
 672            The text in the control will be left-justified (default).
 673     @style{wxTE_CENTRE}:
 674            The text in the control will be centered (currently wxMSW and
 675            wxGTK2 only).
 676     @style{wxTE_RIGHT}:
 677            The text in the control will be right-justified (currently wxMSW
 678            and wxGTK2 only).
 679     @style{wxTE_DONTWRAP}:
 680            Same as wxHSCROLL style: don't wrap at all, show horizontal
 681            scrollbar instead.
 682     @style{wxTE_CHARWRAP}:
 683            Wrap the lines too long to be shown entirely at any position
 684            (wxUniv and wxGTK2 only).
 685     @style{wxTE_WORDWRAP}:
 686            Wrap the lines too long to be shown entirely at word boundaries
 687            (wxUniv and wxGTK2 only).
 688     @style{wxTE_BESTWRAP}:
 689            Wrap the lines at word boundaries or at any other character if
 690            there are words longer than the window width (this is the default).
 691     @style{wxTE_CAPITALIZE}:
 692            On PocketPC and Smartphone, causes the first letter to be
 693            capitalized.
 694     @endStyleTable
 695
 696     @library{wxcore}
 697     @category{ctrl}
 698     @appearance{textctrl.png}
 699
 700     @see wxTextCtrl::Create, wxValidator
 701 */
 702 class wxTextCtrl : public wxControl
 703 {
 704 public:
 705     //@{
 706     /**
 707         Constructor, creating and showing a text control.
 708
 709         @param parent
 710             Parent window. Should not be @NULL.
 711         @param id
 712             Control identifier. A value of -1 denotes a default value.
 713         @param value
 714             Default text value.
 715         @param pos
 716             Text control position.
 717         @param size
 718             Text control size.
 719         @param style
 720             Window style. See wxTextCtrl.
 721         @param validator
 722             Window validator.
 723         @param name
 724             Window name.
 725
 726         @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
 727                  created for multi-line text controls. Without a
 728                  horizontal scrollbar, text lines that don't fit in the
 729                  control's size will be wrapped (but no newline
 730                  character is inserted). Single line controls don't have
 731                  a horizontal scrollbar, the text is automatically
 732                  scrolled so that the insertion point is always visible.
 733
 734         @see Create(), wxValidator
 735     */
 736     wxTextCtrl();
 737     wxTextCtrl(wxWindow* parent, wxWindowID id,
 738                const wxString& value = "",
 739                const wxPoint& pos = wxDefaultPosition,
 740                const wxSize& size = wxDefaultSize,
 741                long style = 0,
 742                const wxValidator& validator = wxDefaultValidator,
 743                const wxString& name = wxTextCtrlNameStr);
 744     //@}
 745
 746     /**
 747         Destructor, destroying the text control.
 748     */
 749     ~wxTextCtrl();
 750
 751     /**
 752         Appends the text to the end of the text control.
 753
 754         @param text
 755             Text to write to the text control.
 756
 757         @remarks After the text is appended, the insertion point will be at the
 758                  end of the text control. If this behaviour is not
 759                  desired, the programmer should use GetInsertionPoint
 760                  and SetInsertionPoint.
 761
 762         @see WriteText()
 763     */
 764     void AppendText(const wxString& text);
 765
 766     /**
 767         Call this function to enable auto-completion of the text typed in a single-line
 768         text control using the given @e choices.
 769         Notice that currently this function is only implemented in wxGTK2 and wxMSW
 770         ports and does nothing under the other platforms.
 771
 772         @wxsince{2.9.0}
 773
 774         @returns @true if the auto-completion was enabled or @false if the
 775                  operation failed, typically because auto-completion is
 776                  not supported by the current platform.
 777
 778         @see AutoCompleteFileNames()
 779     */
 780     bool AutoComplete(const wxArrayString& choices);
 781
 782     /**
 783         Call this function to enable auto-completion of the text typed in a single-line
 784         text control using all valid file system paths.
 785         Notice that currently this function is only implemented in wxGTK2 port and does
 786         nothing under the other platforms.
 787
 788         @wxsince{2.9.0}
 789
 790         @returns @true if the auto-completion was enabled or @false if the
 791                  operation failed, typically because auto-completion is
 792                  not supported by the current platform.
 793
 794         @see AutoComplete()
 795     */
 796     bool AutoCompleteFileNames();
 797
 798     /**
 799         Returns @true if the selection can be copied to the clipboard.
 800     */
 801     virtual bool CanCopy();
 802
 803     /**
 804         Returns @true if the selection can be cut to the clipboard.
 805     */
 806     virtual bool CanCut();
 807
 808     /**
 809         Returns @true if the contents of the clipboard can be pasted into the
 810         text control. On some platforms (Motif, GTK) this is an approximation
 811         and returns @true if the control is editable, @false otherwise.
 812     */
 813     virtual bool CanPaste();
 814
 815     /**
 816         Returns @true if there is a redo facility available and the last operation
 817         can be redone.
 818     */
 819     virtual bool CanRedo();
 820
 821     /**
 822         Returns @true if there is an undo facility available and the last operation
 823         can be undone.
 824     */
 825     virtual bool CanUndo();
 826
 827     /**
 828         Sets the text value and marks the control as not-modified (which means that
 829         IsModified() would return @false immediately
 830         after the call to SetValue).
 831         Note that this function will not generate the @c wxEVT_COMMAND_TEXT_UPDATED
 832         event.
 833         This is the only difference with SetValue().
 834         See @ref overview_progevent "this topic" for more information.
 835
 836         @wxsince{2.7.1}
 837
 838         @param value
 839             The new value to set. It may contain newline characters if the text control
 840         is multi-line.
 841     */
 842     virtual void ChangeValue(const wxString& value);
 843
 844     /**
 845         Clears the text in the control.
 846         Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
 847         event.
 848     */
 849     virtual void Clear();
 850
 851     /**
 852         Copies the selected text to the clipboard under Motif and MS Windows.
 853     */
 854     virtual void Copy();
 855
 856     /**
 857         Creates the text control for two-step construction. Derived classes
 858         should call or replace this function. See wxTextCtrl()
 859         for further details.
 860     */
 861     bool Create(wxWindow* parent, wxWindowID id,
 862                 const wxString& value = "",
 863                 const wxPoint& pos = wxDefaultPosition,
 864                 const wxSize& size = wxDefaultSize,
 865                 long style = 0,
 866                 const wxValidator& validator = wxDefaultValidator,
 867                 const wxString& name = wxTextCtrlNameStr);
 868
 869     /**
 870         Copies the selected text to the clipboard and removes the selection.
 871     */
 872     virtual void Cut();
 873
 874     /**
 875         Resets the internal 'modified' flag as if the current edits had been saved.
 876     */
 877     void DiscardEdits();
 878
 879     /**
 880         This functions inserts into the control the character which would have been
 881         inserted if the given key event had occurred in the text control. The
 882         @a event object should be the same as the one passed to @c EVT_KEY_DOWN
 883         handler previously by wxWidgets.
 884         Please note that this function doesn't currently work correctly for all keys
 885         under any platform but MSW.
 886
 887         @returns @true if the event resulted in a change to the control, @false
 888                  otherwise.
 889     */
 890     bool EmulateKeyPress(const wxKeyEvent& event);
 891
 892     /**
 893         Returns the style currently used for the new text.
 894
 895         @see SetDefaultStyle()
 896     */
 897     const wxTextAttr GetDefaultStyle() const;
 898
 899     /**
 900         Returns the insertion point. This is defined as the zero based index of the
 901         character position to the right of the insertion point. For example, if
 902         the insertion point is at the end of the text control, it is equal to
 903         both GetValue().Length() and
 904         GetLastPosition().
 905         The following code snippet safely returns the character at the insertion
 906         point or the zero character if the point is at the end of the control.
 907     */
 908     virtual long GetInsertionPoint() const;
 909
 910     /**
 911         Returns the zero based index of the last position in the text control,
 912         which is equal to the number of characters in the control.
 913     */
 914     virtual wxTextPos GetLastPosition() const;
 915
 916     /**
 917         Gets the length of the specified line, not including any trailing newline
 918         character(s).
 919
 920         @param lineNo
 921             Line number (starting from zero).
 922
 923         @returns The length of the line, or -1 if lineNo was invalid.
 924     */
 925     int GetLineLength(long lineNo) const;
 926
 927     /**
 928         Returns the contents of a given line in the text control, not including
 929         any trailing newline character(s).
 930
 931         @param lineNo
 932             The line number, starting from zero.
 933
 934         @returns The contents of the line.
 935     */
 936     wxString GetLineText(long lineNo) const;
 937
 938     /**
 939         Returns the number of lines in the text control buffer.
 940
 941         @remarks Note that even empty text controls have one line (where the
 942                  insertion point is), so GetNumberOfLines() never
 943                  returns 0.
 944     */
 945     int GetNumberOfLines() const;
 946
 947     /**
 948         Returns the string containing the text starting in the positions @a from and
 949         up to @a to in the control. The positions must have been returned by another
 950         wxTextCtrl method.
 951         Please note that the positions in a multiline wxTextCtrl do @b not
 952         correspond to the indices in the string returned by
 953         GetValue() because of the different new line
 954         representations (@c CR or @c CR LF) and so this method should be used to
 955         obtain the correct results instead of extracting parts of the entire value. It
 956         may also be more efficient, especially if the control contains a lot of data.
 957     */
 958     virtual wxString GetRange(long from, long to) const;
 959
 960     /**
 961         Gets the current selection span. If the returned values are equal, there was
 962         no selection.
 963         Please note that the indices returned may be used with the other wxTextctrl
 964         methods but don't necessarily represent the correct indices into the string
 965         returned by GetValue() for multiline controls
 966         under Windows (at least,) you should use
 967         GetStringSelection() to get the selected
 968         text.
 969
 970         @param from
 971             The returned first position.
 972         @param to
 973             The returned last position.
 974     */
 975     virtual void GetSelection(long* from, long* to) const;
 976
 977     /**
 978         Gets the text currently selected in the control. If there is no selection, the
 979         returned string is empty.
 980     */
 981     virtual wxString GetStringSelection();
 982
 983     /**
 984         Returns the style at this position in the text control. Not all platforms
 985         support this function.
 986
 987         @returns @true on success, @false if an error occurred - it may also mean
 988                  that the styles are not supported under this platform.
 989
 990         @see SetStyle(), wxTextAttr
 991     */
 992     bool GetStyle(long position, wxTextAttr& style);
 993
 994     /**
 995         Gets the contents of the control. Notice that for a multiline text control,
 996         the lines will be separated by (Unix-style) \n characters, even
 997         under Windows where they are separated by a \r\n
 998         sequence in the native control.
 999     */
1000     wxString GetValue() const;
1001
1002     /**
1003         This function finds the character at the specified position expressed in
1004         pixels. If the return code is not @c wxTE_HT_UNKNOWN the row and column
1005         of the character closest to this position are returned in the @a col and
1006         @a row parameters (unless the pointers are @NULL which is allowed).
1007         Please note that this function is currently only implemented in wxUniv,
1008         wxMSW and wxGTK2 ports.
1009
1010         @see PositionToXY(), XYToPosition()
1011     */
1012     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1013                                     wxTextCoord col,
1014                                     wxTextCoord row) const;
1015
1016     /**
1017         Returns @true if the controls contents may be edited by user (note that it
1018         always can be changed by the program), i.e. if the control hasn't been put in
1019         read-only mode by a previous call to
1020         SetEditable().
1021     */
1022     bool IsEditable() const;
1023
1024     /**
1025         Returns @true if the control is currently empty. This is the same as
1026         @c GetValue().empty() but can be much more efficient for the multiline
1027         controls containing big amounts of text.
1028
1029         @wxsince{2.7.1}
1030     */
1031     bool IsEmpty() const;
1032
1033     /**
1034         Returns @true if the text has been modified by user. Note that calling
1035         SetValue() doesn't make the control modified.
1036
1037         @see MarkDirty()
1038     */
1039     bool IsModified() const;
1040
1041     /**
1042         Returns @true if this is a multi line edit control and @false
1043         otherwise.
1044
1045         @see IsSingleLine()
1046     */
1047     bool IsMultiLine() const;
1048
1049     /**
1050         Returns @true if this is a single line edit control and @false
1051         otherwise.
1052
1053         @see @ref issingleline() IsMultiLine
1054     */
1055     bool IsSingleLine() const;
1056
1057     /**
1058         Loads and displays the named file, if it exists.
1059
1060         @param filename
1061             The filename of the file to load.
1062         @param fileType
1063             The type of file to load. This is currently ignored in wxTextCtrl.
1064
1065         @returns @true if successful, @false otherwise.
1066     */
1067     bool LoadFile(const wxString& filename,
1068                   int fileType = wxTEXT_TYPE_ANY);
1069
1070     /**
1071         Mark text as modified (dirty).
1072
1073         @see IsModified()
1074     */
1075     void MarkDirty();
1076
1077     /**
1078         This event handler function implements default drag and drop behaviour, which
1079         is to load the first dropped file into the control.
1080
1081         @param event
1082             The drop files event.
1083
1084         @remarks This is not implemented on non-Windows platforms.
1085
1086         @see wxDropFilesEvent
1087     */
1088     void OnDropFiles(wxDropFilesEvent& event);
1089
1090     /**
1091         Pastes text from the clipboard to the text item.
1092     */
1093     virtual void Paste();
1094
1095     /**
1096         Converts given position to a zero-based column, line number pair.
1097
1098         @param pos
1099             Position.
1100         @param x
1101             Receives zero based column number.
1102         @param y
1103             Receives zero based line number.
1104
1105         @returns @true on success, @false on failure (most likely due to a too
1106                  large position parameter).
1107
1108         @see XYToPosition()
1109     */
1110     bool PositionToXY(long pos, long* x, long* y) const;
1111
1112     /**
1113         If there is a redo facility and the last operation can be redone, redoes the
1114         last operation. Does nothing
1115         if there is no redo facility.
1116     */
1117     virtual void Redo();
1118
1119     /**
1120         Removes the text starting at the first given position up to (but not including)
1121         the character at the last position.
1122
1123         @param from
1124             The first position.
1125         @param to
1126             The last position.
1127     */
1128     virtual void Remove(long from, long to);
1129
1130     /**
1131         Replaces the text starting at the first position up to (but not including)
1132         the character at the last position with the given text.
1133
1134         @param from
1135             The first position.
1136         @param to
1137             The last position.
1138         @param value
1139             The value to replace the existing text with.
1140     */
1141     virtual void Replace(long from, long to, const wxString& value);
1142
1143     /**
1144         Saves the contents of the control in a text file.
1145
1146         @param filename
1147             The name of the file in which to save the text.
1148         @param fileType
1149             The type of file to save. This is currently ignored in wxTextCtrl.
1150
1151         @returns @true if the operation was successful, @false otherwise.
1152     */
1153     bool SaveFile(const wxString& filename,
1154                   int fileType = wxTEXT_TYPE_ANY);
1155
1156     /**
1157         Changes the default style to use for the new text which is going to be added
1158         to the control using WriteText() or
1159         AppendText().
1160         If either of the font, foreground, or background colour is not set in
1161         @e style, the values of the previous default style are used for them. If
1162         the previous default style didn't set them neither, the global font or colours
1163         of the text control itself are used as fall back.
1164         However if the @a style parameter is the default wxTextAttr, then the
1165         default style is just reset (instead of being combined with the new style which
1166         wouldn't change it at all).
1167
1168         @param style
1169             The style for the new text.
1170
1171         @returns @true on success, @false if an error occurred - may also mean that
1172                  the styles are not supported under this platform.
1173
1174         @see GetDefaultStyle()
1175     */
1176     bool SetDefaultStyle(const wxTextAttr& style);
1177
1178     /**
1179         Makes the text item editable or read-only, overriding the @b wxTE_READONLY flag.
1180
1181         @param editable
1182             If @true, the control is editable. If @false, the control is read-only.
1183
1184         @see IsEditable()
1185     */
1186     virtual void SetEditable(const bool editable);
1187
1188     /**
1189         Sets the insertion point at the given position.
1190
1191         @param pos
1192             Position to set.
1193     */
1194     virtual void SetInsertionPoint(long pos);
1195
1196     /**
1197         Sets the insertion point at the end of the text control. This is equivalent
1198         to wxTextCtrl::SetInsertionPoint(wxTextCtrl::GetLastPosition()).
1199     */
1200     virtual void SetInsertionPointEnd();
1201
1202     /**
1203         This function sets the maximum number of characters the user can enter into the
1204         control. In other words, it allows to limit the text value length to @e len
1205         not counting the terminating @c NUL character.
1206         If @a len is 0, the previously set max length limit, if any, is discarded
1207         and the user may enter as much text as the underlying native text control
1208         widget supports (typically at least 32Kb).
1209         If the user tries to enter more characters into the text control when it
1210         already is filled up to the maximal length, a
1211         @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify the program about it
1212         (giving it the possibility to show an explanatory message, for example) and the
1213         extra input is discarded.
1214         Note that under GTK+, this function may only be used with single line text
1215         controls.
1216     */
1217     virtual void SetMaxLength(unsigned long len);
1218
1219     /**
1220         Marks the control as being modified by the user or not.
1221
1222         @see MarkDirty(), DiscardEdits()
1223     */
1224     void SetModified(bool modified);
1225
1226     /**
1227         Selects the text starting at the first position up to (but not
1228         including) the character at the last position. If both parameters are
1229         equal to -1 all text in the control is selected.
1230
1231         @param from
1232             The first position.
1233         @param to
1234             The last position.
1235
1236         @see SelectAll()
1237     */
1238     virtual void SetSelection(long from, long to);
1239
1240     /**
1241         Selects all text in the control.
1242
1243         @see SetSelection()
1244     */
1245     virtual void SelectAll();
1246
1247     /**
1248         Changes the style of the given range. If any attribute within @a style is
1249         not set, the corresponding attribute from GetDefaultStyle() is used.
1250
1251         @param start
1252             The start of the range to change.
1253         @param end
1254             The end of the range to change.
1255         @param style
1256             The new style for the range.
1257
1258         @returns @true on success, @false if an error occurred - it may also mean
1259                  that the styles are not supported under this platform.
1260
1261         @see GetStyle(), wxTextAttr
1262     */
1263     bool SetStyle(long start, long end, const wxTextAttr& style);
1264
1265     /**
1266         Sets the text value and marks the control as not-modified (which means that
1267         IsModified() would return @false immediately
1268         after the call to SetValue).
1269         Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
1270         event.
1271         This function is deprecated and should not be used in new code. Please use the
1272         ChangeValue() function instead.
1273
1274         @param value
1275             The new value to set. It may contain newline characters if the text control
1276         is multi-line.
1277     */
1278     virtual void SetValue(const wxString& value);
1279
1280     /**
1281         Makes the line containing the given position visible.
1282
1283         @param pos
1284             The position that should be visible.
1285     */
1286     void ShowPosition(long pos);
1287
1288     /**
1289         If there is an undo facility and the last operation can be undone, undoes the
1290         last operation. Does nothing
1291         if there is no undo facility.
1292     */
1293     virtual void Undo();
1294
1295     /**
1296         Writes the text into the text control at the current insertion position.
1297
1298         @param text
1299             Text to write to the text control.
1300
1301         @remarks Newlines in the text string are the only control characters
1302                  allowed, and they will cause appropriate line breaks.
1303                  See () and AppendText() for more
1304                  convenient ways of writing to the window.
1305     */
1306     void WriteText(const wxString& text);
1307
1308     /**
1309         Converts the given zero based column and line number to a position.
1310
1311         @param x
1312             The column number.
1313         @param y
1314             The line number.
1315
1316         @returns The position value, or -1 if x or y was invalid.
1317     */
1318     long XYToPosition(long x, long y);
1319
1320     //@{
1321     /**
1322         Operator definitions for appending to a text control, for example:
1323     */
1324     wxTextCtrl operator(const wxString& s);
1325     wxTextCtrl operator(int i);
1326     wxTextCtrl operator(long i);
1327     wxTextCtrl operator(float f);
1328     wxTextCtrl operator(double d);
1329     wxTextCtrl operator(char c);
1330     //@}
1331 };
1332
1333
1334
1335 /**
1336     @class wxStreamToTextRedirector
1337     @wxheader{textctrl.h}
1338
1339     This class can be used to (temporarily) redirect all output sent to a C++
1340     ostream object to a wxTextCtrl instead.
1341
1342     @b NB: Some compilers and/or build configurations don't support multiply
1343     inheriting wxTextCtrl from @c std::streambuf in which
1344     case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
1345     option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
1346     specify @c --enable-std_iostreams switch when running configure for this.
1347
1348     Example of usage:
1349
1350     @code
1351     using namespace std;
1352
1353       wxTextCtrl *text = new wxTextCtrl(...);
1354
1355       {
1356         wxStreamToTextRedirector redirect(text);
1357
1358         // this goes to the text control
1359         cout  "Hello, text!"  endl;
1360       }
1361
1362       // this goes somewhere else, presumably to stdout
1363       cout  "Hello, console!"  endl;
1364     @endcode
1365
1366
1367     @library{wxcore}
1368     @category{logging}
1369
1370     @see wxTextCtrl
1371 */
1372 class wxStreamToTextRedirector
1373 {
1374 public:
1375     /**
1376         The constructor starts redirecting output sent to @a ostr or @e cout for
1377         the default parameter value to the text control @e text.
1378
1379         @param text
1380             The text control to append output too, must be non-@NULL
1381         @param ostr
1382             The C++ stream to redirect, cout is used if it is @NULL
1383     */
1384     wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
1385
1386     /**
1387         When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1388         and any output sent to the C++ ostream which had been specified at the time of
1389         the object construction will go to its original destination.
1390     */
1391     ~wxStreamToTextRedirector();
1392 };
1393