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)
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
   8 // Licence:     wxWindows licence
   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     @since 2.9.0
  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()
 116         would return @false immediately after the call to ChangeValue().
 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.
 203
 204         @beginWxPerlOnly
 205         In wxPerl this method takes no parameters and returns a
 206         2-element list (from, to).
 207         @endWxPerlOnly
 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
 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
 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
 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
 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
 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 };