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