interface/textctrl.h

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