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