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_TEXT
 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_TEXT
 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         Copies the selected text to the clipboard and removes it from the control.
 211     */
 212     virtual void Cut();
 213
 214     /**
 215         Returns the insertion point, or cursor, position.
 216
 217         This is defined as the zero based index of the character position to
 218         the right of the insertion point. For example, if the insertion point
 219         is at the end of the single-line text control, it is equal to
 220         GetLastPosition().
 221
 222         Notice that insertion position is, in general, different from the index
 223         of the character the cursor position at in the string returned by
 224         GetValue(). While this is always the case for the single line controls,
 225         multi-line controls can use two characters @c "\\r\\n" as line
 226         separator (this is notably the case under MSW) meaning that indices in
 227         the control and its string value are offset by 1 for every line.
 228
 229         Hence to correctly get the character at the current cursor position,
 230         taking into account that there can be none if the cursor is at the end
 231         of the string, you could do the following:
 232
 233         @code
 234         wxString GetCurrentChar(wxTextCtrl *tc)
 235         {
 236             long pos = tc->GetInsertionPoint();
 237             if ( pos == tc->GetLastPosition() )
 238                 return wxString();
 239
 240             return tc->GetRange(pos, pos + 1);
 241         }
 242         @endcode
 243     */
 244     virtual long GetInsertionPoint() const;
 245
 246     /**
 247         Returns the zero based index of the last position in the text control,
 248         which is equal to the number of characters in the control.
 249     */
 250     virtual wxTextPos GetLastPosition() const;
 251
 252     /**
 253         Returns the string containing the text starting in the positions
 254         @a from and up to @a to in the control.
 255
 256         The positions must have been returned by another wxTextCtrl method.
 257         Please note that the positions in a multiline wxTextCtrl do @b not
 258         correspond to the indices in the string returned by GetValue() because
 259         of the different new line representations (@c CR or @c CR LF) and so
 260         this method should be used to obtain the correct results instead of
 261         extracting parts of the entire value. It may also be more efficient,
 262         especially if the control contains a lot of data.
 263     */
 264     virtual wxString GetRange(long from, long to) const;
 265
 266     /**
 267         Gets the current selection span.
 268
 269         If the returned values are equal, there was no selection. Please note
 270         that the indices returned may be used with the other wxTextCtrl methods
 271         but don't necessarily represent the correct indices into the string
 272         returned by GetValue() for multiline controls under Windows (at least,)
 273         you should use GetStringSelection() to get the selected text.
 274
 275         @param from
 276             The returned first position.
 277         @param to
 278             The returned last position.
 279
 280         @beginWxPerlOnly
 281         In wxPerl this method takes no parameters and returns a
 282         2-element list (from, to).
 283         @endWxPerlOnly
 284     */
 285     virtual void GetSelection(long* from, long* to) const;
 286
 287     /**
 288         Gets the text currently selected in the control.
 289
 290         If there is no selection, the returned string is empty.
 291     */
 292     virtual wxString GetStringSelection() const;
 293
 294     /**
 295         Gets the contents of the control.
 296
 297         Notice that for a multiline text control, the lines will be separated
 298         by (Unix-style) @c \\n characters, even under Windows where they are
 299         separated by a @c \\r\\n sequence in the native control.
 300     */
 301     virtual wxString GetValue() const;
 302
 303     /**
 304         Returns @true if the controls contents may be edited by user (note that
 305         it always can be changed by the program).
 306
 307         In other words, this functions returns @true if the control hasn't been
 308         put in read-only mode by a previous call to SetEditable().
 309     */
 310     virtual bool IsEditable() const;
 311
 312     /**
 313         Returns @true if the control is currently empty.
 314
 315         This is the same as @c GetValue().empty() but can be much more
 316         efficient for the multiline controls containing big amounts of text.
 317
 318         @since 2.7.1
 319     */
 320     virtual bool IsEmpty() const;
 321
 322     /**
 323         Pastes text from the clipboard to the text item.
 324     */
 325     virtual void Paste();
 326
 327     /**
 328         If there is a redo facility and the last operation can be redone,
 329         redoes the last operation.
 330
 331         Does nothing if there is no redo facility.
 332     */
 333     virtual void Redo();
 334
 335     /**
 336         Removes the text starting at the first given position up to
 337         (but not including) the character at the last position.
 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     */
 347     virtual void Remove(long from, long to);
 348
 349     /**
 350         Replaces the text starting at the first position up to
 351         (but not including) the character at the last position with the given text.
 352
 353         This function puts the current insertion point position at @a to as a
 354         side effect.
 355
 356         @param from
 357             The first position.
 358         @param to
 359             The last position.
 360         @param value
 361             The value to replace the existing text with.
 362     */
 363     virtual void Replace(long from, long to, const wxString& value);
 364
 365     /**
 366         Makes the text item editable or read-only, overriding the
 367         @b wxTE_READONLY flag.
 368
 369         @param editable
 370             If @true, the control is editable. If @false, the control is
 371             read-only.
 372
 373         @see IsEditable()
 374     */
 375     virtual void SetEditable(bool editable);
 376
 377     /**
 378         Sets the insertion point at the given position.
 379
 380         @param pos
 381             Position to set, in the range from 0 to GetLastPosition() inclusive.
 382     */
 383     virtual void SetInsertionPoint(long pos);
 384
 385     /**
 386         Sets the insertion point at the end of the text control.
 387
 388         This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
 389         wxTextCtrl::GetLastPosition() argument.
 390     */
 391     virtual void SetInsertionPointEnd();
 392
 393     /**
 394         This function sets the maximum number of characters the user can enter
 395         into the control.
 396
 397         In other words, it allows to limit the text value length to @a len not
 398         counting the terminating @c NUL character.
 399
 400         If @a len is 0, the previously set max length limit, if any, is discarded
 401         and the user may enter as much text as the underlying native text control widget
 402         supports (typically at least 32Kb).
 403         If the user tries to enter more characters into the text control when it
 404         already is filled up to the maximal length, a @c wxEVT_TEXT_MAXLEN
 405         event is sent to notify the program about it (giving it the possibility
 406         to show an explanatory message, for example) and the extra input is discarded.
 407
 408         Note that in wxGTK this function may only be used with single line text controls.
 409     */
 410     virtual void SetMaxLength(unsigned long len);
 411
 412     /**
 413         Selects the text starting at the first position up to (but not
 414         including) the character at the last position.
 415
 416         If both parameters are equal to -1 all text in the control is selected.
 417
 418         Notice that the insertion point will be moved to @a from by this
 419         function.
 420
 421         @param from
 422             The first position.
 423         @param to
 424             The last position.
 425
 426         @see SelectAll()
 427     */
 428     virtual void SetSelection(long from, long to);
 429
 430     /**
 431         Selects all text in the control.
 432
 433         @see SetSelection()
 434     */
 435     virtual void SelectAll();
 436
 437     /**
 438         Deselects selected text in the control.
 439
 440         @since 2.9.5
 441     */
 442     virtual void SelectNone();
 443
 444     /**
 445         Sets a hint shown in an empty unfocused text control.
 446
 447         The hints are usually used to indicate to the user what is supposed to
 448         be entered into the given entry field, e.g. a common use of them is to
 449         show an explanation of what can be entered in a wxSearchCtrl.
 450
 451         The hint is shown (usually greyed out) for an empty control until it
 452         gets focus and is shown again if the control loses it and remains
 453         empty. It won't be shown once the control has a non-empty value,
 454         although it will be shown again if the control contents is cleared.
 455         Because of this, it generally only makes sense to use hints with the
 456         controls which are initially empty.
 457
 458         Notice that hints are known as <em>cue banners</em> under MSW or
 459         <em>placeholder strings</em> under OS X.
 460
 461         @remarks For the platforms without native hints support (and currently
 462             only the MSW port does have it and even there it is only used under
 463             Windows Vista and later only), the implementation has several known
 464             limitations. Notably, the hint display will not be properly updated
 465             if you change wxTextEntry contents programmatically when the hint
 466             is displayed using methods other than SetValue() or ChangeValue()
 467             or others which use them internally (e.g. Clear()). In other words,
 468             currently you should avoid calling methods such as WriteText() or
 469             Replace() when using hints and the text control is empty.
 470
 471         @remarks Hints can only be used for single line text controls,
 472             native multi-line text controls don't support hints under any
 473             platform and hence wxWidgets doesn't provide them neither.
 474
 475         @since 2.9.0
 476      */
 477     virtual bool SetHint(const wxString& hint);
 478
 479     /**
 480         Returns the current hint string.
 481
 482         See SetHint() for more information about hints.
 483
 484         @since 2.9.0
 485      */
 486     virtual wxString GetHint() const;
 487
 488     //@{
 489     /**
 490         Attempts to set the control margins. When margins are given as wxPoint,
 491         x indicates the left and y the top margin. Use -1 to indicate that
 492         an existing value should be used.
 493
 494         @return
 495             @true if setting of all requested margins was successful.
 496
 497         @since 2.9.1
 498     */
 499     bool SetMargins(const wxPoint& pt);
 500     bool SetMargins(wxCoord left, wxCoord top = -1);
 501     //@}
 502
 503     /**
 504         Returns the margins used by the control. The @c x field of the returned
 505         point is the horizontal margin and the @c y field is the vertical one.
 506
 507         @remarks If given margin cannot be accurately determined, its value
 508                 will be set to -1. On some platforms you cannot obtain valid
 509                 margin values until you have called SetMargins().
 510
 511         @see SetMargins()
 512
 513         @since 2.9.1
 514     */
 515     wxPoint GetMargins() const;
 516
 517     /**
 518         Sets the new text control value.
 519
 520         It also marks the control as not-modified which means that IsModified()
 521         would return @false immediately after the call to SetValue().
 522
 523         The insertion point is set to the start of the control (i.e. position
 524         0) by this function.
 525
 526         Note that, unlike most other functions changing the controls values,
 527         this function generates a @c wxEVT_TEXT event. To avoid
 528         this you can use ChangeValue() instead.
 529
 530         @param value
 531             The new value to set. It may contain newline characters if the text
 532             control is multi-line.
 533     */
 534     virtual void SetValue(const wxString& value);
 535
 536     /**
 537         If there is an undo facility and the last operation can be undone,
 538         undoes the last operation.
 539
 540         Does nothing if there is no undo facility.
 541     */
 542     virtual void Undo();
 543
 544     /**
 545         Writes the text into the text control at the current insertion position.
 546
 547         @param text
 548             Text to write to the text control.
 549
 550         @remarks
 551             Newlines in the text string are the only control characters
 552             allowed, and they will cause appropriate line breaks.
 553             See operator<<() and AppendText() for more convenient ways of
 554             writing to the window.
 555             After the write operation, the insertion point will be at the end
 556             of the inserted text, so subsequent write operations will be appended.
 557             To append text after the user may have interacted with the control,
 558             call wxTextCtrl::SetInsertionPointEnd() before writing.
 559     */
 560     virtual void WriteText(const wxString& text);
 561 };