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