X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/textctrl.h diff --git a/interface/wx/textctrl.h b/interface/wx/textctrl.h index e72d531484..6dfd914320 100644 --- a/interface/wx/textctrl.h +++ b/interface/wx/textctrl.h @@ -3,9 +3,185 @@ // Purpose: interface of wxTextAttr // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment. +*/ +enum wxTextAttrAlignment +{ + wxTEXT_ALIGNMENT_DEFAULT, + wxTEXT_ALIGNMENT_LEFT, + wxTEXT_ALIGNMENT_CENTRE, + wxTEXT_ALIGNMENT_CENTER = wxTEXT_ALIGNMENT_CENTRE, + wxTEXT_ALIGNMENT_RIGHT, + + /** wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. + In future justification may be supported when printing or previewing, only. */ + wxTEXT_ALIGNMENT_JUSTIFIED +}; + +/** + The following values are passed in a bitlist to wxTextAttr::SetFlags() to + determine what attributes will be considered when setting the attributes for a text control. +*/ +enum wxTextAttrFlags +{ + wxTEXT_ATTR_TEXT_COLOUR = 0x00000001, + wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002, + + wxTEXT_ATTR_FONT_FACE = 0x00000004, + wxTEXT_ATTR_FONT_SIZE = 0x00000008, + wxTEXT_ATTR_FONT_WEIGHT = 0x00000010, + wxTEXT_ATTR_FONT_ITALIC = 0x00000020, + wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040, + wxTEXT_ATTR_FONT_ENCODING = 0x02000000, + wxTEXT_ATTR_FONT_FAMILY = 0x04000000, + + /** + Defined as the combination of all @c wxTEXT_ATTR_FONT_* values above. + */ + wxTEXT_ATTR_FONT = \ + ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \ + wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING | wxTEXT_ATTR_FONT_FAMILY ), + + wxTEXT_ATTR_ALIGNMENT = 0x00000080, + wxTEXT_ATTR_LEFT_INDENT = 0x00000100, + wxTEXT_ATTR_RIGHT_INDENT = 0x00000200, + wxTEXT_ATTR_TABS = 0x00000400, + wxTEXT_ATTR_PARA_SPACING_AFTER = 0x00000800, + wxTEXT_ATTR_PARA_SPACING_BEFORE = 0x00001000, + wxTEXT_ATTR_LINE_SPACING = 0x00002000, + wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000, + wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000, + wxTEXT_ATTR_LIST_STYLE_NAME = 0x00010000, + + wxTEXT_ATTR_BULLET_STYLE = 0x00020000, + wxTEXT_ATTR_BULLET_NUMBER = 0x00040000, + wxTEXT_ATTR_BULLET_TEXT = 0x00080000, + wxTEXT_ATTR_BULLET_NAME = 0x00100000, + + /** + Defined as the combination of all @c wxTEXT_ATTR_BULLET_* values above. + */ + wxTEXT_ATTR_BULLET = \ + ( wxTEXT_ATTR_BULLET_STYLE | wxTEXT_ATTR_BULLET_NUMBER | wxTEXT_ATTR_BULLET_TEXT | \ + wxTEXT_ATTR_BULLET_NAME ), + + wxTEXT_ATTR_URL = 0x00200000, + wxTEXT_ATTR_PAGE_BREAK = 0x00400000, + wxTEXT_ATTR_EFFECTS = 0x00800000, + wxTEXT_ATTR_OUTLINE_LEVEL = 0x01000000, + + /** + Combines the styles @c wxTEXT_ATTR_FONT, @c wxTEXT_ATTR_EFFECTS, @c wxTEXT_ATTR_BACKGROUND_COLOUR, + @c wxTEXT_ATTR_TEXT_COLOUR, @c wxTEXT_ATTR_CHARACTER_STYLE_NAME, @c wxTEXT_ATTR_URL. + */ + + wxTEXT_ATTR_CHARACTER = \ + (wxTEXT_ATTR_FONT|wxTEXT_ATTR_EFFECTS| \ + wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL), + + /** + Combines all the styles regarding text paragraphs. + */ + wxTEXT_ATTR_PARAGRAPH = \ + (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\ + wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\ + wxTEXT_ATTR_BULLET|wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL), + + /** + Combines all previous values. + */ + wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH) +}; + +/** + Styles for wxTextAttr::SetBulletStyle. They can be combined together as a bitlist. +*/ +enum wxTextAttrBulletStyle +{ + wxTEXT_ATTR_BULLET_STYLE_NONE = 0x00000000, + wxTEXT_ATTR_BULLET_STYLE_ARABIC = 0x00000001, + wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER = 0x00000002, + wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER = 0x00000004, + wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER = 0x00000008, + wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER = 0x00000010, + wxTEXT_ATTR_BULLET_STYLE_SYMBOL = 0x00000020, + + /** wxTEXT_ATTR_BULLET_STYLE_BITMAP is unimplemented. */ + wxTEXT_ATTR_BULLET_STYLE_BITMAP = 0x00000040, + wxTEXT_ATTR_BULLET_STYLE_PARENTHESES = 0x00000080, + wxTEXT_ATTR_BULLET_STYLE_PERIOD = 0x00000100, + wxTEXT_ATTR_BULLET_STYLE_STANDARD = 0x00000200, + wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS = 0x00000400, + wxTEXT_ATTR_BULLET_STYLE_OUTLINE = 0x00000800, + + wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT = 0x00000000, + wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT = 0x00001000, + wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000 +}; + +/** + Styles for wxTextAttr::SetTextEffects(). They can be combined together as a bitlist. + + Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented. +*/ +enum wxTextAttrEffects +{ + wxTEXT_ATTR_EFFECT_NONE = 0x00000000, + wxTEXT_ATTR_EFFECT_CAPITALS = 0x00000001, + wxTEXT_ATTR_EFFECT_SMALL_CAPITALS = 0x00000002, + wxTEXT_ATTR_EFFECT_STRIKETHROUGH = 0x00000004, + wxTEXT_ATTR_EFFECT_DOUBLE_STRIKETHROUGH = 0x00000008, + wxTEXT_ATTR_EFFECT_SHADOW = 0x00000010, + wxTEXT_ATTR_EFFECT_EMBOSS = 0x00000020, + wxTEXT_ATTR_EFFECT_OUTLINE = 0x00000040, + wxTEXT_ATTR_EFFECT_ENGRAVE = 0x00000080, + wxTEXT_ATTR_EFFECT_SUPERSCRIPT = 0x00000100, + wxTEXT_ATTR_EFFECT_SUBSCRIPT = 0x00000200 +}; + +/** + Convenience line spacing values; see wxTextAttr::SetLineSpacing(). +*/ +enum wxTextAttrLineSpacing +{ + wxTEXT_ATTR_LINE_SPACING_NORMAL = 10, + wxTEXT_ATTR_LINE_SPACING_HALF = 15, + wxTEXT_ATTR_LINE_SPACING_TWICE = 20 +}; + + +/** + Describes the possible return values of wxTextCtrl::HitTest(). + + The element names correspond to the relationship between the point asked + for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point + is before (leftward or upward) it and so on. + */ +enum wxTextCtrlHitTestResult +{ + /// Indicates that wxTextCtrl::HitTest() is not implemented on this + /// platform. + wxTE_HT_UNKNOWN = -2, + + /// The point is before the character returned. + wxTE_HT_BEFORE, + + /// The point is directly on the character returned. + wxTE_HT_ON_TEXT, + + /// The point is below the last line of the control. + wxTE_HT_BELOW, + + /// The point is beyond the end of line containing the character returned. + wxTE_HT_BEYOND +}; + + /** @class wxTextAttr @@ -13,8 +189,8 @@ for a range of text in a wxTextCtrl or wxRichTextCtrl. When setting up a wxTextAttr object, pass a bitlist mask to - wxTextAttr::SetFlags to indicate which style elements should be changed. As - a convenience, when you call a setter such as SetFont, the relevant bit + wxTextAttr::SetFlags() to indicate which style elements should be changed. + As a convenience, when you call a setter such as SetFont, the relevant bit will be set. @library{wxcore} @@ -49,39 +225,61 @@ public: */ wxFont CreateFont() const; + /** + Copies all defined/valid properties from overlay to current object. + */ + void Merge(const wxTextAttr& overlay); + + /** + Creates a new @c wxTextAttr which is a merge of @a base and @a overlay. + + Properties defined in @a overlay take precedence over those in @a base. + Properties undefined/invalid in both are undefined in the result. + */ + static wxTextAttr Merge(const wxTextAttr& base, + const wxTextAttr& overlay); + + + /** + @name GetXXX functions + */ + + //@{ + /** Returns the alignment flags. - See SetAlignment() for a list of available styles. + See ::wxTextAttrAlignment for a list of available styles. */ wxTextAttrAlignment GetAlignment() const; /** Returns the background colour. */ - const wxColour GetBackgroundColour() const; + const wxColour& GetBackgroundColour() const; /** - Returns a string containing the name of the font associated with the bullet - symbol. + Returns a string containing the name of the font associated with the bullet symbol. Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. */ - const wxString GetBulletFont() const; + const wxString& GetBulletFont() const; /** Returns the standard bullet name, applicable if the bullet style is wxTEXT_ATTR_BULLET_STYLE_STANDARD. + Currently the following standard bullet names are supported: - @c standard/circle - @c standard/square - @c standard/diamond - @c standard/triangle + - @c standard/circle + - @c standard/square + - @c standard/diamond + - @c standard/triangle + + @note For wxRichTextCtrl users only: if you wish your rich text controls to support - further bullet graphics, you can derive a - class from wxRichTextRenderer or wxRichTextStdRenderer, override @c - DrawStandardBullet and @c EnumerateStandardBulletNames, and - set an instance of the class using wxRichTextBuffer::SetRenderer. + further bullet graphics, you can derive a class from wxRichTextRenderer or + wxRichTextStdRenderer, override @c DrawStandardBullet and @c EnumerateStandardBulletNames, + and set an instance of the class using wxRichTextBuffer::SetRenderer. */ - const wxString GetBulletName() const; + const wxString& GetBulletName() const; /** Returns the bullet number. @@ -90,7 +288,7 @@ public: /** Returns the bullet style. - See SetBulletStyle() for a list of available styles. + See ::wxTextAttrBulletStyle for a list of available styles. */ int GetBulletStyle() const; @@ -98,12 +296,12 @@ public: Returns the bullet text, which could be a symbol, or (for example) cached outline text. */ - const wxString GetBulletText() const; + const wxString& GetBulletText() const; /** Returns the name of the character style. */ - const wxString GetCharacterStyleName() const; + const wxString& GetCharacterStyleName() const; /** Returns flags indicating which attributes are applicable. @@ -113,10 +311,10 @@ public: /** Creates and returns a font specified by the font attributes in the wxTextAttr - object. Note that - wxTextAttr does not store a wxFont object, so this is only a temporary font. - For greater - efficiency, access the font attributes directly. + object. Note that wxTextAttr does not store a wxFont object, so this is only + a temporary font. + + For greater efficiency, access the font attributes directly. */ wxFont GetFont() const; @@ -135,7 +333,12 @@ public: /** Returns the font face name. */ - const wxString GetFontFaceName() const; + const wxString& GetFontFaceName() const; + + /** + Returns the font family. + */ + wxFontFamily GetFontFamily() const; /** Returns the font size in points. @@ -145,7 +348,7 @@ public: /** Returns the font style. */ - int GetFontStyle() const; + wxFontStyle GetFontStyle() const; /** Returns @true if the font is underlined. @@ -155,7 +358,7 @@ public: /** Returns the font weight. */ - int GetFontWeight() const; + wxFontWeight GetFontWeight() const; /** Returns the left indent in tenths of a millimetre. @@ -168,20 +371,19 @@ public: long GetLeftSubIndent() const; /** - Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL, - wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE. + Returns the line spacing value, one of ::wxTextAttrLineSpacing values. */ int GetLineSpacing() const; /** Returns the name of the list style. */ - const wxString GetListStyleName() const; + const wxString& GetListStyleName() const; /** Returns the outline level. */ - bool GetOutlineLevel() const; + int GetOutlineLevel() const; /** Returns the space in tenths of a millimeter after the paragraph. @@ -196,7 +398,7 @@ public: /** Returns the name of the paragraph style. */ - const wxString GetParagraphStyleName() const; + const wxString& GetParagraphStyleName() const; /** Returns the right indent in tenths of a millimeter. @@ -204,37 +406,48 @@ public: long GetRightIndent() const; /** - Returns an array of tab stops, each expressed in tenths of a millimeter. Each - stop - is measured from the left margin and therefore each value must be larger than - the last. + Returns an array of tab stops, each expressed in tenths of a millimeter. + + Each stop is measured from the left margin and therefore each value must + be larger than the last. */ - const wxArrayInt GetTabs() const; + const wxArrayInt& GetTabs() const; /** Returns the text foreground colour. */ - const wxColour GetTextColour() const; + const wxColour& GetTextColour() const; /** - Returns the text effect bits of interest. See SetFlags() for further - information. + Returns the text effect bits of interest. + See SetFlags() for further information. */ int GetTextEffectFlags() const; /** - Returns the text effects, a bit list of styles. See SetTextEffects() for - details. + Returns the text effects, a bit list of styles. + See SetTextEffects() for details. */ int GetTextEffects() const; /** - Returns the URL for the content. Content with wxTEXT_ATTR_URL style - causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl - generates - a wxTextUrlEvent when the content is clicked. + Returns the URL for the content. + + Content with @a wxTEXT_ATTR_URL style causes wxRichTextCtrl to show a + hand cursor over it, and wxRichTextCtrl generates a wxTextUrlEvent + when the content is clicked. */ - const wxString GetURL() const; + const wxString& GetURL() const; + + //@} + + + + /** + @name HasXXX and IsXXX functions + */ + + //@{ /** Returns @true if the attribute object specifies alignment. @@ -293,6 +506,11 @@ public: */ bool HasFontFaceName() const; + /** + Returns @true if the attribute object specifies a font family. + */ + bool HasFontFamily() const; + /** Returns @true if the attribute object specifies italic style. */ @@ -399,24 +617,20 @@ public: */ bool IsParagraphStyle() const; - //@{ - /** - Creates a new @c wxTextAttr which is a merge of @a base and - @a overlay. Properties defined in @a overlay take precedence over those - in @a base. Properties undefined/invalid in both are undefined in the - result. - */ - void Merge(const wxTextAttr& overlay); - static wxTextAttr Merge(const wxTextAttr& base, - const wxTextAttr& overlay); //@} + + /** + @name SetXXX functions + */ + + //@{ + /** - Sets the paragraph alignment. These are the possible values for @a alignment: + Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values. - Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification - may be supported - when printing or previewing, only. + Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. + In future justification may be supported when printing or previewing, only. */ void SetAlignment(wxTextAttrAlignment alignment); @@ -434,8 +648,9 @@ public: /** Sets the standard bullet name, applicable if the bullet style is wxTEXT_ATTR_BULLET_STYLE_STANDARD. - See GetBulletName() for a list - of supported names, and how to expand the range of supported types. + + See GetBulletName() for a list of supported names, and how + to expand the range of supported types. */ void SetBulletName(const wxString& name); @@ -445,17 +660,18 @@ public: void SetBulletNumber(int n); /** - Sets the bullet style. The following styles can be passed: + Sets the bullet style. - Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported. + The ::wxTextAttrBulletStyle enumeration values are all supported, + except for wxTEXT_ATTR_BULLET_STYLE_BITMAP. */ void SetBulletStyle(int style); /** - Sets the bullet text, which could be a symbol, or (for example) cached outline - text. + Sets the bullet text, which could be a symbol, or (for example) cached + outline text. */ - void SetBulletText(const wxString text); + void SetBulletText(const wxString& text); /** Sets the character style name. @@ -463,16 +679,16 @@ public: void SetCharacterStyleName(const wxString& name); /** - Sets the flags determining which styles are being specified. The following - flags can be passed in a bitlist: + Sets the flags determining which styles are being specified. + The ::wxTextAttrFlags values can be passed in a bitlist. */ void SetFlags(long flags); /** - Sets the attributes for the given font. Note that wxTextAttr does not store an - actual wxFont object. + Sets the attributes for the given font. + Note that wxTextAttr does not store an actual wxFont object. */ - void SetFont(const wxFont& font); + void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT); /** Sets the font encoding. @@ -480,10 +696,15 @@ public: void SetFontEncoding(wxFontEncoding encoding); /** - Sets the paragraph alignment. + Sets the font face name. */ void SetFontFaceName(const wxString& faceName); + /** + Sets the font family. + */ + void SetFontFamily(wxFontFamily family); + /** Sets the font size in points. */ @@ -492,7 +713,7 @@ public: /** Sets the font style (normal, italic or slanted). */ - void SetFontStyle(int fontStyle); + void SetFontStyle(wxFontStyle fontStyle); /** Sets the font underlining. @@ -502,31 +723,30 @@ public: /** Sets the font weight. */ - void SetFontWeight(int fontWeight); + void SetFontWeight(wxFontWeight fontWeight); /** Sets the left indent and left subindent in tenths of a millimetre. The sub-indent is an offset from the left of the paragraph, and is used for all - but the - first line in a paragraph. A positive value will cause the first line to appear - to the left + but the first line in a paragraph. + + A positive value will cause the first line to appear to the left of the subsequent lines, and a negative value will cause the first line to be - indented - relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the + indented relative to the subsequent lines. + + wxRichTextBuffer uses indentation to render a bulleted item. + The left indent is the distance between the margin and the bullet. + The content of the paragraph, including the first line, starts + at leftMargin + leftSubIndent. + So the distance between the left edge of the bullet and the left of the actual paragraph is leftSubIndent. */ void SetLeftIndent(int indent, int subIndent = 0); /** Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: + 15 means 1.5 spacing, and 20 means double spacing. + The ::wxTextAttrLineSpacing values are defined for convenience. */ void SetLineSpacing(int spacing); @@ -536,11 +756,10 @@ public: void SetListStyleName(const wxString& name); /** - Specifies the outline level. Zero represents normal text. At present, the - outline level is - not used, but may be used in future for determining list levels and for - applications - that need to store document structure information. + Specifies the outline level. Zero represents normal text. + At present, the outline level is not used, but may be used in future for + determining list levels and for applications that need to store document + structure information. */ void SetOutlineLevel(int level); @@ -577,93 +796,76 @@ public: void SetTabs(const wxArrayInt& tabs); /** - Sets the text foreground colout. + Sets the text foreground colour. */ void SetTextColour(const wxColour& colText); /** - Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS - to SetFlags(). + Sets the text effect bits of interest. + + You should also pass wxTEXT_ATTR_EFFECTS to SetFlags(). See SetFlags() for further information. */ void SetTextEffectFlags(int flags); /** Sets the text effects, a bit list of styles. - The following styles can be passed: + The ::wxTextAttrEffects enumeration values can be used. Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented. + wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case - of the actual buffer - text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text. + of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws + a line through text. + To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call - SetTextEffectFlags() with the styles (taken from the - above set) that you are interested in setting. + SetTextEffectFlags() with the styles (taken from the above set) that you + are interested in setting. */ void SetTextEffects(int effects); /** Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this - style - causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl - generates - a wxTextUrlEvent when the content is clicked. + style causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl + generates a wxTextUrlEvent when the content is clicked. */ void SetURL(const wxString& url); + //@} + + /** Assignment from a wxTextAttr object. */ void operator operator=(const wxTextAttr& attr); }; -/** - Describes the possible return values of wxTextCtrl::HitTest(). - - The element names correspond to the relationship between the point asked - for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point - is before (leftward or upward) it and so on. - */ -enum wxTextCtrlHitTestResult -{ - /// Indicates that wxTextCtrl::HitTest() is not implemented on this - /// platform. - wxTE_HT_UNKNOWN = -2, - - /// The point is before the character returned. - wxTE_HT_BEFORE, - - /// The point is directly on the character returned. - wxTE_HT_ON_TEXT, - - /// The point is below the last line of the control. - wxTE_HT_BELOW, - - /// The point is beyond the end of line containing the character returned. - wxTE_HT_BEYOND -}; - /** @class wxTextCtrl A text control allows text to be displayed and edited. - It may be single line or multi-line. + It may be single line or multi-line. Notice that a lot of methods of the + text controls are found in the base wxTextEntry class which is a common + base class for wxTextCtrl and other controls using a single line text entry + field (e.g. wxComboBox). @beginStyleTable @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER + The control will generate the event @c wxEVT_COMMAND_TEXT_ENTER (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls). @style{wxTE_PROCESS_TAB} - The control will receive wxEVT_CHAR events for TAB pressed - + The control will receive @c wxEVT_CHAR events for TAB pressed - normally, TAB is used for passing to the next control in a dialog instead. For the control created with this style, you can still use Ctrl-Enter to pass to the next control from the keyboard. @style{wxTE_MULTILINE} - The text control allows multiple lines. + The text control allows multiple lines. If this style is not + specified, line break characters should not be used in the controls + value. @style{wxTE_PASSWORD} The text will be echoed as asterisks. @style{wxTE_READONLY} @@ -716,6 +918,11 @@ enum wxTextCtrlHitTestResult capitalized. @endStyleTable + Note that alignment styles (wxTE_LEFT, wxTE_CENTRE and wxTE_RIGHT) can be + changed dynamically after control creation on wxMSW and wxGTK. wxTE_READONLY, + wxTE_PASSWORD and wrapping styles can be dynamically changed under wxGTK but + not wxMSW. The other styles can be only set during control creation. + @section textctrl_text_format wxTextCtrl Text Format @@ -840,19 +1047,16 @@ enum wxTextCtrlHitTestResult wxID_REDO. The associated UI update events are also processed automatically, when the control has the focus. - To process input from a text control, use these event handler macros to - direct input to member functions that take a wxCommandEvent argument. - - @beginEventTable{wxCommandEvent} + @beginEventEmissionTable{wxCommandEvent} @event{EVT_TEXT(id, func)} - Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text + Respond to a @c wxEVT_COMMAND_TEXT_UPDATED event, generated when the text changes. Notice that this event will be sent when the text controls contents changes -- whether this is due to user input or comes from the - program itself (for example, if SetValue() is called); see - ChangeValue() for a function which does not send this event. This - event is however not sent during the control creation. + program itself (for example, if wxTextCtrl::SetValue() is called); see + wxTextCtrl::ChangeValue() for a function which does not send this event. + This event is however not sent during the control creation. @event{EVT_TEXT_ENTER(id, func)} - Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is + Respond to a @c wxEVT_COMMAND_TEXT_ENTER event, generated when enter is pressed in a text control which must have wxTE_PROCESS_ENTER style for this event to be generated. @event{EVT_TEXT_URL(id, func)} @@ -860,24 +1064,23 @@ enum wxTextCtrlHitTestResult wxGTK2 only currently). @event{EVT_TEXT_MAXLEN(id, func)} This event is generated when the user tries to enter more text into the - control than the limit set by SetMaxLength(), see its description. + control than the limit set by wxTextCtrl::SetMaxLength(), see its description. @endEventTable @library{wxcore} @category{ctrl} - + @appearance{textctrl.png} @see wxTextCtrl::Create, wxValidator */ -class wxTextCtrl : public wxControl +class wxTextCtrl : public wxControl, + public wxTextEntry { public: - //@{ /** - Constructor, creating and showing a text control. - @see Create() + Default ctor. */ - wxTextCtrl(); + wxTextCtrl(); /** Constructor, creating and showing a text control. @@ -899,140 +1102,28 @@ public: @param name Window name. - @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be + @remarks + The horizontal scrollbar (wxHSCROLL style flag) will only be created for multi-line text controls. Without a horizontal scrollbar, text lines that don't fit in the control's size will be - wrapped (but no newline character is inserted). Single line - controls don't have a horizontal scrollbar, the text is - automatically scrolled so that the insertion point is always - visible. + wrapped (but no newline character is inserted). + Single line controls don't have a horizontal scrollbar, the text is + automatically scrolled so that the insertion point is always visible. @see Create(), wxValidator */ wxTextCtrl(wxWindow* parent, wxWindowID id, - const wxString& value = "", + const wxString& value = wxEmptyString, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxTextCtrlNameStr); - //@} /** Destructor, destroying the text control. */ - ~wxTextCtrl(); - - /** - Appends the text to the end of the text control. - - @param text - Text to write to the text control. - - @remarks After the text is appended, the insertion point will be at the - end of the text control. If this behaviour is not desired, the - programmer should use GetInsertionPoint and SetInsertionPoint. - - @see WriteText() - */ - void AppendText(const wxString& text); - - /** - Call this function to enable auto-completion of the text typed in a - single-line text control using the given @a choices. - - Notice that currently this function is only implemented in wxGTK2 and - wxMSW ports and does nothing under the other platforms. - - @since 2.9.0 - - @return - @true if the auto-completion was enabled or @false if the operation - failed, typically because auto-completion is not supported by the - current platform. - - @see AutoCompleteFileNames() - */ - bool AutoComplete(const wxArrayString& choices); - - /** - Call this function to enable auto-completion of the text typed in a - single-line text control using all valid file system paths. - - Notice that currently this function is only implemented in wxGTK2 port - and does nothing under the other platforms. - - @since 2.9.0 - - @return - @true if the auto-completion was enabled or @false if the operation - failed, typically because auto-completion is not supported by the - current platform. - - @see AutoComplete() - */ - bool AutoCompleteFileNames(); - - /** - Returns @true if the selection can be copied to the clipboard. - */ - virtual bool CanCopy(); - - /** - Returns @true if the selection can be cut to the clipboard. - */ - virtual bool CanCut(); - - /** - Returns @true if the contents of the clipboard can be pasted into the - text control. - - On some platforms (Motif, GTK) this is an approximation and returns - @true if the control is editable, @false otherwise. - */ - virtual bool CanPaste(); - - /** - Returns @true if there is a redo facility available and the last - operation can be redone. - */ - virtual bool CanRedo(); - - /** - Returns @true if there is an undo facility available and the last - operation can be undone. - */ - virtual bool CanUndo(); - - /** - Sets the text value and marks the control as not-modified (which means - that IsModified() would return @false immediately after the call to - SetValue). - - This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED - event but otherwise is identical to SetValue(). - See @ref overview_progevent "this topic" for more information. - - @since 2.7.1 - - @param value - The new value to set. It may contain newline characters if the text - control is multi-line. - */ - virtual void ChangeValue(const wxString& value); - - /** - Clears the text in the control. - - Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED - event, i.e. its effect is identical to calling @c SetValue(""). - */ - virtual void Clear(); - - /** - Copies the selected text to the clipboard. - */ - virtual void Copy(); + virtual ~wxTextCtrl(); /** Creates the text control for two-step construction. @@ -1042,10 +1133,9 @@ public: non-default constructor. */ bool Create(wxWindow* parent, wxWindowID id, - const wxString& value = "", + const wxString& value = wxEmptyString, const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, + const wxSize& size = wxDefaultSize, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = wxTextCtrlNameStr); @@ -1058,47 +1148,27 @@ public: Resets the internal modified flag as if the current changes had been saved. */ - void DiscardEdits(); + virtual void DiscardEdits(); /** - This functions inserts into the control the character which would have + This function inserts into the control the character which would have been inserted if the given key event had occurred in the text control. - The @a event object should be the same as the one passed to @c - EVT_KEY_DOWN handler previously by wxWidgets. Please note that this - function doesn't currently work correctly for all keys under any - platform but MSW. + The @a event object should be the same as the one passed to @c EVT_KEY_DOWN + handler previously by wxWidgets. Please note that this function doesn't + currently work correctly for all keys under any platform but MSW. @return - @true if the event resulted in a change to the control, @false - otherwise. + @true if the event resulted in a change to the control, @false otherwise. */ - bool EmulateKeyPress(const wxKeyEvent& event); + virtual bool EmulateKeyPress(const wxKeyEvent& event); /** Returns the style currently used for the new text. @see SetDefaultStyle() */ - const wxTextAttr GetDefaultStyle() const; - - /** - Returns the insertion point, or cursor, position. - - This is defined as the zero based index of the character position to - the right of the insertion point. For example, if the insertion point - is at the end of the single-line text control, it is equal to both - GetLastPosition() and GetValue().length() (but notice that the latter - equality is not necessarily true for multiline edit controls which may - use multiple new line characters). - */ - virtual long GetInsertionPoint() const; - - /** - Returns the zero based index of the last position in the text control, - which is equal to the number of characters in the control. - */ - virtual wxTextPos GetLastPosition() const; + virtual const wxTextAttr& GetDefaultStyle() const; /** Gets the length of the specified line, not including any trailing @@ -1110,7 +1180,7 @@ public: @return The length of the line, or -1 if @a lineNo was invalid. */ - int GetLineLength(long lineNo) const; + virtual int GetLineLength(long lineNo) const; /** Returns the contents of a given line in the text control, not including @@ -1122,53 +1192,26 @@ public: @return The contents of the line. */ - wxString GetLineText(long lineNo) const; + virtual wxString GetLineText(long lineNo) const; /** Returns the number of lines in the text control buffer. - @remarks Note that even empty text controls have one line (where the - insertion point is), so GetNumberOfLines() never - returns 0. - */ - int GetNumberOfLines() const; - - /** - Returns the string containing the text starting in the positions - @a from and up to @a to in the control. - - The positions must have been returned by another wxTextCtrl method. - Please note that the positions in a multiline wxTextCtrl do @b not - correspond to the indices in the string returned by GetValue() because - of the different new line representations (@c CR or @c CR LF) and so - this method should be used to obtain the correct results instead of - extracting parts of the entire value. It may also be more efficient, - especially if the control contains a lot of data. - */ - virtual wxString GetRange(long from, long to) const; - - /** - Gets the current selection span. - - If the returned values are equal, there was no selection. Please note - that the indices returned may be used with the other wxTextCtrl methods - but don't necessarily represent the correct indices into the string - returned by GetValue() for multiline controls under Windows (at least,) - you should use GetStringSelection() to get the selected text. - - @param from - The returned first position. - @param to - The returned last position. - */ - virtual void GetSelection(long* from, long* to) const; - - /** - Gets the text currently selected in the control. - - If there is no selection, the returned string is empty. + @remarks + Note that even empty text controls have one line (where the + insertion point is), so GetNumberOfLines() never returns 0. + For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a + multi-line text control is calculated by actually counting newline + characters in the buffer, i.e. this function returns the number of + logical lines and doesn't depend on whether any of them are wrapped. + For all the other platforms, the number of physical lines in the + control is returned. + Also note that you may wish to avoid using functions that work with + line numbers if you are working with controls that contain large + amounts of text as this function has O(N) complexity for N being + the number of lines. */ - virtual wxString GetStringSelection(); + virtual int GetNumberOfLines() const; /** Returns the style at this position in the text control. @@ -1181,50 +1224,49 @@ public: @see SetStyle(), wxTextAttr */ - bool GetStyle(long position, wxTextAttr& style); - - /** - Gets the contents of the control. - Notice that for a multiline text control, the lines will be separated - by (Unix-style) @c \\n characters, even under Windows where they are - separated by a @c \\r\\n sequence in the native control. - */ - wxString GetValue() const; + virtual bool GetStyle(long position, wxTextAttr& style); + //@{ /** This function finds the character at the specified position expressed in pixels. + The two overloads of this method allow to find either the position of + the character, as an index into the text control contents, or its row + and column. + If the return code is not @c wxTE_HT_UNKNOWN the row and column of the - character closest to this position are returned in the @a col and @a - row parameters (unless the pointers are @NULL which is allowed). Please - note that this function is currently only implemented in wxUniv, wxMSW - and wxGTK2 ports. + character closest to this position are returned, otherwise the output + parameters are not modified. + + Please note that this function is currently only implemented in wxUniv, + wxMSW and wxGTK2 ports and always returns @c wxTE_HT_UNKNOWN in the + other ports. + + @beginWxPerlOnly + In wxPerl this function takes only the @a pt argument and + returns a 3-element list (result, col, row). + @endWxPerlOnly + + @param pt + The position of the point to check, in window device coordinates. + @param col + Receives the column of the character at the given position. May be + @NULL. + @param row + Receives the row of the character at the given position. May be + @NULL. + @param pos + Receives the position of the character at the given position. May + be @NULL. @see PositionToXY(), XYToPosition() */ + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long *pos) const; wxTextCtrlHitTestResult HitTest(const wxPoint& pt, - wxTextCoord col, - wxTextCoord row) const; - - /** - Returns @true if the controls contents may be edited by user (note that - it always can be changed by the program). - - In other words, this functions returns @true if the control hasn't been - put in read-only mode by a previous call to SetEditable(). - */ - bool IsEditable() const; - - /** - Returns @true if the control is currently empty. - - This is the same as @c GetValue().empty() but can be much more - efficient for the multiline controls containing big amounts of text. - - @since 2.7.1 - */ - bool IsEmpty() const; + wxTextCoord *col, + wxTextCoord *row) const; + //@} /** Returns @true if the text has been modified by user. @@ -1233,21 +1275,19 @@ public: @see MarkDirty() */ - bool IsModified() const; + virtual bool IsModified() const; /** - Returns @true if this is a multi line edit control and @false - otherwise. + Returns @true if this is a multi line edit control and @false otherwise. @see IsSingleLine() */ bool IsMultiLine() const; /** - Returns @true if this is a single line edit control and @false - otherwise. + Returns @true if this is a single line edit control and @false otherwise. - @see @ref IsSingleLine() IsMultiLine + @see IsSingleLine(), IsMultiLine() */ bool IsSingleLine() const; @@ -1270,7 +1310,7 @@ public: @see IsModified() */ - void MarkDirty(); + virtual void MarkDirty(); /** This event handler function implements default drag and drop behaviour, @@ -1285,11 +1325,6 @@ public: */ void OnDropFiles(wxDropFilesEvent& event); - /** - Pastes text from the clipboard to the text item. - */ - virtual void Paste(); - /** Converts given position to a zero-based column, line number pair. @@ -1304,41 +1339,36 @@ public: @true on success, @false on failure (most likely due to a too large position parameter). + @beginWxPerlOnly + In wxPerl this function takes only the @a pos argument and + returns a 2-element list (x, y). + @endWxPerlOnly + @see XYToPosition() */ - bool PositionToXY(long pos, long* x, long* y) const; + virtual bool PositionToXY(long pos, long* x, long* y) const; /** - If there is a redo facility and the last operation can be redone, - redoes the last operation. + Converts given text position to client coordinates in pixels. - Does nothing if there is no redo facility. - */ - virtual void Redo(); + This function allows to find where is the character at the given + position displayed in the text control. - /** - Removes the text starting at the first given position up to (but not - including) the character at the last position. + @onlyfor{wxmsw,wxgtk}. Additionally, wxGTK only implements this method + for multiline controls and ::wxDefaultPosition is always returned for + the single line ones. - @param from - The first position. - @param to - The last position. - */ - virtual void Remove(long from, long to); + @param pos + Text position in 0 to GetLastPosition() range (inclusive). + @return + On success returns a wxPoint which contains client coordinates for + the given position in pixels, otherwise returns ::wxDefaultPosition. - /** - Replaces the text starting at the first position up to (but not - including) the character at the last position with the given text. + @since 2.9.3 - @param from - The first position. - @param to - The last position. - @param value - The value to replace the existing text with. + @see XYToPosition(), PositionToXY() */ - virtual void Replace(long from, long to, const wxString& value); + wxPoint PositionToCoords(long pos) const; /** Saves the contents of the control in a text file. @@ -1351,7 +1381,7 @@ public: @return @true if the operation was successful, @false otherwise. */ - bool SaveFile(const wxString& filename, + bool SaveFile(const wxString& filename = wxEmptyString, int fileType = wxTEXT_TYPE_ANY); /** @@ -1361,8 +1391,9 @@ public: If either of the font, foreground, or background colour is not set in @a style, the values of the previous default style are used for them. If the previous default style didn't set them neither, the global font - or colours of the text control itself are used as fall back. However if - the @a style parameter is the default wxTextAttr, then the default + or colours of the text control itself are used as fall back. + + However if the @a style parameter is the default wxTextAttr, then the default style is just reset (instead of being combined with the new style which wouldn't change it at all). @@ -1375,52 +1406,7 @@ public: @see GetDefaultStyle() */ - bool SetDefaultStyle(const wxTextAttr& style); - - /** - Makes the text item editable or read-only, overriding the - @b wxTE_READONLY flag. - - @param editable - If @true, the control is editable. If @false, the control is - read-only. - - @see IsEditable() - */ - virtual void SetEditable(const bool editable); - - /** - Sets the insertion point at the given position. - - @param pos - Position to set. - */ - virtual void SetInsertionPoint(long pos); - - /** - Sets the insertion point at the end of the text control. - - This is equivalent to calling wxTextCtrl::SetInsertionPoint() with - wxTextCtrl::GetLastPosition() argument. - */ - virtual void SetInsertionPointEnd(); - - /** - This function sets the maximum number of characters the user can enter - into the control. - - In other words, it allows to limit the text value length to @a len not - counting the terminating @c NUL character. If @a len is 0, the - previously set max length limit, if any, is discarded and the user may - enter as much text as the underlying native text control widget - supports (typically at least 32Kb). If the user tries to enter more - characters into the text control when it already is filled up to the - maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify - the program about it (giving it the possibility to show an explanatory - message, for example) and the extra input is discarded. Note that in - wxGTK this function may only be used with single line text controls. - */ - virtual void SetMaxLength(unsigned long len); + virtual bool SetDefaultStyle(const wxTextAttr& style); /** Marks the control as being modified by the user or not. @@ -1429,28 +1415,6 @@ public: */ void SetModified(bool modified); - /** - Selects the text starting at the first position up to (but not - including) the character at the last position. - - If both parameters are equal to -1 all text in the control is selected. - - @param from - The first position. - @param to - The last position. - - @see SelectAll() - */ - virtual void SetSelection(long from, long to); - - /** - Selects all text in the control. - - @see SetSelection() - */ - virtual void SelectAll(); - /** Changes the style of the given range. @@ -1470,21 +1434,7 @@ public: @see GetStyle(), wxTextAttr */ - bool SetStyle(long start, long end, const wxTextAttr& style); - - /** - Sets the text value and marks the control as not-modified (which means - that IsModified() would return @false immediately after the call to - SetValue). - - Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED - event, to avoid this you can use ChangeValue() instead. - - @param value - The new value to set. It may contain newline characters if the text - control is multi-line. - */ - virtual void SetValue(const wxString& value); + virtual bool SetStyle(long start, long end, const wxTextAttr& style); /** Makes the line containing the given position visible. @@ -1492,27 +1442,7 @@ public: @param pos The position that should be visible. */ - void ShowPosition(long pos); - - /** - If there is an undo facility and the last operation can be undone, - undoes the last operation. - - Does nothing if there is no undo facility. - */ - virtual void Undo(); - - /** - Writes the text into the text control at the current insertion position. - - @param text - Text to write to the text control. - - @remarks Newlines in the text string are the only control characters - allowed, and they will cause appropriate line breaks. See () and - AppendText() for more convenient ways of writing to the window. - */ - void WriteText(const wxString& text); + virtual void ShowPosition(long pos); /** Converts the given zero based column and line number to a position. @@ -1525,7 +1455,7 @@ public: @return The position value, or -1 if x or y was invalid. */ - long XYToPosition(long x, long y); + virtual long XYToPosition(long x, long y) const; //@{ /** @@ -1558,31 +1488,29 @@ public: This class can be used to (temporarily) redirect all output sent to a C++ ostream object to a wxTextCtrl instead. - @note Some compilers and/or build configurations don't support multiply - inheriting wxTextCtrl from @c std::streambuf in which - case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM - option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix, - specify @c --enable-std_iostreams switch when running configure for this. + @note + Some compilers and/or build configurations don't support multiply + inheriting wxTextCtrl from @c std::streambuf in which case this class is + not compiled in. + You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your + @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams + switch when running configure for this. Example of usage: @code using namespace std; - - wxTextCtrl *text = new wxTextCtrl(...); - - { + wxTextCtrl* text = new wxTextCtrl(...); + { wxStreamToTextRedirector redirect(text); // this goes to the text control - cout "Hello, text!" endl; - } - - // this goes somewhere else, presumably to stdout - cout "Hello, console!" endl; + cout << "Hello, text!" << endl; + } + // this goes somewhere else, presumably to stdout + cout << "Hello, console!" << endl; @endcode - @library{wxcore} @category{logging} @@ -1600,7 +1528,7 @@ public: @param ostr The C++ stream to redirect, cout is used if it is @NULL */ - wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL); + wxStreamToTextRedirector(wxTextCtrl *text, ostream* ostr); /** When a wxStreamToTextRedirector object is destroyed, the redirection is ended