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