X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9c4cb6116779e9fc7bcb7009ef0aa6047d2f8874..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/textctrl.h?ds=sidebyside diff --git a/interface/wx/textctrl.h b/interface/wx/textctrl.h index aa8bfad77a..98dd83dd97 100644 --- a/interface/wx/textctrl.h +++ b/interface/wx/textctrl.h @@ -3,13 +3,66 @@ // Purpose: interface of wxTextAttr // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + wxTextCtrl style flags +*/ +#define wxTE_NO_VSCROLL 0x0002 + +#define wxTE_READONLY 0x0010 +#define wxTE_MULTILINE 0x0020 +#define wxTE_PROCESS_TAB 0x0040 + +// alignment flags +#define wxTE_LEFT 0x0000 // 0x0000 +#define wxTE_CENTER wxALIGN_CENTER_HORIZONTAL // 0x0100 +#define wxTE_RIGHT wxALIGN_RIGHT // 0x0200 +#define wxTE_CENTRE wxTE_CENTER + +// this style means to use RICHEDIT control and does something only under wxMSW +// and Win32 and is silently ignored under all other platforms +#define wxTE_RICH 0x0080 + +#define wxTE_PROCESS_ENTER 0x0400 +#define wxTE_PASSWORD 0x0800 + +// automatically detect the URLs and generate the events when mouse is +// moved/clicked over an URL +// +// this is for Win32 richedit and wxGTK2 multiline controls only so far +#define wxTE_AUTO_URL 0x1000 + +// by default, the Windows text control doesn't show the selection when it +// doesn't have focus - use this style to force it to always show it +#define wxTE_NOHIDESEL 0x2000 + +// use wxHSCROLL to not wrap text at all, wxTE_CHARWRAP to wrap it at any +// position and wxTE_WORDWRAP to wrap at words boundary +// +// if no wrapping style is given at all, the control wraps at word boundary +#define wxTE_DONTWRAP wxHSCROLL +#define wxTE_CHARWRAP 0x4000 // wrap at any position +#define wxTE_WORDWRAP 0x0001 // wrap only at words boundaries +#define wxTE_BESTWRAP 0x0000 // this is the default + +// force using RichEdit version 2.0 or 3.0 instead of 1.0 (default) for +// wxTE_RICH controls - can be used together with or instead of wxTE_RICH +#define wxTE_RICH2 0x8000 + + +#define wxTEXT_TYPE_ANY 0 + + +/** + wxTextCoord is a line or row number +*/ +typedef long wxTextCoord; /** - The following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment. + One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment. */ enum wxTextAttrAlignment { @@ -32,56 +85,79 @@ 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_POINT_SIZE = 0x00000008, + wxTEXT_ATTR_FONT_PIXEL_SIZE = 0x10000000, wxTEXT_ATTR_FONT_WEIGHT = 0x00000010, wxTEXT_ATTR_FONT_ITALIC = 0x00000020, wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040, + wxTEXT_ATTR_FONT_STRIKETHROUGH = 0x08000000, wxTEXT_ATTR_FONT_ENCODING = 0x02000000, wxTEXT_ATTR_FONT_FAMILY = 0x04000000, + + wxTEXT_ATTR_FONT_SIZE = \ + ( wxTEXT_ATTR_FONT_POINT_SIZE | wxTEXT_ATTR_FONT_PIXEL_SIZE ), + /** + 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_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_STRIKETHROUGH | 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, /** - Character and paragraph combined styles + 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_STYLE|wxTEXT_ATTR_BULLET_NUMBER|wxTEXT_ATTR_BULLET_TEXT|wxTEXT_ATTR_BULLET_NAME|\ - wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL), + 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 + Styles for wxTextAttr::SetBulletStyle. They can be combined together as a bitlist. */ enum wxTextAttrBulletStyle { @@ -103,13 +179,16 @@ enum wxTextAttrBulletStyle wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT = 0x00000000, wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT = 0x00001000, - wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000 + wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000, + + wxTEXT_ATTR_BULLET_STYLE_CONTINUATION = 0x00004000 }; /** - Styles for wxTextAttr::SetTextEffects(). + 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. + Of these, only wxTEXT_ATTR_EFFECT_CAPITALS, wxTEXT_ATTR_EFFECT_STRIKETHROUGH, + wxTEXT_ATTR_EFFECT_SUPERSCRIPT and wxTEXT_ATTR_EFFECT_SUBSCRIPT are implemented. */ enum wxTextAttrEffects { @@ -127,7 +206,7 @@ enum wxTextAttrEffects }; /** - Line spacing values; see wxTextAttr::SetLineSpacing(). + Convenience line spacing values; see wxTextAttr::SetLineSpacing(). */ enum wxTextAttrLineSpacing { @@ -203,9 +282,33 @@ public: const wxTextAttr* compareWith = NULL); /** - Creates a font from the font attributes. + Copies all defined/valid properties from overlay to current object. */ - wxFont CreateFont() const; + 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); + + + /** + Partial equality test. If @a weakTest is @true, attributes of this object do not + have to be present if those attributes of @a attr are present. If @a weakTest is + @false, the function will fail if an attribute is present in @a attr but not + in this object. + */ + bool EqPartial(const wxTextAttr& attr, bool weakTest = true) const; + + /** + @name GetXXX functions + */ + + //@{ /** Returns the alignment flags. @@ -299,7 +402,7 @@ public: /** Returns the font family. */ - int GetFontFamily() const; + wxFontFamily GetFontFamily() const; /** Returns the font size in points. @@ -309,7 +412,7 @@ public: /** Returns the font style. */ - int GetFontStyle() const; + wxFontStyle GetFontStyle() const; /** Returns @true if the font is underlined. @@ -319,7 +422,7 @@ public: /** Returns the font weight. */ - int GetFontWeight() const; + wxFontWeight GetFontWeight() const; /** Returns the left indent in tenths of a millimetre. @@ -400,6 +503,16 @@ public: */ const wxString& GetURL() const; + //@} + + + + /** + @name HasXXX and IsXXX functions + */ + + //@{ + /** Returns @true if the attribute object specifies alignment. */ @@ -468,10 +581,20 @@ public: bool HasFontItalic() const; /** - Returns @true if the attribute object specifies a font point size. + Returns @true if the attribute object specifies a font point or pixel size. */ bool HasFontSize() const; + /** + Returns @true if the attribute object specifies a font point size. + */ + bool HasFontPointSize() const; + + /** + Returns @true if the attribute object specifies a font pixel size. + */ + bool HasFontPixelSize() const; + /** Returns @true if the attribute object specifies either underlining or no underlining. @@ -568,19 +691,14 @@ public: */ bool IsParagraphStyle() 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. + @name SetXXX functions + */ - 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); + //@{ /** Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values. @@ -644,7 +762,7 @@ public: Sets the attributes for the given font. Note that wxTextAttr does not store an actual wxFont object. */ - void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT); + void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT & ~wxTEXT_ATTR_FONT_PIXEL_SIZE); /** Sets the font encoding. @@ -659,17 +777,27 @@ public: /** Sets the font family. */ - void SetFontFamily(int family); + void SetFontFamily(wxFontFamily family); /** Sets the font size in points. */ void SetFontSize(int pointSize); + /** + Sets the font size in points. + */ + void SetFontPointSize(int pointSize); + + /** + Sets the font size in pixels. + */ + void SetFontPixelSize(int pixelSize); + /** Sets the font style (normal, italic or slanted). */ - void SetFontStyle(int fontStyle); + void SetFontStyle(wxFontStyle fontStyle); /** Sets the font underlining. @@ -679,7 +807,7 @@ 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. @@ -752,7 +880,7 @@ public: void SetTabs(const wxArrayInt& tabs); /** - Sets the text foreground colout. + Sets the text foreground colour. */ void SetTextColour(const wxColour& colText); @@ -768,8 +896,8 @@ public: Sets the text effects, a bit list of styles. The ::wxTextAttrEffects enumeration values can be used. - Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH - are implemented. + Of these, only wxTEXT_ATTR_EFFECT_CAPITALS, wxTEXT_ATTR_EFFECT_STRIKETHROUGH, + wxTEXT_ATTR_EFFECT_SUPERSCRIPT and wxTEXT_ATTR_EFFECT_SUBSCRIPT 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 @@ -788,10 +916,13 @@ public: */ void SetURL(const wxString& url); + //@} + + /** Assignment from a wxTextAttr object. */ - void operator operator=(const wxTextAttr& attr); + void operator=(const wxTextAttr& attr); }; @@ -800,20 +931,25 @@ public: 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_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} @@ -995,16 +1131,16 @@ public: wxID_REDO. The associated UI update events are also processed automatically, when the control has the focus. - @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_TEXT 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 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_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)} @@ -1017,11 +1153,12 @@ public: @library{wxcore} @category{ctrl} - @appearance{textctrl.png} + @appearance{textctrl} @see wxTextCtrl::Create, wxValidator */ -class wxTextCtrl : public wxControl +class wxTextCtrl : public wxControl, + public wxTextEntry { public: /** @@ -1072,123 +1209,6 @@ public: */ virtual ~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() - */ - virtual 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() - */ - virtual 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() - */ - virtual bool AutoCompleteFileNames(); - - /** - Returns @true if the selection can be copied to the clipboard. - */ - virtual bool CanCopy() const; - - /** - Returns @true if the selection can be cut to the clipboard. - */ - virtual bool CanCut() const; - - /** - 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() const; - - /** - Returns @true if there is a redo facility available and the last - operation can be redone. - */ - virtual bool CanRedo() const; - - /** - Returns @true if there is an undo facility available and the last - operation can be undone. - */ - virtual bool CanUndo() const; - - /** - Sets the new text control value. - - It also marks the control as not-modified which means that IsModified() - would return @false immediately after the call to SetValue(). - - The insertion point is set to the start of the control (i.e. position - 0) by this function. - - This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED - event but otherwise is identical to SetValue(). - - See @ref overview_eventhandling_prog 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(); - /** Creates the text control for two-step construction. @@ -1203,11 +1223,6 @@ public: const wxValidator& validator = wxDefaultValidator, const wxString& name = wxTextCtrlNameStr); - /** - Copies the selected text to the clipboard and removes the selection. - */ - virtual void Cut(); - /** Resets the internal modified flag as if the current changes had been saved. @@ -1215,7 +1230,7 @@ public: 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 @@ -1234,35 +1249,6 @@ public: */ virtual 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 @c "GetValue().Length()" (but notice that the latter - equality is not necessarily true for multiline edit controls which may - use multiple new line characters). - - The following code snippet safely returns the character at the insertion - point or the zero character if the point is at the end of the control. - - @code - char GetCurrentChar(wxTextCtrl *tc) { - if (tc->GetInsertionPoint() == tc->GetLastPosition()) - return '\0'; - return tc->GetValue[tc->GetInsertionPoint()]; - } - @endcode - */ - 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; - /** Gets the length of the specified line, not including any trailing newline character(s). @@ -1290,59 +1276,18 @@ public: /** Returns the number of lines in the text control buffer. + The returned number is the number of logical lines, i.e. just the count + of the number of newline characters in the control + 1, for wxGTK and + wxOSX/Cocoa ports while it is the number of physical lines, i.e. the + count of lines actually shown in the control, in wxMSW and wxOSX/Carbon. + Because of this discrepancy, it is not recommended to use this function. + @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 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. - */ - virtual wxString GetStringSelection() const; - /** Returns the style at this position in the text control. @@ -1356,49 +1301,47 @@ public: */ virtual 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. - */ - virtual wxString GetValue() const; - + //@{ /** 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(). - */ - virtual 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 - */ - virtual bool IsEmpty() const; + wxTextCoord *col, + wxTextCoord *row) const; + //@} /** Returns @true if the text has been modified by user. @@ -1457,11 +1400,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. @@ -1476,47 +1414,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() */ 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. - - Does nothing if there is no redo facility. - */ - virtual void Redo(); - - /** - Removes the text starting at the first given position up to - (but not including) the character at the last position. + Converts given text position to client coordinates in pixels. - This function puts the current insertion point position at @a to as a - side effect. + This function allows to find where is the character at the given + position displayed in the text control. - @param from - The first position. - @param to - The last position. - */ - virtual void Remove(long from, long to); + @onlyfor{wxmsw,wxgtk}. Additionally, wxGTK only implements this method + for multiline controls and ::wxDefaultPosition is always returned for + the single line ones. - /** - Replaces the text starting at the first position up to - (but not including) the character at the last position with the given text. + @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. - This function puts the current insertion point position at @a to as a - side effect. + @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. @@ -1556,53 +1483,6 @@ public: */ virtual 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(bool editable); - - /** - Sets the insertion point at the given position. - - @param pos - Position to set, in the range from 0 to GetLastPosition() inclusive. - */ - 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); - /** Marks the control as being modified by the user or not. @@ -1610,31 +1490,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. - - Notice that the insertion point will be moved to @a from by this - function. - - @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. @@ -1656,25 +1511,6 @@ public: */ virtual bool SetStyle(long start, long end, const wxTextAttr& style); - /** - Sets the new text control value. - - It also marks the control as not-modified which means that IsModified() - would return @false immediately after the call to SetValue(). - - The insertion point is set to the start of the control (i.e. position - 0) by this function. - - Note that, unlike most other functions changing the controls values, - 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); - /** Makes the line containing the given position visible. @@ -1683,32 +1519,6 @@ public: */ virtual 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 operator<<() and AppendText() for more convenient ways of - writing to the window. - After the write operation, the insertion point will be at the end - of the inserted text, so subsequent write operations will be appended. - To append text after the user may have interacted with the control, - call wxTextCtrl::SetInsertionPointEnd() before writing. - */ - virtual void WriteText(const wxString& text); - /** Converts the given zero based column and line number to a position. @@ -1747,6 +1557,33 @@ public: +wxEventType wxEVT_TEXT; +wxEventType wxEVT_TEXT_ENTER; +wxEventType wxEVT_TEXT_URL; +wxEventType wxEVT_TEXT_MAXLEN; + + +class wxTextUrlEvent : public wxCommandEvent +{ +public: + wxTextUrlEvent(int winid, const wxMouseEvent& evtMouse, + long start, long end); + + wxTextUrlEvent(const wxTextUrlEvent& event); + + // get the mouse event which happened over the URL + const wxMouseEvent& GetMouseEvent() const; + + // get the start of the URL + long GetURLStart() const; + + // get the end of the URL + long GetURLEnd() const; + + virtual wxEvent *Clone() const; +}; + + /** @class wxStreamToTextRedirector