]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/textentry.h
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)
7 // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
13 wxTextPos is a position in the text
15 typedef long wxTextPos
;
21 Common base class for single line text entry fields.
23 This class is not a control itself, as it doesn't derive from wxWindow.
24 Instead it is used as a base class by other controls, notably wxTextCtrl
25 and wxComboBox and gathers the methods common to both of them.
30 @see wxTextCtrl, wxComboBox
38 Appends the text to the end of the text control.
41 Text to write to the text control.
44 After the text is appended, the insertion point will be at the
45 end of the text control. If this behaviour is not desired, the
46 programmer should use GetInsertionPoint() and SetInsertionPoint().
50 virtual void AppendText(const wxString
& text
);
53 Call this function to enable auto-completion of the text typed in a
54 single-line text control using the given @a choices.
56 Notice that currently this function is only implemented in wxGTK2,
57 wxMSW and wxOSX/Cocoa ports and does nothing under the other platforms.
62 @true if the auto-completion was enabled or @false if the operation
63 failed, typically because auto-completion is not supported by the
66 @see AutoCompleteFileNames()
68 bool AutoComplete(const wxArrayString
& choices
);
71 Enable auto-completion using the provided completer object.
73 This method should be used instead of AutoComplete() overload taking
74 the array of possible completions if the total number of strings is too
75 big as it allows to return the completions dynamically, depending on
76 the text already entered by user and so is more efficient.
78 The specified @a completer object will be used to retrieve the list of
79 possible completions for the already entered text and will be deleted
80 by wxTextEntry itself when it's not needed any longer.
82 Notice that you need to include @c wx/textcompleter.h in order to
83 define your class inheriting from wxTextCompleter.
85 Currently this method is only implemented in wxMSW and wxOSX/Cocoa.
90 The object to be used for generating completions if non-@NULL. If
91 it is @NULL, auto-completion is disabled. The wxTextEntry object
92 takes ownership of this pointer and will delete it in any case
93 (i.e. even if this method returns @false).
96 @true if the auto-completion was enabled or @false if the operation
97 failed, typically because auto-completion is not supported by the
102 bool AutoComplete(wxTextCompleter
*completer
);
105 Call this function to enable auto-completion of the text typed in a
106 single-line text control using all valid file system paths.
108 Notice that currently this function is only implemented in wxMSW port
109 and does nothing under the other platforms.
114 @true if the auto-completion was enabled or @false if the operation
115 failed, typically because auto-completion is not supported by the
120 bool AutoCompleteFileNames();
123 Call this function to enable auto-completion of the text using the file
126 Unlike AutoCompleteFileNames() which completes both file names and
127 directories, this function only completes the directory names.
129 Notice that currently this function is only implemented in wxMSW port
130 and does nothing under the other platforms.
135 @true if the auto-completion was enabled or @false if the operation
136 failed, typically because auto-completion is not supported by the
141 bool AutoCompleteDirectories();
144 Returns @true if the selection can be copied to the clipboard.
146 virtual bool CanCopy() const;
149 Returns @true if the selection can be cut to the clipboard.
151 virtual bool CanCut() const;
154 Returns @true if the contents of the clipboard can be pasted into the
157 On some platforms (Motif, GTK) this is an approximation and returns
158 @true if the control is editable, @false otherwise.
160 virtual bool CanPaste() const;
163 Returns @true if there is a redo facility available and the last
164 operation can be redone.
166 virtual bool CanRedo() const;
169 Returns @true if there is an undo facility available and the last
170 operation can be undone.
172 virtual bool CanUndo() const;
175 Sets the new text control value.
177 It also marks the control as not-modified which means that IsModified()
178 would return @false immediately after the call to ChangeValue().
180 The insertion point is set to the start of the control (i.e. position
183 This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
184 event but otherwise is identical to SetValue().
186 See @ref overview_events_prog for more information.
191 The new value to set. It may contain newline characters if the text
192 control is multi-line.
194 virtual void ChangeValue(const wxString
& value
);
197 Clears the text in the control.
199 Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
200 event, i.e. its effect is identical to calling @c SetValue("").
202 virtual void Clear();
205 Copies the selected text to the clipboard.
210 Returns the insertion point, or cursor, position.
212 This is defined as the zero based index of the character position to
213 the right of the insertion point. For example, if the insertion point
214 is at the end of the single-line text control, it is equal to
217 Notice that insertion position is, in general, different from the index
218 of the character the cursor position at in the string returned by
219 GetValue(). While this is always the case for the single line controls,
220 multi-line controls can use two characters @c "\\r\\n" as line
221 separator (this is notably the case under MSW) meaning that indices in
222 the control and its string value are offset by 1 for every line.
224 Hence to correctly get the character at the current cursor position,
225 taking into account that there can be none if the cursor is at the end
226 of the string, you could do the following:
229 wxString GetCurrentChar(wxTextCtrl *tc)
231 long pos = tc->GetInsertionPoint();
232 if ( pos == tc->GetLastPosition() )
235 return tc->GetRange(pos, pos + 1);
239 virtual long GetInsertionPoint() const;
242 Returns the zero based index of the last position in the text control,
243 which is equal to the number of characters in the control.
245 virtual wxTextPos
GetLastPosition() const;
248 Returns the string containing the text starting in the positions
249 @a from and up to @a to in the control.
251 The positions must have been returned by another wxTextCtrl method.
252 Please note that the positions in a multiline wxTextCtrl do @b not
253 correspond to the indices in the string returned by GetValue() because
254 of the different new line representations (@c CR or @c CR LF) and so
255 this method should be used to obtain the correct results instead of
256 extracting parts of the entire value. It may also be more efficient,
257 especially if the control contains a lot of data.
259 virtual wxString
GetRange(long from
, long to
) const;
262 Gets the current selection span.
264 If the returned values are equal, there was no selection. Please note
265 that the indices returned may be used with the other wxTextCtrl methods
266 but don't necessarily represent the correct indices into the string
267 returned by GetValue() for multiline controls under Windows (at least,)
268 you should use GetStringSelection() to get the selected text.
271 The returned first position.
273 The returned last position.
276 In wxPerl this method takes no parameters and returns a
277 2-element list (from, to).
280 virtual void GetSelection(long* from
, long* to
) const;
283 Gets the text currently selected in the control.
285 If there is no selection, the returned string is empty.
287 virtual wxString
GetStringSelection() const;
290 Gets the contents of the control.
292 Notice that for a multiline text control, the lines will be separated
293 by (Unix-style) @c \\n characters, even under Windows where they are
294 separated by a @c \\r\\n sequence in the native control.
296 virtual wxString
GetValue() const;
299 Returns @true if the controls contents may be edited by user (note that
300 it always can be changed by the program).
302 In other words, this functions returns @true if the control hasn't been
303 put in read-only mode by a previous call to SetEditable().
305 virtual bool IsEditable() const;
308 Returns @true if the control is currently empty.
310 This is the same as @c GetValue().empty() but can be much more
311 efficient for the multiline controls containing big amounts of text.
315 virtual bool IsEmpty() const;
318 Pastes text from the clipboard to the text item.
320 virtual void Paste();
323 If there is a redo facility and the last operation can be redone,
324 redoes the last operation.
326 Does nothing if there is no redo facility.
331 Removes the text starting at the first given position up to
332 (but not including) the character at the last position.
334 This function puts the current insertion point position at @a to as a
342 virtual void Remove(long from
, long to
);
345 Replaces the text starting at the first position up to
346 (but not including) the character at the last position with the given text.
348 This function puts the current insertion point position at @a to as a
356 The value to replace the existing text with.
358 virtual void Replace(long from
, long to
, const wxString
& value
);
361 Makes the text item editable or read-only, overriding the
362 @b wxTE_READONLY flag.
365 If @true, the control is editable. If @false, the control is
370 virtual void SetEditable(bool editable
);
373 Sets the insertion point at the given position.
376 Position to set, in the range from 0 to GetLastPosition() inclusive.
378 virtual void SetInsertionPoint(long pos
);
381 Sets the insertion point at the end of the text control.
383 This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
384 wxTextCtrl::GetLastPosition() argument.
386 virtual void SetInsertionPointEnd();
389 This function sets the maximum number of characters the user can enter
392 In other words, it allows to limit the text value length to @a len not
393 counting the terminating @c NUL character.
395 If @a len is 0, the previously set max length limit, if any, is discarded
396 and the user may enter as much text as the underlying native text control widget
397 supports (typically at least 32Kb).
398 If the user tries to enter more characters into the text control when it
399 already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
400 event is sent to notify the program about it (giving it the possibility
401 to show an explanatory message, for example) and the extra input is discarded.
403 Note that in wxGTK this function may only be used with single line text controls.
405 virtual void SetMaxLength(unsigned long len
);
408 Selects the text starting at the first position up to (but not
409 including) the character at the last position.
411 If both parameters are equal to -1 all text in the control is selected.
413 Notice that the insertion point will be moved to @a from by this
423 virtual void SetSelection(long from
, long to
);
426 Selects all text in the control.
430 virtual void SelectAll();
433 Sets a hint shown in an empty unfocused text control.
435 The hints are usually used to indicate to the user what is supposed to
436 be entered into the given entry field, e.g. a common use of them is to
437 show an explanation of what can be entered in a wxSearchCtrl.
439 The hint is shown (usually greyed out) for an empty control until it
440 gets focus and is shown again if the control loses it and remains
441 empty. It won't be shown once the control has a non-empty value,
442 although it will be shown again if the control contents is cleared.
443 Because of this, it generally only makes sense to use hints with the
444 controls which are initially empty.
446 Notice that hints are known as <em>cue banners</em> under MSW or
447 <em>placeholder strings</em> under OS X.
449 @remarks For the platforms without native hints support (and currently
450 only the MSW port does have it and even there it is only used under
451 Windows Vista and later only), the implementation has several known
452 limitations. Notably, the hint display will not be properly updated
453 if you change wxTextEntry contents programmatically when the hint
454 is displayed using methods other than SetValue() or ChangeValue()
455 or others which use them internally (e.g. Clear()). In other words,
456 currently you should avoid calling methods such as WriteText() or
457 Replace() when using hints and the text control is empty.
459 @remarks Hints can only be used for single line text controls,
460 native multi-line text controls don't support hints under any
461 platform and hence wxWidgets doesn't provide them neither.
465 virtual bool SetHint(const wxString
& hint
);
468 Returns the current hint string.
470 See SetHint() for more information about hints.
474 virtual wxString
GetHint() const;
478 Attempts to set the control margins. When margins are given as wxPoint,
479 x indicates the left and y the top margin. Use -1 to indicate that
480 an existing value should be used.
483 @true if setting of all requested margins was successful.
487 bool SetMargins(const wxPoint
& pt
);
488 bool SetMargins(wxCoord left
, wxCoord top
= -1);
492 Returns the margins used by the control. The @c x field of the returned
493 point is the horizontal margin and the @c y field is the vertical one.
495 @remarks If given margin cannot be accurately determined, its value
496 will be set to -1. On some platforms you cannot obtain valid
497 margin values until you have called SetMargins().
503 wxPoint
GetMargins() const;
506 Sets the new text control value.
508 It also marks the control as not-modified which means that IsModified()
509 would return @false immediately after the call to SetValue().
511 The insertion point is set to the start of the control (i.e. position
514 Note that, unlike most other functions changing the controls values,
515 this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
516 this you can use ChangeValue() instead.
519 The new value to set. It may contain newline characters if the text
520 control is multi-line.
522 virtual void SetValue(const wxString
& value
);
525 If there is an undo facility and the last operation can be undone,
526 undoes the last operation.
528 Does nothing if there is no undo facility.
533 Writes the text into the text control at the current insertion position.
536 Text to write to the text control.
539 Newlines in the text string are the only control characters
540 allowed, and they will cause appropriate line breaks.
541 See operator<<() and AppendText() for more convenient ways of
542 writing to the window.
543 After the write operation, the insertion point will be at the end
544 of the inserted text, so subsequent write operations will be appended.
545 To append text after the user may have interacted with the control,
546 call wxTextCtrl::SetInsertionPointEnd() before writing.
548 virtual void WriteText(const wxString
& text
);