docs/latex/wx/text.tex

   1 \section{\class{wxTextCtrl}}\label{wxtextctrl}
   2
   3 A text control allows text to be displayed and edited. It may be
   4 single line or multiline.
   5
   6 \wxheading{Derived from}
   7
   8 streambuf\\
   9 \helpref{wxControl}{wxcontrol}\\
  10 \helpref{wxWindow}{wxwindow}\\
  11 \helpref{wxEvtHandler}{wxevthandler}\\
  12 \helpref{wxObject}{wxobject}
  13
  14 \wxheading{Window styles}
  15
  16 \twocolwidtha{5cm}
  17 \begin{twocollist}\itemsep=0pt
  18 \twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The callback function will
  19 receive the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND. Note
  20 that this will break tab traversal for this panel item under
  21 Windows.}
  22 \twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
  23 \twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
  24 \twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
  25 \twocolitem{\windowstyle{wxHSCROLL}}{A vertical scrollbar will be present.}
  26 \end{twocollist}
  27
  28 See also \helpref{window styles overview}{windowstyles}.
  29
  30 \wxheading{Remarks}
  31
  32 This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such
  33 as the following:
  34
  35 {\small%
  36 \begin{verbatim}
  37   wxTextCtrl *control = new wxTextCtrl(...);
  38
  39   ostream stream(control)
  40
  41   stream << 123.456 << " some text\n";
  42   stream.flush();
  43 \end{verbatim}
  44 }%
  45
  46 If your compiler does not support derivation from {\bf streambuf} and gives a compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
  47 wxTextCtrl header file.
  48
  49 %\wxheading{See also}
  50 %
  51 %\helpref{wxRichTextCtrl}{wxrichtextctrl}
  52 %
  53 \latexignore{\rtfignore{\wxheading{Members}}}
  54
  55 \membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
  56
  57 \func{}{wxTextCtrl}{\void}
  58
  59 Default constructor.
  60
  61 \func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
  62 \param{const wxString\& }{value = ``"}, \param{const wxPosition\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  63 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
  64
  65 Constructor, creating and showing a text control.
  66
  67 \wxheading{Parameters}
  68
  69 \docparam{parent}{Parent window. Should not be NULL.}
  70
  71 \docparam{id}{Control identifier. A value of -1 denotes a default value.}
  72
  73 \docparam{value}{Default text value.}
  74
  75 \docparam{pos}{Text control position.}
  76
  77 \docparam{size}{Text control size.}
  78
  79 \docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
  80
  81 \docparam{validator}{Window validator.}
  82
  83 \docparam{name}{Window name.}
  84
  85 \wxheading{Remarks}
  86
  87 Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
  88 as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
  89 apply.
  90
  91 \wxheading{See also}
  92
  93 \helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
  94
  95 \membersection{wxTextCtrl::\destruct{wxTextCtrl}}
  96
  97 \func{}{\destruct{wxTextCtrl}}{\void}
  98
  99 Destructor, destroying the text control.
 100
 101 \membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
 102
 103 \func{virtual void}{Clear}{\void}
 104
 105 Clears the text in the control.
 106
 107 \membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
 108
 109 \func{virtual void}{Copy}{\void}
 110
 111 Copies the selected text to the clipboard under Motif and MS Windows.
 112
 113 \membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
 114
 115 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
 116 \param{const wxString\& }{value = ``"}, \param{const wxPosition\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 117 \param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
 118
 119 Creates the text control for two-step construction. Derived classes
 120 should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
 121 for further details.
 122
 123 \membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
 124
 125 \func{virtual void}{Cut}{\void}
 126
 127 Copies the selected text to the clipboard and removes the selection.
 128
 129 \membersection{wxTextCtrl::DiscardEdits}
 130
 131 \func{void}{DiscardEdits}{\void}
 132
 133 Resets the internal `modified' flag as if the current edits had been saved.
 134
 135 \membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
 136
 137 \constfunc{virtual long}{GetInsertionPoint}{\void}
 138
 139 Returns the insertion point.
 140
 141 \membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
 142
 143 \constfunc{virtual long}{GetLastPosition}{\void}
 144
 145 Returns the last position in the text control.
 146
 147 \membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
 148
 149 \constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
 150
 151 Gets the length of the specified line.
 152
 153 \wxheading{Parameters}
 154
 155 \docparam{lineNo}{Line number (starting from zero).}
 156
 157 \wxheading{Return value}
 158
 159 The length of the line, or -1 if {\it lineNo} was invalid.
 160
 161 \membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
 162
 163 \constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
 164
 165 Returns the contents of a given line in the text control.
 166
 167 \wxheading{Parameters}
 168
 169 \docparam{lineNo}{The line number, starting from zero.}
 170
 171 \wxheading{Return value}
 172
 173 The contents of the line.
 174
 175 \membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
 176
 177 \constfunc{int}{GetNumberOfLines}{\void}
 178
 179 Returns the number of lines in the text control buffer.
 180
 181 \membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
 182
 183 \constfunc{wxString}{GetValue}{\void}
 184
 185 Gets the contents of the control.
 186
 187 \membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
 188
 189 \constfunc{bool}{IsModified}{\void}
 190
 191 Returns TRUE if the text has been modified.
 192
 193 \membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
 194
 195 \func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
 196
 197 Loads and displays the named file, if it exists.
 198
 199 \wxheading{Parameters}
 200
 201 \docparam{filename}{The filename of the file to load.}
 202
 203 \wxheading{Return value}
 204
 205 TRUE if successful, FALSE otherwise.
 206
 207 \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
 208
 209 \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
 210
 211 Default handler for character input.
 212
 213 \wxheading{Remarks}
 214
 215 It is possible to intercept character
 216 input by overriding this member. Call this function
 217 to let the default behaviour take place; not calling
 218 it results in the character being ignored. You can
 219 replace the {\it keyCode} member of {\it event} to
 220 translate keystrokes.
 221
 222 Note that Windows and Motif have different ways
 223 of implementing the default behaviour. In Windows,
 224 calling wxTextCtrl::OnChar immediately
 225 processes the character. In Motif,
 226 calling this function simply sets a flag
 227 to let default processing happen. This might affect
 228 the way in which you write your OnChar function
 229 on different platforms.
 230
 231 \wxheading{See also}
 232
 233 \helpref{wxKeyEvent}{wxkeyevent}
 234
 235 \membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
 236
 237 \func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
 238
 239 This event handler function implements default drag and drop behaviour, which
 240 is to load the first dropped file into the control.
 241
 242 \wxheading{Parameters}
 243
 244 \docparam{event}{The drop files event.}
 245
 246 \wxheading{See also}
 247
 248 \helpref{wxDropFilesEvent}{wxdropfilesevent}
 249
 250 \membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
 251
 252 \func{virtual void}{Paste}{\void}
 253
 254 Pastes text from the clipboard to the text item.
 255
 256 \membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
 257
 258 \constfunc{long}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
 259
 260 Converts given character and line position to a position.
 261
 262 \wxheading{Parameters}
 263
 264 \docparam{pos}{Position.}
 265
 266 \docparam{x}{Receives character position.}
 267
 268 \docparam{y}{Receives line position.}
 269
 270 \wxheading{See also}
 271
 272 \helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
 273
 274 \membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
 275
 276 \func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
 277
 278 Removes the text between the two positions.
 279
 280 \wxheading{Parameters}
 281
 282 \docparam{from}{The first position.}
 283
 284 \docparam{to}{The last position.}
 285
 286 \membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
 287
 288 \func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
 289
 290 Replaces the text between two positions with the given text.
 291
 292 \wxheading{Parameters}
 293
 294 \docparam{from}{The first position.}
 295
 296 \docparam{to}{The last position.}
 297
 298 \docparam{value}{The value to replace the existing text with.}
 299
 300 \membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
 301
 302 \func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
 303
 304 Saves the contents of the control in a text file.
 305
 306 \wxheading{Parameters}
 307
 308 \docparam{filename}{The name of file in which to save the text.}
 309
 310 \wxheading{Return value}
 311
 312 TRUE if the operation was successful, FALSE otherwise.
 313
 314 \membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
 315
 316 \func{virtual void}{SetEditable}{\param{const bool}{ editable}}
 317
 318 Makes the text item editable or read-only.
 319
 320 \wxheading{Parameters}
 321
 322 \docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
 323
 324 \membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
 325
 326 \func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
 327
 328 Sets the insertion point. Windows only. ??
 329
 330 \wxheading{Parameters}
 331
 332 \docparam{pos}{Position to set.}
 333
 334 \membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
 335
 336 \func{virtual void}{SetInsertionPointEnd}{\void}
 337
 338 Sets the insertion point at the end of the text control.
 339
 340 \membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
 341
 342 \func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
 343
 344 Selects the text between the two positions.
 345
 346 \wxheading{Parameters}
 347
 348 \docparam{from}{The first position.}
 349
 350 \docparam{to}{The last position.}
 351
 352 \membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
 353
 354 \func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
 355
 356 Sets the text value.
 357
 358 \wxheading{Parameters}
 359
 360 \docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
 361
 362 \membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
 363
 364 \func{void}{ShowPosition}{\param{long}{ pos}}
 365
 366 Makes the line containing the given position visible.
 367
 368 \wxheading{Parameters}
 369
 370 \docparam{pos}{The position that should be visible.}
 371
 372 \membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
 373
 374 \func{void}{WriteText}{\param{const wxString\& }{ text}}
 375
 376 Writes the text into the text control at the current position.
 377
 378 \wxheading{Parameters}
 379
 380 \docparam{text}{Text to write to the text control.}
 381
 382 \wxheading{Remarks}
 383
 384 Newlines in the text string
 385 are the only control characters allowed, and they will cause appropriate
 386 line breaks.  See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} for more convenient ways of writing to the
 387 window.
 388
 389 \membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
 390
 391 \func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
 392
 393 Converts the given character and line position to a position.
 394
 395 \wxheading{Parameters}
 396
 397 \docparam{x}{The character position.}
 398
 399 \docparam{y}{The line position.}
 400
 401 \wxheading{Return value}
 402
 403 The position value.
 404
 405 \membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
 406
 407 \func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
 408
 409 \func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
 410
 411 \func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
 412
 413 \func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
 414
 415 \func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
 416
 417 \func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
 418
 419 Operator definitions for writing to a text control, for example:
 420
 421 \begin{verbatim}
 422   wxTextCtrl *wnd = new wxTextCtrl(my_frame);
 423
 424   (*wnd) << "Welcome to text control number " << 1 << ".\n";
 425 \end{verbatim}
 426
 427