// Created: 2009-03-01 (extracted from wx/textctrl.h)
// RCS-ID: $Id$
// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@category{ctrl}
@see wxTextCtrl, wxComboBox
+
+ @since 2.9.0
*/
class wxTextEntry
{
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
@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
@see AutoComplete()
*/
- virtual bool AutoCompleteFileNames();
+ bool AutoCompleteFileNames();
/**
Returns @true if the selection can be copied to the clipboard.
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.
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;
*/
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 <em>cue banners</em> under MSW or
+ <em>placeholder strings</em> 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.
projects / wxWidgets.git / blobdiff