X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/63f7d5022e786be61c0226314dac98739f49a426..2e8c12bcb028f4b3a77e71e7bcc91fc8f156feaa:/interface/wx/textentry.h diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h index bec4b6a928..d31506f1c0 100644 --- a/interface/wx/textentry.h +++ b/interface/wx/textentry.h @@ -5,9 +5,16 @@ // Created: 2009-03-01 (extracted from wx/textctrl.h) // RCS-ID: $Id$ // Copyright: (c) 2009 Vadim Zeitlin -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + wxTextPos is a position in the text +*/ +typedef long wxTextPos; + + /** @class wxTextEntry @@ -21,6 +28,8 @@ @category{ctrl} @see wxTextCtrl, wxComboBox + + @since 2.9.0 */ class wxTextEntry { @@ -44,8 +53,8 @@ public: 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. + Notice that currently this function is only implemented in wxGTK2, + wxMSW and wxOSX/Cocoa ports and does nothing under the other platforms. @since 2.9.0 @@ -56,13 +65,47 @@ public: @see AutoCompleteFileNames() */ - virtual bool AutoComplete(const wxArrayString& choices); + bool AutoComplete(const wxArrayString& choices); + + /** + Enable auto-completion using the provided completer object. + + This method should be used instead of AutoComplete() overload taking + the array of possible completions if the total number of strings is too + big as it allows to return the completions dynamically, depending on + the text already entered by user and so is more efficient. + + The specified @a completer object will be used to retrieve the list of + possible completions for the already entered text and will be deleted + by wxTextEntry itself when it's not needed any longer. + + Notice that you need to include @c wx/textcompleter.h in order to + define your class inheriting from wxTextCompleter. + + Currently this method is only implemented in wxMSW and wxOSX/Cocoa. + + @since 2.9.2 + + @param completer + The object to be used for generating completions if non-@NULL. If + it is @NULL, auto-completion is disabled. The wxTextEntry object + takes ownership of this pointer and will delete it in any case + (i.e. even if this method returns @false). + + @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 wxTextCompleter + */ + bool AutoComplete(wxTextCompleter *completer); /** 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 + Notice that currently this function is only implemented in wxMSW port and does nothing under the other platforms. @since 2.9.0 @@ -74,7 +117,28 @@ public: @see AutoComplete() */ - virtual bool AutoCompleteFileNames(); + bool AutoCompleteFileNames(); + + /** + Call this function to enable auto-completion of the text using the file + system directories. + + Unlike AutoCompleteFileNames() which completes both file names and + directories, this function only completes the directory names. + + Notice that currently this function is only implemented in wxMSW port + and does nothing under the other platforms. + + @since 2.9.3 + + @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 AutoCompleteDirectories(); /** Returns @true if the selection can be copied to the clipboard. @@ -111,7 +175,7 @@ public: 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(). + would return @false immediately after the call to ChangeValue(). The insertion point is set to the start of the control (i.e. position 0) by this function. @@ -198,6 +262,11 @@ public: The returned first position. @param to The returned last position. + + @beginWxPerlOnly + In wxPerl this method takes no parameters and returns a + 2-element list (from, to). + @endWxPerlOnly */ virtual void GetSelection(long* from, long* to) const; @@ -368,9 +437,19 @@ public: Notice that hints are known as cue banners under MSW or placeholder strings under OS X. + @remarks For the platforms without native hints support (and currently + only the MSW port does have it and even there it is only used under + Windows Vista and later only), the implementation has several known + limitations. Notably, the hint display will not be properly updated + if you change wxTextEntry contents programmatically when the hint + is displayed using methods other than SetValue() or ChangeValue() + or others which use them internally (e.g. Clear()). In other words, + currently you should avoid calling methods such as WriteText() or + Replace() when using hints and the text control is empty. + @since 2.9.0 */ - virtual void SetHint(const wxString& hint); + virtual bool SetHint(const wxString& hint); /** Returns the current hint string. @@ -381,6 +460,35 @@ public: */ virtual wxString GetHint() const; + //@{ + /** + Attempts to set the control margins. When margins are given as wxPoint, + x indicates the left and y the top margin. Use -1 to indicate that + an existing value should be used. + + @return + @true if setting of all requested margins was successful. + + @since 2.9.1 + */ + bool SetMargins(const wxPoint& pt); + bool SetMargins(wxCoord left, wxCoord top = -1); + //@} + + /** + Returns the margins used by the control. The @c x field of the returned + point is the horizontal margin and the @c y field is the vertical one. + + @remarks If given margin cannot be accurately determined, its value + will be set to -1. On some platforms you cannot obtain valid + margin values until you have called SetMargins(). + + @see SetMargins() + + @since 2.9.1 + */ + wxPoint GetMargins() const; + /** Sets the new text control value.