[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 and
        wxMSW 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()
    */
    virtual bool AutoComplete(const wxArrayString& choices);

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