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