+
+ @section textctrl_text_format wxTextCtrl Text Format
+
+ The multiline text controls always store the text as a sequence of lines
+ separated by @c '\\n' 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 @b not be used
+ as indices into the string returned by GetValue() as they're going to be
+ slightly off for platforms using @c "\\r\\n" as separator (as Windows
+ does).
+
+ 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. This problem doesn't arise for
+ single-line platforms however where the indices in the control do
+ correspond to the positions in the value string.
+
+
+ @section textctrl_styles wxTextCtrl Styles.
+
+ Multi-line text controls support styling, i.e. provide a possibility to set
+ colours and font for individual characters in it (note that under Windows
+ @c 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):
+
+ @code
+ 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");
+ @endcode
+
+
+ @section textctrl_cpp_streams wxTextCtrl and C++ Streams
+
+ This class multiply-inherits from @c std::streambuf (except for some really
+ old compilers using non-standard iostream library), allowing code such as
+ the following:
+
+ @code
+ wxTextCtrl *control = new wxTextCtrl(...);
+
+ ostream stream(control)
+
+ stream << 123.456 << " some text\n";
+ stream.flush();
+ @endcode
+
+ Note that even if your compiler doesn't support this (the symbol
+ @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use
+ wxTextCtrl itself in a stream-like manner:
+
+ @code
+ wxTextCtrl *control = new wxTextCtrl(...);
+
+ *control << 123.456 << " some text\n";
+ @endcode
+
+ 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 @c std::cout to the text
+ control. This may be done in the following way:
+
+ @code
+ #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);
+ @endcode
+
+ But wxWidgets provides a convenient class to make it even simpler so
+ instead you may just do
+
+ @code
+ #include <iostream>
+
+ wxTextCtrl *control = new wxTextCtrl(...);
+
+ wxStreamToTextRedirector redirect(control);
+
+ // all output to cout goes into the text control until the exit from
+ // current scope
+ @endcode
+
+ See wxStreamToTextRedirector for more details.
+
+
+ @section textctrl_event_handling Event Handling.
+
+ The following commands are processed by default event handlers in
+ wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c
+ wxID_REDO. The associated UI update events are also processed
+ automatically, when the control has the focus.
+
+ To process input from a text control, use these event handler macros to
+ direct input to member functions that take a wxCommandEvent argument.
+
+ @beginEventTable{wxCommandEvent}
+ @event{EVT_TEXT(id, func)}
+ Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
+ changes. Notice that this event will 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); see
+ ChangeValue() for a function which does not send this event. This
+ event is however not sent during the control creation.
+ @event{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.
+ @event{EVT_TEXT_URL(id, func)}
+ A mouse event occurred over an URL in the text control (wxMSW and
+ wxGTK2 only currently).
+ @event{EVT_TEXT_MAXLEN(id, func)}
+ This event is generated when the user tries to enter more text into the
+ control than the limit set by SetMaxLength(), see its description.
+ @endEventTable
+
projects / wxWidgets.git / blobdiff