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 SetValue().
 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     virtual void GetSelection(long* from, long* to) const;
 203
 204     /**
 205         Gets the text currently selected in the control.
 206
 207         If there is no selection, the returned string is empty.
 208     */
 209     virtual wxString GetStringSelection() const;
 210
 211     /**
 212         Gets the contents of the control.
 213
 214         Notice that for a multiline text control, the lines will be separated
 215         by (Unix-style) @c \\n characters, even under Windows where they are
 216         separated by a @c \\r\\n sequence in the native control.
 217     */
 218     virtual wxString GetValue() const;
 219
 220     /**
 221         Returns @true if the controls contents may be edited by user (note that
 222         it always can be changed by the program).
 223
 224         In other words, this functions returns @true if the control hasn't been
 225         put in read-only mode by a previous call to SetEditable().
 226     */
 227     virtual bool IsEditable() const;
 228
 229     /**
 230         Returns @true if the control is currently empty.
 231
 232         This is the same as @c GetValue().empty() but can be much more
 233         efficient for the multiline controls containing big amounts of text.
 234
 235         @since 2.7.1
 236     */
 237     virtual bool IsEmpty() const;
 238
 239     /**
 240         Pastes text from the clipboard to the text item.
 241     */
 242     virtual void Paste();
 243
 244     /**
 245         If there is a redo facility and the last operation can be redone,
 246         redoes the last operation.
 247
 248         Does nothing if there is no redo facility.
 249     */
 250     virtual void Redo();
 251
 252     /**
 253         Removes the text starting at the first given position up to
 254         (but not including) the character at the last position.
 255
 256         This function puts the current insertion point position at @a to as a
 257         side effect.
 258
 259         @param from
 260             The first position.
 261         @param to
 262             The last position.
 263     */
 264     virtual void Remove(long from, long to);
 265
 266     /**
 267         Replaces the text starting at the first position up to
 268         (but not including) the character at the last position with the given text.
 269
 270         This function puts the current insertion point position at @a to as a
 271         side effect.
 272
 273         @param from
 274             The first position.
 275         @param to
 276             The last position.
 277         @param value
 278             The value to replace the existing text with.
 279     */
 280     virtual void Replace(long from, long to, const wxString& value);
 281
 282     /**
 283         Makes the text item editable or read-only, overriding the
 284         @b wxTE_READONLY flag.
 285
 286         @param editable
 287             If @true, the control is editable. If @false, the control is
 288             read-only.
 289
 290         @see IsEditable()
 291     */
 292     virtual void SetEditable(bool editable);
 293
 294     /**
 295         Sets the insertion point at the given position.
 296
 297         @param pos
 298             Position to set, in the range from 0 to GetLastPosition() inclusive.
 299     */
 300     virtual void SetInsertionPoint(long pos);
 301
 302     /**
 303         Sets the insertion point at the end of the text control.
 304
 305         This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
 306         wxTextCtrl::GetLastPosition() argument.
 307     */
 308     virtual void SetInsertionPointEnd();
 309
 310     /**
 311         This function sets the maximum number of characters the user can enter
 312         into the control.
 313
 314         In other words, it allows to limit the text value length to @a len not
 315         counting the terminating @c NUL character.
 316
 317         If @a len is 0, the previously set max length limit, if any, is discarded
 318         and the user may enter as much text as the underlying native text control widget
 319         supports (typically at least 32Kb).
 320         If the user tries to enter more characters into the text control when it
 321         already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
 322         event is sent to notify the program about it (giving it the possibility
 323         to show an explanatory message, for example) and the extra input is discarded.
 324
 325         Note that in wxGTK this function may only be used with single line text controls.
 326     */
 327     virtual void SetMaxLength(unsigned long len);
 328
 329     /**
 330         Selects the text starting at the first position up to (but not
 331         including) the character at the last position.
 332
 333         If both parameters are equal to -1 all text in the control is selected.
 334
 335         Notice that the insertion point will be moved to @a from by this
 336         function.
 337
 338         @param from
 339             The first position.
 340         @param to
 341             The last position.
 342
 343         @see SelectAll()
 344     */
 345     virtual void SetSelection(long from, long to);
 346
 347     /**
 348         Selects all text in the control.
 349
 350         @see SetSelection()
 351     */
 352     virtual void SelectAll();
 353
 354     /**
 355         Sets a hint shown in an empty unfocused text control.
 356
 357         The hints are usually used to indicate to the user what is supposed to
 358         be entered into the given entry field, e.g. a common use of them is to
 359         show an explanation of what can be entered in a wxSearchCtrl.
 360
 361         The hint is shown (usually greyed out) for an empty control until it
 362         gets focus and is shown again if the control loses it and remains
 363         empty. It won't be shown once the control has a non-empty value,
 364         although it will be shown again if the control contents is cleared.
 365         Because of this, it generally only makes sense to use hints with the
 366         controls which are initially empty.
 367
 368         Notice that hints are known as <em>cue banners</em> under MSW or
 369         <em>placeholder strings</em> under OS X.
 370
 371         @since 2.9.0
 372      */
 373     virtual void SetHint(const wxString& hint);
 374
 375     /**
 376         Returns the current hint string.
 377
 378         See SetHint() for more information about hints.
 379
 380         @since 2.9.0
 381      */
 382     virtual wxString GetHint() const;
 383
 384     //@{
 385     /**
 386         Attempts to set the control margins. When margins are given as wxPoint,
 387         x indicates the left and y the top margin. Use -1 to indicate that
 388         an existing value should be used.
 389
 390         @return
 391             @true if setting of all requested margins was successful.
 392
 393         @since 2.9.1
 394     */
 395     bool SetMargins(const wxPoint& pt);
 396     bool SetMargins(wxCoord left, wxCoord top = -1);
 397     //@}
 398
 399     /**
 400         Returns the margins used by the control. The @c x field of the returned
 401         point is the horizontal margin and the @c y field is the vertical one.
 402
 403         @remarks If given margin cannot be accurately determined, its value
 404                 will be set to -1. On some platforms you cannot obtain valid
 405                 margin values until you have called SetMargins().
 406
 407         @see SetMargins()
 408
 409         @since 2.9.1
 410     */
 411     wxPoint GetMargins() const;
 412
 413     /**
 414         Sets the new text control value.
 415
 416         It also marks the control as not-modified which means that IsModified()
 417         would return @false immediately after the call to SetValue().
 418
 419         The insertion point is set to the start of the control (i.e. position
 420         0) by this function.
 421
 422         Note that, unlike most other functions changing the controls values,
 423         this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
 424         this you can use ChangeValue() instead.
 425
 426         @param value
 427             The new value to set. It may contain newline characters if the text
 428             control is multi-line.
 429     */
 430     virtual void SetValue(const wxString& value);
 431
 432     /**
 433         If there is an undo facility and the last operation can be undone,
 434         undoes the last operation.
 435
 436         Does nothing if there is no undo facility.
 437     */
 438     virtual void Undo();
 439
 440     /**
 441         Writes the text into the text control at the current insertion position.
 442
 443         @param text
 444             Text to write to the text control.
 445
 446         @remarks
 447             Newlines in the text string are the only control characters
 448             allowed, and they will cause appropriate line breaks.
 449             See operator<<() and AppendText() for more convenient ways of
 450             writing to the window.
 451             After the write operation, the insertion point will be at the end
 452             of the inserted text, so subsequent write operations will be appended.
 453             To append text after the user may have interacted with the control,
 454             call wxTextCtrl::SetInsertionPointEnd() before writing.
 455     */
 456     virtual void WriteText(const wxString& text);
 457 };