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