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