X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2e7789a933dd68fe41cf73325cda6094bef4d27d..caa1ec9545f5ac943e90f12d4a87f7a43e0eb15d:/interface/wx/textentry.h?ds=sidebyside diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h index df1ddc9100..a2c7b7f8b6 100644 --- a/interface/wx/textentry.h +++ b/interface/wx/textentry.h @@ -5,7 +5,7 @@ // Created: 2009-03-01 (extracted from wx/textctrl.h) // RCS-ID: $Id$ // Copyright: (c) 2009 Vadim Zeitlin -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -21,6 +21,8 @@ @category{ctrl} @see wxTextCtrl, wxComboBox + + @since 2.9.0 */ class wxTextEntry { @@ -44,8 +46,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 +58,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 +110,7 @@ public: @see AutoComplete() */ - virtual bool AutoCompleteFileNames(); + bool AutoCompleteFileNames(); /** Returns @true if the selection can be copied to the clipboard. @@ -111,7 +147,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 +234,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; @@ -351,6 +392,75 @@ public: */ virtual void SelectAll(); + /** + Sets a hint shown in an empty unfocused text control. + + The hints are usually used to indicate to the user what is supposed to + be entered into the given entry field, e.g. a common use of them is to + show an explanation of what can be entered in a wxSearchCtrl. + + The hint is shown (usually greyed out) for an empty control until it + gets focus and is shown again if the control loses it and remains + empty. It won't be shown once the control has a non-empty value, + although it will be shown again if the control contents is cleared. + Because of this, it generally only makes sense to use hints with the + controls which are initially empty. + + 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); + + /** + Returns the current hint string. + + See SetHint() for more information about hints. + + @since 2.9.0 + */ + 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.