[wxWidgets.git] / interface / wx / textentry.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/textentry.h
// Purpose:     interface of wxTextEntry
// Author:      Vadim Zeitlin
// Created:     2009-03-01 (extracted from wx/textctrl.h)
// RCS-ID:      $Id$
// Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxTextEntry

    Common base class for single line text entry fields.

    This class is not a control itself, as it doesn't derive from wxWindow.
    Instead it is used as a base class by other controls, notably wxTextCtrl
    and wxComboBox and gathers the methods common to both of them.

    @library{wxcore}
    @category{ctrl}

    @see wxTextCtrl, wxComboBox

    @since 2.9.0
*/
class wxTextEntry
{
public:
    /**
        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,
        wxMSW and wxOSX/Cocoa 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()
    */
    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 wxMSW 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()
    */
    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 ChangeValue().

        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_events_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();

    /**
        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;

    /**
        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.

        @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;

    /**
        Gets the text currently selected in the control.

        If there is no selection, the returned string is empty.
    */
    virtual wxString GetStringSelection() const;

    /**
        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;

    /**
        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;

    /**
        Pastes text from the clipboard to the text item.
    */
    virtual void Paste();

    /**
        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.

        This function puts the current insertion point position at @a to as a
        side effect.

        @param from
            The first position.
        @param to
            The last position.
    */
    virtual void Remove(long from, long to);

    /**
        Replaces the text starting at the first position up to
        (but not including) the character at the last position with the given text.

        This function puts the current insertion point position at @a to as a
        side effect.

        @param from
            The first position.
        @param to
            The last position.
        @param value
            The value to replace the existing text with.
    */
    virtual void Replace(long from, long to, const wxString& value);

