.\" This is a wxWidgets manpage page generated from the XML docs
.TH wxTextCtrl 3wx 2005-02-15 "wxWidgets" "wxWidgets class documentation"
.SH NAME
wxTextCtrl \- 
  Single or multiline text editing control
 
.SH DESCRIPTION

  


   A text control allows text to be displayed and edited. It may be single line
   or multi-line.
  
  


   
    wxTextCtrl text format
   
  
  


   The multiline text controls always store the text as a sequence of lines
   separated by
   \backslashn
   characters, i.e. in the Unix text format even on non-Unix platforms. This
   allows the user code to ignore the differences between the platforms but at a
   price: the indices in the control such as those returned by
   GetInsertionPoint
   or
   GetSelection
   can
   
    not
   
   be used as indices into the string returned by
   GetValue
   as they're going to be slightly off for platforms using
   \backslashr\backslashn
   as separator (as Windows does), for example.
  
  


   Instead, if you need to obtain a substring between the 2 indices obtained
   from the control with the help of the functions mentioned above, you should
   use
   GetRange
   . And the indices themselves can only be passed to other methods, for example
   SetInsertionPoint
   or
   SetSelection
   .
  
  


   To summarize: never use the indices returned by (multiline) wxTextCtrl as
   indices into the string it contains, but only as arguments to be passed back
   to the other wxTextCtrl methods.
  
  


   
    styles
   
  
  


   Multi-line text controls support the styles, i.e. provide a possibility to
   set colours and font for individual characters in it (note that under Windows
   wxTE_RICH
   style is required for style support). To use the styles you can either call
   SetDefaultStyle
   before inserting the text or call
   SetStyle
   later to change the style of the text already in the control (the first
   solution is much more efficient).
  
  


   In either case, if the style doesn't specify some of the attributes (for
   example you only want to set the text colour but without changing the font
   nor the text background), the values of the default style will be used for
   them. If there is no default style, the attributes of the text control itself
   are used.
  
  


   So the following code correctly describes what it does: the second call to
   SetDefaultStyle
   doesn't change the text foreground colour (which stays red) while the last
   one doesn't change the background colour (which stays grey):
  
  


  
    text->SetDefaultStyle(wxTextAttr(*wxRED));
    text->AppendText("Red text\n");
    text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
    text->AppendText("Red on grey text\n");
    text->SetDefaultStyle(wxTextAttr(*wxBLUE);
    text->AppendText("Blue on grey text\n");

  


  


   
    C++ streams
   
  
  


   This class multiply-inherits from
   
    streambuf
   
   where compilers allow, allowing code such as the following:
  
  


  
  wxTextCtrl *control = new wxTextCtrl(...);

  ostream stream(control)

  stream << 123.456 << " some text\n";
  stream.flush();

  


  


   If your compiler does not support derivation from
   
    streambuf
   
   and gives a compile error, define the symbol
   
    NO_TEXT_WINDOW_STREAM
   
   in the wxTextCtrl header file.
  
  


   Note that independently of this setting you can always use wxTextCtrl itself
   in a stream-like manner:
  
  


  
  wxTextCtrl *control = new wxTextCtrl(...);

  *control << 123.456 << " some text\n";

  


  


   always works. However the possibility to create an ostream associated with
   wxTextCtrl may be useful if you need to redirect the output of a function
   taking an ostream as parameter to a text control.
  
  


   Another commonly requested need is to redirect
   
    std::cout
   
   to the text control. This could be done in the following way:
  
  


  
  #include <iostream>

  wxTextCtrl *control = new wxTextCtrl(...);

  std::streambuf *sbOld = std::cout.rdbuf();
  std::cout.rdbuf(*control);

  // use cout as usual, the output appears in the text control
  ...

  std::cout.rdbuf(sbOld);

  


  


   But wxWidgets provides a convenient class to make it even simpler so instead
   you may just do
  
  


  
  #include <iostream>

  wxTextCtrl *control = new wxTextCtrl(...);

  wxStreamToTextRedirector redirect(control);

  // all output to cout goes into the text control until the exit from current
  // scope

  


  


   See
   wxStreamToTextRedirector
   for more details.
  
 
.SH "PARENTS"

  streambuf
   
  wxControl
   
  wxWindow
   
  wxEvtHandler
   
  wxObject
 
.SH "INCLUDE FILES"
wx/textctrl.h
.SH MEMBERS

  
.SS  wxTextCtrl ()

     


      Default constructor.
     
    
.SS  wxTextCtrl (wxWindow* parentwxWindowID idconst wxString& value = ``"const wxPoint& pos = wxDefaultPositionconst wxSize& size = wxDefaultSizelong style = 0const wxValidator& validator = wxDefaultValidatorconst wxString& name = wxTextCtrlNameStr)

   
  
.SS  ~wxTextCtrl ()

     


      Destructor, destroying the text control.
     
    
   
  
.SS void AppendText (const wxString&  text)

     


      Appends the text to the end of the text control.
     
    
   
  
.SS virtual bool CanCopy ()

     


      Returns
      true
      if the selection can be copied to the clipboard.
     
    
   
  
.SS virtual bool CanCut ()

     


      Returns
      true
      if the selection can be cut to the clipboard.
     
    
   
  
.SS virtual bool CanPaste ()

     


      Returns
      true
      if the contents of the clipboard can be pasted into the text control. On
      some platforms (Motif, GTK) this is an approximation and returns
      true
      if the control is editable,
      false
      otherwise.
     
    
   
  
.SS virtual bool CanRedo ()

     


      Returns
      true
      if there is a redo facility available and the last operation can be
      redone.
     
    
   
  
.SS virtual bool CanUndo ()

     


      Returns
      true
      if there is an undo facility available and the last operation can be
      undone.
     
    
   
  
.SS virtual void Clear ()

     


      Clears the text in the control.
     
     


      Note that this function will generate a
      wxEVT_COMMAND_TEXT_UPDATED
      event.
     
    
   
  
.SS virtual void Copy ()

     


      Copies the selected text to the clipboard under Motif and MS Windows.
     
    
   
  
.SS bool Create (wxWindow* parentwxWindowID idconst wxString& value = ``"const wxPoint& pos = wxDefaultPositionconst wxSize& size = wxDefaultSizelong style = 0const wxValidator& validator = wxDefaultValidatorconst wxString& name = wxTextCtrlNameStr)

     


      Creates the text control for two-step construction. Derived classes should
      call or replace this function. See
      wxTextCtrl::wxTextCtrl
      for further details.
     
    
   
  
.SS virtual void Cut ()

     


      Copies the selected text to the clipboard and removes the selection.
     
    
   
  
.SS void DiscardEdits ()

     


      Resets the internal `modified' flag as if the current edits had been
      saved.
     
    
   
  
.SS bool EmulateKeyPress (const wxKeyEvent& event)

     


      This functions inserts into the control the character which would have
      been inserted if the given key event had occurred in the text control. The
      
       event
      
      object should be the same as the one passed to
      EVT_KEY_DOWN
      handler previously by wxWidgets.
     
     


      Please note that this function doesn't currently work correctly for all
      keys under any platform but MSW.
     
    
   
  
.SS const wxTextAttr&  GetDefaultStyle ()

     


      Returns the style currently used for the new text.
     
    
   
  
.SS virtual long GetInsertionPoint ()

     


      Returns the insertion point. This is defined as the zero based index of
      the character position to the right of the insertion point. For example,
      if the insertion point is at the end of the text control, it is equal to
      both
      GetValue()
      .Length() and
      GetLastPosition()
      .
     
     


      The following code snippet safely returns the character at the insertion
      point or the zero character if the point is at the end of the control.
     
     
  char GetCurrentChar(wxTextCtrl *tc) {
    if (tc->GetInsertionPoint() == tc->GetLastPosition())
      return '\0';
    return tc->GetValue[tc->GetInsertionPoint()];
  }

    
   
  
.SS virtual wxTextPos GetLastPosition ()

     


      Returns the zero based index of the last position in the text control,
      which is equal to the number of characters in the control.
     
    
   
  
.SS int GetLineLength (long lineNo)

     


      Gets the length of the specified line, not including any trailing newline
      character(s).
     
    
   
  
.SS wxString GetLineText (long lineNo)

     


      Returns the contents of a given line in the text control, not including
      any trailing newline character(s).
     
    
   
  
.SS int GetNumberOfLines ()

     


      Returns the number of lines in the text control buffer.
     
    
   
  
.SS virtual wxString GetRange (long fromlong to)

     


      Returns the string containing the text starting in the positions
      
       from
      
      and up to
      
       to
      
      in the control. The positions must have been returned by another
      wxTextCtrl method.
     
     


      Please note that the positions in a multiline wxTextCtrl do
      
       not
      
      correspond to the indices in the string returned by
      GetValue
      because of the different new line representations (
      CR
      or
      CR LF
      ) and so this method should be used to obtain the correct results instead
      of extracting parts of the entire value. It may also be more efficient,
      especially if the control contains a lot of data.
     
    
   
  
.SS virtual void GetSelection (long* fromlong* to)

     


      Gets the current selection span. If the returned values are equal, there
      was no selection.
     
     


      Please note that the indices returned may be used with the other
      wxTextctrl methods but don't necessarily represent the correct indices
      into the string returned by
      GetValue()
      for multiline controls under Windows (at least,) you should use
      GetStringSelection()
      to get the selected text.
     
    
   
  
.SS virtual wxString GetStringSelection ()

     


      Gets the text currently selected in the control. If there is no selection,
      the returned string is empty.
     
    
   
  
.SS bool GetStyle (long positionwxTextAttr& style)

   
  
.SS wxString GetValue ()

     


      Gets the contents of the control. Notice that for a multiline text
      control, the lines will be separated by (Unix-style) \backslashn
      characters, even under Windows where they are separated by a
      \backslashr\backslashn sequence in the native control.
     
    
   
  
.SS wxTextCtrlHitTestResult HitTest (const wxPoint& ptwxTextCoord *colwxTextCoord *row)

   
  
.SS bool IsEditable ()

     


      Returns
      true
      if the controls contents may be edited by user (note that it always can be
      changed by the program), i.e. if the control hasn't been put in read-only
      mode by a previous call to
      SetEditable
      .
     
    
   
  
.SS bool IsModified ()

     


      Returns
      true
      if the text has been modified by user. Note that calling
      SetValue
      doesn't make the control modified.
     
    
   
  
.SS bool IsMultiLine ()

     


      Returns
      true
      if this is a multi line edit control and
      false
      otherwise.
     
    
   
  
.SS bool IsSingleLine ()

     


      Returns
      true
      if this is a single line edit control and
      false
      otherwise.
     
    
   
  
.SS bool LoadFile (const wxString&  filename)

     


      Loads and displays the named file, if it exists.
     
    
   
  
.SS void MarkDirty ()

     


      Mark text as modified (dirty).
     
    
   
  
.SS void OnDropFiles (wxDropFilesEvent& event)

     


      This event handler function implements default drag and drop behaviour,
      which is to load the first dropped file into the control.
     
    
   
  
.SS virtual void Paste ()

     


      Pastes text from the clipboard to the text item.
     
    
   
  
.SS bool PositionToXY (long poslong *xlong *y)

     


      Converts given position to a zero-based column, line number pair.
     
    
   
  
.SS virtual void Redo ()

     


      If there is a redo facility and the last operation can be redone, redoes
      the last operation. Does nothing if there is no redo facility.
     
    
   
  
.SS virtual void Remove (long fromlong to)

     


      Removes the text starting at the first given position up to (but not
      including) the character at the last position.
     
    
   
  
.SS virtual void Replace (long fromlong toconst wxString& value)

     


      Replaces the text starting at the first position up to (but not including)
      the character at the last position with the given text.
     
    
   
  
.SS bool SaveFile (const wxString&  filename)

     


      Saves the contents of the control in a text file.
     
    
   
  
.SS bool SetDefaultStyle (const wxTextAttr& style)

     


      Changes the default style to use for the new text which is going to be
      added to the control using
      WriteText
      or
      AppendText
      .
     
     


      If either of the font, foreground, or background colour is not set in
      
       style
      
      , the values of the previous default style are used for them. If the
      previous default style didn't set them neither, the global font or colours
      of the text control itself are used as fall back.
     
     


      However if the
      
       style
      
      parameter is the default wxTextAttr, then the default style is just reset
      (instead of being combined with the new style which wouldn't change it at
      all).
     
    
   
  
.SS virtual void SetEditable (const bool editable)

     


      Makes the text item editable or read-only, overriding the
      
       wxTE_READONLY
      
      flag.
     
    
   
  
.SS virtual void SetInsertionPoint (long pos)

     


      Sets the insertion point at the given position.
     
    
   
  
.SS virtual void SetInsertionPointEnd ()

     


      Sets the insertion point at the end of the text control. This is
      equivalent to
      SetInsertionPoint
      (
      GetLastPosition
      ()).
     
    
   
  
.SS virtual void SetMaxLength (unsigned long len)

     


      This function sets the maximum number of characters the user can enter
      into the control. In other words, it allows to limit the text value length
      to
      
       len
      
      not counting the terminating
      NUL
      character.
     
     


      If
      
       len
      
      is 0, the previously set max length limit, if any, is discarded and the
      user may enter as much text as the underlying native text control widget
      supports (typically at least 32Kb).
     
     


      If the user tries to enter more characters into the text control when it
      already is filled up to the maximal length, a
      wxEVT_COMMAND_TEXT_MAXLEN
      event is sent to notify the program about it (giving it the possibility to
      show an explanatory message, for example) and the extra input is
      discarded.
     
     


      Note that under GTK+, this function may only be used with single line text
      controls.
     
     


      \wxheading{Compatibility}
     
     


      Only implemented in wxMSW/wxGTK starting with wxWidgets 2.3.2.
     
    
   
  
.SS virtual void SetSelection (long fromlong to)

     


      Selects the text starting at the first position up to (but not including)
      the character at the last position. If both parameters are equal to -1 all
      text in the control is selected.
     
    
   
  
.SS bool SetStyle (long startlong endconst wxTextAttr& style)

   
  
.SS virtual void SetValue (const wxString&  value)

     


      Sets the text value and marks the control as not-modified (which means
      that
      IsModified
      would return
      false
      immediately after the call to SetValue).
     
     


      Note that this function will generate a
      wxEVT_COMMAND_TEXT_UPDATED
      event.
     
    
   
  
.SS void ShowPosition (long pos)

     


      Makes the line containing the given position visible.
     
    
   
  
.SS virtual void Undo ()

     


      If there is an undo facility and the last operation can be undone, undoes
      the last operation. Does nothing if there is no undo facility.
     
    
   
  
.SS void WriteText (const wxString&  text)

     


      Writes the text into the text control at the current insertion position.
     
    
   
  
.SS long XYToPosition (long xlong y)

     


      Converts the given zero based column and line number to a position.
     
    
   
  
.SS wxTextCtrl& operator \cinsert (const wxString& s)

.SS wxTextCtrl& operator \cinsert (int i)

.SS wxTextCtrl& operator \cinsert (long i)

.SS wxTextCtrl& operator \cinsert (float f)

.SS wxTextCtrl& operator \cinsert (double d)

.SS wxTextCtrl& operator \cinsert (char c)

     


      Operator definitions for appending to a text control, for example:
     
     
  wxTextCtrl *wnd = new wxTextCtrl(my_frame);

  (*wnd) << "Welcome to text control number " << 1 << ".\n";

    
 
.SH "WINDOW STYLES"

.SS wxTE_PROCESS_ENTER

   wxTE_PROCESS_ENTER
  
.SS wxTE_PROCESS_TAB

   wxTE_PROCESS_TAB
  
.SS wxTE_MULTILINE

   The text control allows multiple lines.
  
.SS wxTE_PASSWORD

   The text will be echoed as asterisks.
  
.SS wxTE_READONLY

   The text will not be user-editable.
  
.SS wxTE_RICH

   wxTE_RICH
  
.SS wxTE_RICH2

   wxTE_RICH2
  
.SS wxTE_AUTO_URL

   wxTE_AUTO_URL
  
.SS wxTE_NOHIDESEL

   wxTE_NOHIDESEL
  
.SS wxHSCROLL

   wxHSCROLL
  
.SS wxTE_LEFT

   The text in the control will be left-justified (default).
  
.SS wxTE_CENTRE

   The text in the control will be centered (currently wxMSW and wxGTK2 only).
  
.SS wxTE_RIGHT

   The text in the control will be right-justified (currently wxMSW and wxGTK2
   only).
  
.SS wxTE_DONTWRAP

   Same as
   wxHSCROLL
   style: don't wrap at all, show horizontal scrollbar instead.
  
.SS wxTE_CHARWRAP

   Wrap the lines too long to be shown entirely at any position (wxUniv and
   wxGTK2 only).
  
.SS wxTE_WORDWRAP

   Wrap the lines too long to be shown entirely at word boundaries (wxUniv and
   wxGTK2 only).
  
.SS wxTE_BESTWRAP

   Wrap the lines at word boundaries or at any other character if there are
   words longer than the window width (this is the default).
  
.SS wxTE_CAPITALIZE

   On PocketPC and Smartphone, causes the first letter to be capitalized.
  
.SH EVENTS

.SS EVT_TEXT(id, func)

   Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text changes. Notice that this event will always be sent when the text controls contents changes - whether this is due to user input or comes from the program itself (for example, if SetValue() is called)
  
.SS EVT_TEXT_ENTER(id, func)

   Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is pressed in a text control (which must have wxTE_PROCESS_ENTER style for this event to be generated).
  
.SS EVT_TEXT_URL(id, func)

   A mouse event occurred over an URL in the text control (wxMSW and wxGTK2 only)
  
.SS EVT_TEXT_MAXLEN(id, func)

   User tried to enter more text into the control than the limit set by 
   SetMaxLength
   .
  
.SH "SEE ALSO"

  streambuf
   
  wxControl
   
  wxWindow
   
  wxEvtHandler
   
  wxObject
 
.SH "AUTHORS"
Documentation content by Julian Smart, Robert Roebling, Vadim Zeitlin, Robin Dunn, et al

Conversion to manpage format by Arnout Engelen (http://bzzt.net), bugreports welcome.