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