    /**
        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);

    /**
        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();

    /**
        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.

        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);

    /**
        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);
};
Commit	Line	Data
2e7789a9 VZ	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/textentry.h
	3	// Purpose: interface of wxTextEntry
	4	// Author: Vadim Zeitlin
	5	// Created: 2009-03-01 (extracted from wx/textctrl.h)
	6	// RCS-ID: $Id$
	7	// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
526954c5	8	// Licence: wxWindows licence
2e7789a9 VZ	9	/////////////////////////////////////////////////////////////////////////////
	10
	11	/**
	12	@class wxTextEntry
	13
	14	Common base class for single line text entry fields.
	15
	16	This class is not a control itself, as it doesn't derive from wxWindow.
	17	Instead it is used as a base class by other controls, notably wxTextCtrl
	18	and wxComboBox and gathers the methods common to both of them.
	19
	20	@library{wxcore}
	21	@category{ctrl}
	22
	23	@see wxTextCtrl, wxComboBox
5a969d51 VS	24
5a969d51 VS	25	@since 2.9.0
2e7789a9 VZ	26	*/
	27	class wxTextEntry
	28	{
	29	public:
	30	/**
	31	Appends the text to the end of the text control.
	32
	33	@param text
	34	Text to write to the text control.
	35
	36	@remarks
	37	After the text is appended, the insertion point will be at the
	38	end of the text control. If this behaviour is not desired, the
	39	programmer should use GetInsertionPoint() and SetInsertionPoint().
	40
	41	@see WriteText()
	42	*/
	43	virtual void AppendText(const wxString& text);
	44
	45	/**
	46	Call this function to enable auto-completion of the text typed in a
	47	single-line text control using the given @a choices.
	48
c729f16f VZ	49	Notice that currently this function is only implemented in wxGTK2,
c729f16f VZ	50	wxMSW and wxOSX/Cocoa ports and does nothing under the other platforms.
2e7789a9 VZ	51
	52	@since 2.9.0
	53
	54	@return
	55	@true if the auto-completion was enabled or @false if the operation
	56	failed, typically because auto-completion is not supported by the
	57	current platform.
	58
	59	@see AutoCompleteFileNames()
	60	*/
574479e8	61	bool AutoComplete(const wxArrayString& choices);
2e7789a9	62
ea98f11c VZ	63	/**
	64	Enable auto-completion using the provided completer object.
	65
	66	This method should be used instead of AutoComplete() overload taking
	67	the array of possible completions if the total number of strings is too
	68	big as it allows to return the completions dynamically, depending on
	69	the text already entered by user and so is more efficient.
	70
	71	The specified @a completer object will be used to retrieve the list of
	72	possible completions for the already entered text and will be deleted
	73	by wxTextEntry itself when it's not needed any longer.
	74
	75	Notice that you need to include @c wx/textcompleter.h in order to
	76	define your class inheriting from wxTextCompleter.
	77
c729f16f	78	Currently this method is only implemented in wxMSW and wxOSX/Cocoa.
ea98f11c VZ	79
	80	@since 2.9.2
	81
	82	@param completer
	83	The object to be used for generating completions if non-@NULL. If
	84	it is @NULL, auto-completion is disabled. The wxTextEntry object
	85	takes ownership of this pointer and will delete it in any case
	86	(i.e. even if this method returns @false).
	87
	88	@return
	89	@true if the auto-completion was enabled or @false if the operation
	90	failed, typically because auto-completion is not supported by the
	91	current platform.
	92
	93	@see wxTextCompleter
	94	*/
	95	bool AutoComplete(wxTextCompleter *completer);
	96
2e7789a9 VZ	97	/**
	98	Call this function to enable auto-completion of the text typed in a
	99	single-line text control using all valid file system paths.
	100
a0f01cb2	101	Notice that currently this function is only implemented in wxMSW port
2e7789a9 VZ	102	and does nothing under the other platforms.
	103
	104	@since 2.9.0
	105
	106	@return
	107	@true if the auto-completion was enabled or @false if the operation
	108	failed, typically because auto-completion is not supported by the
	109	current platform.
	110
	111	@see AutoComplete()
	112	*/
574479e8	113	bool AutoCompleteFileNames();
2e7789a9 VZ	114
	115	/**
	116	Returns @true if the selection can be copied to the clipboard.
	117	*/
	118	virtual bool CanCopy() const;
	119
	120	/**
	121	Returns @true if the selection can be cut to the clipboard.
	122	*/
	123	virtual bool CanCut() const;
	124
	125	/**
	126	Returns @true if the contents of the clipboard can be pasted into the
	127	text control.
	128
	129	On some platforms (Motif, GTK) this is an approximation and returns
	130	@true if the control is editable, @false otherwise.
	131	*/
	132	virtual bool CanPaste() const;
	133
	134	/**
	135	Returns @true if there is a redo facility available and the last
	136	operation can be redone.
	137	*/
	138	virtual bool CanRedo() const;
	139
	140	/**
	141	Returns @true if there is an undo facility available and the last
	142	operation can be undone.
	143	*/
	144	virtual bool CanUndo() const;
	145
	146	/**
	147	Sets the new text control value.
	148
	149	It also marks the control as not-modified which means that IsModified()
1dd35cd6	150	would return @false immediately after the call to ChangeValue().
2e7789a9 VZ	151
	152	The insertion point is set to the start of the control (i.e. position
	153	0) by this function.
	154
	155	This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
	156	event but otherwise is identical to SetValue().
	157
	158	See @ref overview_events_prog for more information.
	159
	160	@since 2.7.1
	161
	162	@param value
	163	The new value to set. It may contain newline characters if the text
	164	control is multi-line.
	165	*/
	166	virtual void ChangeValue(const wxString& value);
	167
	168	/**
	169	Clears the text in the control.
	170
	171	Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
	172	event, i.e. its effect is identical to calling @c SetValue("").
	173	*/
	174	virtual void Clear();
	175
	176	/**
	177	Copies the selected text to the clipboard.
	178	*/
	179	virtual void Copy();
	180
	181	/**
	182	Returns the insertion point, or cursor, position.
	183
	184	This is defined as the zero based index of the character position to
	185	the right of the insertion point. For example, if the insertion point
	186	is at the end of the single-line text control, it is equal to both
	187	GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
	188	equality is not necessarily true for multiline edit controls which may
	189	use multiple new line characters).
	190
	191	The following code snippet safely returns the character at the insertion
	192	point or the zero character if the point is at the end of the control.
	193
	194	@code
	195	char GetCurrentChar(wxTextCtrl *tc) {
	196	if (tc->GetInsertionPoint() == tc->GetLastPosition())
	197	return '\0';
	198	return tc->GetValue[tc->GetInsertionPoint()];
	199	}
	200	@endcode
	201	*/
	202	virtual long GetInsertionPoint() const;
	203
	204	/**
	205	Returns the zero based index of the last position in the text control,
	206	which is equal to the number of characters in the control.
	207	*/
	208	virtual wxTextPos GetLastPosition() const;
	209
	210	/**
	211	Returns the string containing the text starting in the positions
	212	@a from and up to @a to in the control.
	213
	214	The positions must have been returned by another wxTextCtrl method.
215	Please note that the positions in a multiline wxTextCtrl do @b not
216	correspond to the indices in the string returned by GetValue() because
217	of the different new line representations (@c CR or @c CR LF) and so
218	this method should be used to obtain the correct results instead of
219	extracting parts of the entire value. It may also be more efficient,
220	especially if the control contains a lot of data.
221	*/
222	virtual wxString GetRange(long from, long to) const;
223
224	/**
225	Gets the current selection span.
226
227	If the returned values are equal, there was no selection. Please note
228	that the indices returned may be used with the other wxTextCtrl methods
229	but don't necessarily represent the correct indices into the string
230	returned by GetValue() for multiline controls under Windows (at least,)
231	you should use GetStringSelection() to get the selected text.
232
233	@param from
234	The returned first position.
235	@param to
236	The returned last position.
1058f652 MB	237
	238	@beginWxPerlOnly
	239	In wxPerl this method takes no parameters and returns a
	240	2-element list (from, to).
	241	@endWxPerlOnly
2e7789a9 VZ	242	*/
	243	virtual void GetSelection(long* from, long* to) const;
	244
	245	/**
	246	Gets the text currently selected in the control.
	247
	248	If there is no selection, the returned string is empty.
	249	*/
	250	virtual wxString GetStringSelection() const;
	251
	252	/**
	253	Gets the contents of the control.
	254
	255	Notice that for a multiline text control, the lines will be separated
	256	by (Unix-style) @c \\n characters, even under Windows where they are
	257	separated by a @c \\r\\n sequence in the native control.
	258	*/
	259	virtual wxString GetValue() const;
	260
	261	/**
	262	Returns @true if the controls contents may be edited by user (note that
	263	it always can be changed by the program).
	264
	265	In other words, this functions returns @true if the control hasn't been
	266	put in read-only mode by a previous call to SetEditable().
	267	*/
	268	virtual bool IsEditable() const;
	269
	270	/**
	271	Returns @true if the control is currently empty.
	272
	273	This is the same as @c GetValue().empty() but can be much more
	274	efficient for the multiline controls containing big amounts of text.
	275
	276	@since 2.7.1
	277	*/
	278	virtual bool IsEmpty() const;
	279
	280	/**
	281	Pastes text from the clipboard to the text item.
	282	*/
	283	virtual void Paste();
	284
	285	/**
	286	If there is a redo facility and the last operation can be redone,
	287	redoes the last operation.
	288
	289	Does nothing if there is no redo facility.
	290	*/
	291	virtual void Redo();
	292
	293	/**
	294	Removes the text starting at the first given position up to
	295	(but not including) the character at the last position.
	296
	297	This function puts the current insertion point position at @a to as a
	298	side effect.
	299
	300	@param from
	301	The first position.
	302	@param to
	303	The last position.
	304	*/
	305	virtual void Remove(long from, long to);
306
307	/**
308	Replaces the text starting at the first position up to
309	(but not including) the character at the last position with the given text.
310
311	This function puts the current insertion point position at @a to as a
312	side effect.
313
314	@param from
315	The first position.
316	@param to
317	The last position.
318	@param value
319	The value to replace the existing text with.
320	*/
321	virtual void Replace(long from, long to, const wxString& value);
322
323	/**
324	Makes the text item editable or read-only, overriding the
325	@b wxTE_READONLY flag.
326
327	@param editable
328	If @true, the control is editable. If @false, the control is
329	read-only.
330
331	@see IsEditable()
332	*/
333	virtual void SetEditable(bool editable);
334
335	/**
336	Sets the insertion point at the given position.
337
338	@param pos
339	Position to set, in the range from 0 to GetLastPosition() inclusive.
340	*/
341	virtual void SetInsertionPoint(long pos);
342
343	/**
344	Sets the insertion point at the end of the text control.
345
346	This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
347	wxTextCtrl::GetLastPosition() argument.
348	*/
349	virtual void SetInsertionPointEnd();
350
351	/**
352	This function sets the maximum number of characters the user can enter
353	into the control.
354
355	In other words, it allows to limit the text value length to @a len not
356	counting the terminating @c NUL character.
357
358	If @a len is 0, the previously set max length limit, if any, is discarded
359	and the user may enter as much text as the underlying native text control widget
360	supports (typically at least 32Kb).
361	If the user tries to enter more characters into the text control when it
362	already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
363	event is sent to notify the program about it (giving it the possibility
364	to show an explanatory message, for example) and the extra input is discarded.
365
366	Note that in wxGTK this function may only be used with single line text controls.
367	*/
368	virtual void SetMaxLength(unsigned long len);
369
370	/**
371	Selects the text starting at the first position up to (but not
372	including) the character at the last position.
373
374	If both parameters are equal to -1 all text in the control is selected.
375
376	Notice that the insertion point will be moved to @a from by this
377	function.
378
379	@param from
380	The first position.
381	@param to
382	The last position.
383
384	@see SelectAll()
385	*/
386	virtual void SetSelection(long from, long to);
387
388	/**
389	Selects all text in the control.
390
391	@see SetSelection()
392	*/
393	virtual void SelectAll();
394
63f7d502 VZ	395	/**
	396	Sets a hint shown in an empty unfocused text control.
	397
	398	The hints are usually used to indicate to the user what is supposed to
	399	be entered into the given entry field, e.g. a common use of them is to
	400	show an explanation of what can be entered in a wxSearchCtrl.
	401
	402	The hint is shown (usually greyed out) for an empty control until it
	403	gets focus and is shown again if the control loses it and remains
	404	empty. It won't be shown once the control has a non-empty value,
	405	although it will be shown again if the control contents is cleared.
	406	Because of this, it generally only makes sense to use hints with the
	407	controls which are initially empty.
	408
	409	Notice that hints are known as <em>cue banners</em> under MSW or
	410	<em>placeholder strings</em> under OS X.
	411
7d4cb1ef VZ	412	@remarks For the platforms without native hints support (and currently
	413	only the MSW port does have it and even there it is only used under
	414	Windows Vista and later only), the implementation has several known
	415	limitations. Notably, the hint display will not be properly updated
	416	if you change wxTextEntry contents programmatically when the hint
	417	is displayed using methods other than SetValue() or ChangeValue()
	418	or others which use them internally (e.g. Clear()). In other words,
	419	currently you should avoid calling methods such as WriteText() or
	420	Replace() when using hints and the text control is empty.
	421
63f7d502 VZ	422	@since 2.9.0
	423	*/
	424	virtual void SetHint(const wxString& hint);
	425
	426	/**
	427	Returns the current hint string.
	428
	429	See SetHint() for more information about hints.
	430
	431	@since 2.9.0
	432	*/
	433	virtual wxString GetHint() const;
	434
0847e36e JS	435	//@{
	436	/**
	437	Attempts to set the control margins. When margins are given as wxPoint,
	438	x indicates the left and y the top margin. Use -1 to indicate that
	439	an existing value should be used.
	440
	441	@return
	442	@true if setting of all requested margins was successful.
	443
	444	@since 2.9.1
	445	*/
	446	bool SetMargins(const wxPoint& pt);
	447	bool SetMargins(wxCoord left, wxCoord top = -1);
	448	//@}
	449
	450	/**
	451	Returns the margins used by the control. The @c x field of the returned
	452	point is the horizontal margin and the @c y field is the vertical one.
	453
	454	@remarks If given margin cannot be accurately determined, its value
	455	will be set to -1. On some platforms you cannot obtain valid
	456	margin values until you have called SetMargins().
	457
	458	@see SetMargins()
	459
	460	@since 2.9.1
	461	*/
	462	wxPoint GetMargins() const;
	463
2e7789a9 VZ	464	/**
	465	Sets the new text control value.
	466
	467	It also marks the control as not-modified which means that IsModified()
	468	would return @false immediately after the call to SetValue().
	469
	470	The insertion point is set to the start of the control (i.e. position
	471	0) by this function.
	472
	473	Note that, unlike most other functions changing the controls values,
	474	this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
	475	this you can use ChangeValue() instead.
	476
	477	@param value
	478	The new value to set. It may contain newline characters if the text
	479	control is multi-line.
	480	*/
	481	virtual void SetValue(const wxString& value);
	482
	483	/**
	484	If there is an undo facility and the last operation can be undone,
	485	undoes the last operation.
	486
	487	Does nothing if there is no undo facility.
	488	*/
	489	virtual void Undo();
	490
	491	/**
	492	Writes the text into the text control at the current insertion position.
	493
	494	@param text
	495	Text to write to the text control.
	496
	497	@remarks
	498	Newlines in the text string are the only control characters
	499	allowed, and they will cause appropriate line breaks.
	500	See operator<<() and AppendText() for more convenient ways of
	501	writing to the window.
	502	After the write operation, the insertion point will be at the end
	503	of the inserted text, so subsequent write operations will be appended.
	504	To append text after the user may have interacted with the control,
	505	call wxTextCtrl::SetInsertionPointEnd() before writing.
	506	*/
	507	virtual void WriteText(const wxString& text);
	508	};