[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 license
/////////////////////////////////////////////////////////////////////////////

/**
    @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
*/
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 SetValue().

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

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

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