X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2e7789a933dd68fe41cf73325cda6094bef4d27d..b09857ae000a60704207d63290be937584805fb0:/interface/wx/textentry.h diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h index df1ddc9100..89fdaf5541 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. @@ -147,19 +211,28 @@ public: 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). + is at the end of the single-line text control, it is equal to + GetLastPosition(). - 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. + Notice that insertion position is, in general, different from the index + of the character the cursor position at in the string returned by + GetValue(). While this is always the case for the single line controls, + multi-line controls can use two characters @c "\\r\\n" as line + separator (this is notably the case under MSW) meaning that indices in + the control and its string value are offset by 1 for every line. + + Hence to correctly get the character at the current cursor position, + taking into account that there can be none if the cursor is at the end + of the string, you could do the following: @code - char GetCurrentChar(wxTextCtrl *tc) { - if (tc->GetInsertionPoint() == tc->GetLastPosition()) - return '\0'; - return tc->GetValue[tc->GetInsertionPoint()]; + wxString GetCurrentChar(wxTextCtrl *tc) + { + long pos = tc->GetInsertionPoint(); + if ( pos == tc->GetLastPosition() ) + return wxString(); + + return tc->GetRange(pos, pos + 1); } @endcode */ @@ -198,6 +271,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 +429,86 @@ public: */ virtual void SelectAll(); + /** + Deselects selected text in the control. + + @since 2.9.5 + */ + virtual void SelectNone(); + + /** + 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. + + @remarks Hints can only be used for single line text controls, + native multi-line text controls don't support hints under any + platform and hence wxWidgets doesn't provide them neither. + + @since 2.9.0 + */ + virtual bool 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.