include/wx/univ/textctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/univ/textctrl.h
   3 // Purpose:     wxTextCtrl class
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     15.09.00
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2000 SciTech Software, Inc. (www.scitechsoft.com)
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_UNIV_TEXTCTRL_H_
  13 #define _WX_UNIV_TEXTCTRL_H_
  14
  15 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  16     #pragma interface "univtextctrl.h"
  17 #endif
  18
  19 class WXDLLEXPORT wxCaret;
  20 class WXDLLEXPORT wxTextCtrlCommandProcessor;
  21
  22 #include "wx/scrolwin.h"    // for wxScrollHelper
  23
  24 #include "wx/univ/inphand.h"
  25
  26 // ----------------------------------------------------------------------------
  27 // wxTextCtrl actions
  28 // ----------------------------------------------------------------------------
  29
  30 // cursor movement and also selection and delete operations
  31 #define wxACTION_TEXT_GOTO          _T("goto")  // to pos in numArg
  32 #define wxACTION_TEXT_FIRST         _T("first") // go to pos 0
  33 #define wxACTION_TEXT_LAST          _T("last")  // go to last pos
  34 #define wxACTION_TEXT_HOME          _T("home")
  35 #define wxACTION_TEXT_END           _T("end")
  36 #define wxACTION_TEXT_LEFT          _T("left")
  37 #define wxACTION_TEXT_RIGHT         _T("right")
  38 #define wxACTION_TEXT_UP            _T("up")
  39 #define wxACTION_TEXT_DOWN          _T("down")
  40 #define wxACTION_TEXT_WORD_LEFT     _T("wordleft")
  41 #define wxACTION_TEXT_WORD_RIGHT    _T("wordright")
  42 #define wxACTION_TEXT_PAGE_UP       _T("pageup")
  43 #define wxACTION_TEXT_PAGE_DOWN     _T("pagedown")
  44
  45 // clipboard operations
  46 #define wxACTION_TEXT_COPY          _T("copy")
  47 #define wxACTION_TEXT_CUT           _T("cut")
  48 #define wxACTION_TEXT_PASTE         _T("paste")
  49
  50 // insert text at the cursor position: the text is in strArg of PerformAction
  51 #define wxACTION_TEXT_INSERT        _T("insert")
  52
  53 // if the action starts with either of these prefixes and the rest of the
  54 // string is one of the movement commands, it means to select/delete text from
  55 // the current cursor position to the new one
  56 #define wxACTION_TEXT_PREFIX_SEL    _T("sel")
  57 #define wxACTION_TEXT_PREFIX_DEL    _T("del")
  58
  59 // mouse selection
  60 #define wxACTION_TEXT_ANCHOR_SEL    _T("anchorsel")
  61 #define wxACTION_TEXT_EXTEND_SEL    _T("extendsel")
  62 #define wxACTION_TEXT_SEL_WORD      _T("wordsel")
  63 #define wxACTION_TEXT_SEL_LINE      _T("linesel")
  64
  65 // undo or redo
  66 #define wxACTION_TEXT_UNDO          _T("undo")
  67 #define wxACTION_TEXT_REDO          _T("redo")
  68
  69 // ----------------------------------------------------------------------------
  70 // wxTextCtrl types
  71 // ----------------------------------------------------------------------------
  72
  73 // wxTextPos is the position in the text
  74 typedef long wxTextPos;
  75
  76 // wxTextCoord is the line or row number (which should have been unsigned but
  77 // is long for backwards compatibility)
  78 typedef long wxTextCoord;
  79
  80 // ----------------------------------------------------------------------------
  81 // wxTextCtrl::HitTest return values
  82 // ----------------------------------------------------------------------------
  83
  84 // the point asked is ...
  85 enum wxTextCtrlHitTestResult
  86 {
  87     wxTE_HT_BEFORE = -1,    // either to the left or upper
  88     wxTE_HT_ON_TEXT,        // directly on
  89     wxTE_HT_BELOW,          // below [the last line]
  90     wxTE_HT_BEYOND          // after [the end of line]
  91 };
  92 // ... the character returned
  93
  94 // ----------------------------------------------------------------------------
  95 // wxTextCtrl
  96 // ----------------------------------------------------------------------------
  97
  98 class WXDLLEXPORT wxTextCtrl : public wxTextCtrlBase, public wxScrollHelper
  99 {
 100 public:
 101     // creation
 102     // --------
 103
 104     wxTextCtrl() { Init(); }
 105
 106     wxTextCtrl(wxWindow *parent,
 107                wxWindowID id,
 108                const wxString& value = wxEmptyString,
 109                const wxPoint& pos = wxDefaultPosition,
 110                const wxSize& size = wxDefaultSize,
 111                long style = 0,
 112                const wxValidator& validator = wxDefaultValidator,
 113                const wxString& name = wxTextCtrlNameStr)
 114     {
 115         Init();
 116
 117         Create(parent, id, value, pos, size, style, validator, name);
 118     }
 119
 120     bool Create(wxWindow *parent,
 121                 wxWindowID id,
 122                 const wxString& value = wxEmptyString,
 123                 const wxPoint& pos = wxDefaultPosition,
 124                 const wxSize& size = wxDefaultSize,
 125                 long style = 0,
 126                 const wxValidator& validator = wxDefaultValidator,
 127                 const wxString& name = wxTextCtrlNameStr);
 128
 129     virtual ~wxTextCtrl();
 130
 131     // implement base class pure virtuals
 132     // ----------------------------------
 133
 134     virtual wxString GetValue() const;
 135     virtual void SetValue(const wxString& value);
 136
 137     virtual int GetLineLength(wxTextCoord lineNo) const;
 138     virtual wxString GetLineText(wxTextCoord lineNo) const;
 139     virtual int GetNumberOfLines() const;
 140
 141     virtual bool IsModified() const;
 142     virtual bool IsEditable() const;
 143
 144     // If the return values from and to are the same, there is no selection.
 145     virtual void GetSelection(wxTextPos* from, wxTextPos* to) const;
 146
 147     // operations
 148     // ----------
 149
 150     // editing
 151     virtual void Clear();
 152     virtual void Replace(wxTextPos from, wxTextPos to, const wxString& value);
 153     virtual void Remove(wxTextPos from, wxTextPos to);
 154
 155     // sets/clears the dirty flag
 156     virtual void MarkDirty();
 157     virtual void DiscardEdits();
 158
 159     // writing text inserts it at the current position, appending always
 160     // inserts it at the end
 161     virtual void WriteText(const wxString& text);
 162     virtual void AppendText(const wxString& text);
 163
 164     // translate between the position (which is just an index in the text ctrl
 165     // considering all its contents as a single strings) and (x, y) coordinates
 166     // which represent (logical, i.e. unwrapped) column and line.
 167     virtual wxTextPos XYToPosition(wxTextCoord x, wxTextCoord y) const;
 168     virtual bool PositionToXY(wxTextPos pos,
 169                               wxTextCoord *x, wxTextCoord *y) const;
 170
 171     // wxUniv-specific: find a screen position (in client coordinates) of the
 172     // given text position or of the caret
 173     bool PositionToLogicalXY(wxTextPos pos, wxCoord *x, wxCoord *y) const;
 174     bool PositionToDeviceXY(wxTextPos pos, wxCoord *x, wxCoord *y) const;
 175     wxPoint GetCaretPosition() const;
 176
 177     virtual void ShowPosition(wxTextPos pos);
 178
 179     // Clipboard operations
 180     virtual void Copy();
 181     virtual void Cut();
 182     virtual void Paste();
 183
 184     // Undo/redo
 185     virtual void Undo();
 186     virtual void Redo();
 187
 188     virtual bool CanUndo() const;
 189     virtual bool CanRedo() const;
 190
 191     // Insertion point
 192     virtual void SetInsertionPoint(wxTextPos pos);
 193     virtual void SetInsertionPointEnd();
 194     virtual wxTextPos GetInsertionPoint() const;
 195     virtual wxTextPos GetLastPosition() const;
 196
 197     virtual void SetSelection(wxTextPos from, wxTextPos to);
 198     virtual void SetEditable(bool editable);
 199
 200     // wxUniv-specific methods
 201     // -----------------------
 202
 203     // caret stuff
 204     virtual void ShowCaret(bool show = TRUE);
 205     void HideCaret() { ShowCaret(FALSE); }
 206     void CreateCaret(); // for the current font size
 207
 208     // helpers for cursor movement
 209     wxTextPos GetWordStart() const;
 210     wxTextPos GetWordEnd() const;
 211
 212     // selection helpers
 213     bool HasSelection() const
 214         { return m_selStart != -1 && m_selEnd > m_selStart; }
 215     void ClearSelection();
 216     void RemoveSelection();
 217     wxString GetSelectionText() const;
 218
 219     // find the character at this position, return 0 if the character is
 220     // really there, -1 if the point is before the beginning of the text/line
 221     // and the returned character is the first one to follow it or +1 if it the
 222     // position is beyond the end of line/text and the returned character is
 223     // the last one
 224     //
 225     // NB: pt is in device coords (not adjusted for the client area origin nor
 226     //     for the scrolling)
 227     wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
 228                                     wxTextCoord *col, wxTextCoord *row) const;
 229
 230     // find the character at this position in the given line, return value as
 231     // for HitTest()
 232     //
 233     // NB: x is the logical coord (client and unscrolled)
 234     wxTextCtrlHitTestResult HitTestLine(const wxString& line,
 235                                         wxCoord x,
 236                                         wxTextCoord *colOut) const;
 237
 238     // bring the given position into view
 239     void ShowHorzPosition(wxCoord pos);
 240
 241     // scroll the window horizontally so that the first character shown is in
 242     // position pos
 243     void ScrollText(wxTextCoord col);
 244
 245     // adjust the DC for horz text control scrolling too
 246     virtual void DoPrepareDC(wxDC& dc);
 247
 248     // implementation only from now on
 249     // -------------------------------
 250
 251     // override this to take into account our scrollbar-less scrolling
 252     virtual void CalcUnscrolledPosition(int x, int y, int *xx, int *yy) const;
 253     virtual void CalcScrolledPosition(int x, int y, int *xx, int *yy) const;
 254
 255     // set the right colours and border
 256     virtual bool IsContainerWindow() const { return TRUE; }
 257     virtual wxBorder GetDefaultBorder() const { return wxBORDER_SUNKEN; }
 258
 259     // perform an action
 260     virtual bool PerformAction(const wxControlAction& action,
 261                                long numArg = -1,
 262                                const wxString& strArg = wxEmptyString);
 263
 264     // override these methods to handle the caret
 265     virtual bool SetFont(const wxFont &font);
 266     virtual bool Enable(bool enable = TRUE);
 267
 268     // more readable flag testing methods
 269     bool IsPassword() const { return (GetWindowStyle() & wxTE_PASSWORD) != 0; }
 270     bool WrapLines() const
 271         { return !IsSingleLine() && !(GetWindowStyle() & wxHSCROLL); }
 272
 273     // only for wxStdTextCtrlInputHandler
 274     void RefreshSelection();
 275
 276 protected:
 277     // override base class methods
 278     virtual void DoDrawBorder(wxDC& dc, const wxRect& rect);
 279     virtual void DoDraw(wxControlRenderer *renderer);
 280
 281     // calc the size from the text extent
 282     virtual wxSize DoGetBestClientSize() const;
 283
 284     // common part of all ctors
 285     void Init();
 286
 287     // drawing
 288     // -------
 289
 290     // draw the text in the given rectangle
 291     void DoDrawTextInRect(wxDC& dc, const wxRect& rectUpdate);
 292
 293     // draw the line wrap marks in this rect
 294     void DoDrawLineWrapMarks(wxDC& dc, const wxRect& rectUpdate);
 295
 296     // line/row geometry calculations
 297     // ------------------------------
 298
 299     // get the extent (width) of the text
 300     wxCoord GetTextWidth(const wxString& text) const;
 301
 302     // get the logical text width (accounting for scrolling)
 303     wxCoord GetTotalWidth() const;
 304
 305     // get total number of rows (different from number of lines if the lines
 306     // can be wrapped)
 307     wxTextCoord GetRowCount() const;
 308
 309     // find the number of rows in this line (only if WrapLines())
 310     wxTextCoord GetRowsPerLine(wxTextCoord line) const;
 311
 312     // get the starting row of the given line
 313     wxTextCoord GetFirstRowOfLine(wxTextCoord line) const;
 314
 315     // get the row following this line
 316     wxTextCoord GetRowAfterLine(wxTextCoord line) const;
 317
 318     // refresh functions
 319     // -----------------
 320
 321     // the text area is the part of the window in which the text can be
 322     // displayed, i.e. part of it inside the margins and the real text area is
 323     // the area in which the text *is* currently displayed: for example, in the
 324     // multiline control case the text area can have extra space at the bottom
 325     // which is not tall enough for another line and which is then not included
 326     // into the real text area
 327     wxRect GetRealTextArea() const;
 328
 329     // refresh the text in the given (in logical coords) rect
 330     void RefreshTextRect(const wxRect& rect, bool textOnly = TRUE);
 331
 332     // refresh the line wrap marks for the given range of lines (inclusive)
 333     void RefreshLineWrapMarks(wxTextCoord rowFirst, wxTextCoord rowLast);
 334
 335     // refresh the text in the given range (in logical coords) of this line, if
 336     // width is 0, refresh to the end of line
 337     void RefreshPixelRange(wxTextCoord line, wxCoord start, wxCoord width);
 338
 339     // refresh the text in the given range (in text coords) in this line
 340     void RefreshColRange(wxTextCoord line, wxTextPos start, size_t count);
 341
 342     // refresh the text from in the given line range (inclusive)
 343     void RefreshLineRange(wxTextCoord lineFirst, wxTextCoord lineLast);
 344
 345     // refresh the text in the given range which can span multiple lines
 346     // (this method accepts arguments in any order)
 347     void RefreshTextRange(wxTextPos start, wxTextPos end);
 348
 349     // get the text to show: either the text itself or the text replaced with
 350     // starts for wxTE_PASSWORD control
 351     wxString GetTextToShow(const wxString& text) const;
 352
 353     // find the row in this line where the given position (counted from the
 354     // start of line) is
 355     wxTextCoord GetRowInLine(wxTextCoord line,
 356                              wxTextCoord col,
 357                              wxTextCoord *colRowStart = NULL) const;
 358
 359     // find the number of characters of a line before it wraps
 360     // (and optionally also the real width of the line)
 361     size_t GetPartOfWrappedLine(const wxChar* text,
 362                                 wxCoord *widthReal = NULL) const;
 363
 364     // get the start and end of the selection for this line: if the line is
 365     // outside the selection, both will be -1 and FALSE will be returned
 366     bool GetSelectedPartOfLine(wxTextCoord line,
 367                                wxTextPos *start, wxTextPos *end) const;
 368
 369     // update the text rect: the zone inside our client rect (its coords are
 370     // client coords) which contains the text
 371     void UpdateTextRect();
 372
 373     // calculate the last visible position
 374     void UpdateLastVisible();
 375
 376     // move caret to the given position unconditionally
 377     // (SetInsertionPoint() does nothing if the position didn't change)
 378     void DoSetInsertionPoint(wxTextPos pos);
 379
 380     // move caret to the new position without updating the display (for
 381     // internal use only)
 382     void MoveInsertionPoint(wxTextPos pos);
 383
 384     // set the caret to its initial (default) position
 385     void InitInsertionPoint();
 386
 387     // get the width of the longest line in pixels
 388     wxCoord GetMaxWidth() const;
 389
 390     // force recalculation of the max line width
 391     void RecalcMaxWidth();
 392
 393     // update the max width after the given line was modified
 394     void UpdateMaxWidth(wxTextCoord line);
 395
 396     // hit testing
 397     // -----------
 398
 399     // HitTest2() is more efficient than 2 consecutive HitTest()s with the same
 400     // line (i.e. y) and it also returns the offset of the starting position in
 401     // pixels
 402     //
 403     // as the last hack, this function accepts either logical or device (by
 404     // default) coords depending on devCoords flag
 405     wxTextCtrlHitTestResult HitTest2(wxCoord y,
 406                                      wxCoord x1,
 407                                      wxCoord x2,
 408                                      wxTextCoord *row,
 409                                      wxTextCoord *colStart,
 410                                      wxTextCoord *colEnd,
 411                                      wxTextCoord *colRowStart,
 412                                      bool devCoords = TRUE) const;
 413
 414     // HitTest() version which takes the logical text coordinates and not the
 415     // device ones
 416     wxTextCtrlHitTestResult HitTestLogical(const wxPoint& pos,
 417                                            wxTextCoord *col,
 418                                            wxTextCoord *row) const;
 419
 420     // get the line and the row in this line corresponding to the given row,
 421     // return TRUE if ok and FALSE if row is out of range
 422     //
 423     // NB: this function can only be called for controls which wrap lines
 424     bool GetLineAndRow(wxTextCoord row,
 425                        wxTextCoord *line,
 426                        wxTextCoord *rowInLine) const;
 427
 428     // get the height of one line (the same for all lines)
 429     wxCoord GetLineHeight() const
 430     {
 431         // this one should be already precalculated
 432         wxASSERT_MSG( m_heightLine != -1, _T("should have line height") );
 433
 434         return m_heightLine;
 435     }
 436
 437     // get the average char width
 438     wxCoord GetAverageWidth() const { return m_widthAvg; }
 439
 440     // recalc the line height and char width (to call when the font changes)
 441     void RecalcFontMetrics();
 442
 443     // vertical scrolling helpers
 444     // --------------------------
 445
 446     // all these functions are for multi line controls only
 447
 448     // get the number of visible lines
 449     size_t GetLinesPerPage() const;
 450
 451     // return the position above the cursor or INVALID_POS_VALUE
 452     wxTextPos GetPositionAbove();
 453
 454     // return the position below the cursor or INVALID_POS_VALUE
 455     wxTextPos GetPositionBelow();
 456
 457     // event handlers
 458     // --------------
 459     void OnChar(wxKeyEvent& event);
 460     void OnSize(wxSizeEvent& event);
 461
 462     // overrdie wxScrollHelper method to prevent (auto)scrolling beyond the end
 463     // of line
 464     virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
 465
 466     // return the struct containing control-type dependent data
 467     struct wxTextSingleLineData& SData() { return *m_data.sdata; }
 468     struct wxTextMultiLineData& MData() { return *m_data.mdata; }
 469     struct wxTextWrappedData& WData() { return *m_data.wdata; }
 470     const wxTextSingleLineData& SData() const { return *m_data.sdata; }
 471     const wxTextMultiLineData& MData() const { return *m_data.mdata; }
 472     const wxTextWrappedData& WData() const { return *m_data.wdata; }
 473
 474     // clipboard operations (unlike the versions without Do prefix, they have a
 475     // return code)
 476     bool DoCut();
 477     bool DoPaste();
 478
 479     // idle processing
 480     virtual void OnInternalIdle();
 481 private:
 482     // all these methods are for multiline text controls only
 483
 484     // update the scrollbars (only called from OnIdle)
 485     void UpdateScrollbars();
 486
 487     // get read only access to the lines of multiline control
 488     inline const wxArrayString& GetLines() const;
 489     inline size_t GetLineCount() const;
 490
 491     // replace a line (returns TRUE if the number of rows in thel ine changed)
 492     bool ReplaceLine(wxTextCoord line, const wxString& text);
 493
 494     // remove a line
 495     void RemoveLine(wxTextCoord line);
 496
 497     // insert a line at this position
 498     void InsertLine(wxTextCoord line, const wxString& text);
 499
 500     // calculate geometry of this line
 501     void LayoutLine(wxTextCoord line, class wxWrappedLineData& lineData) const;
 502
 503     // calculate geometry of all lines until the given one
 504     void LayoutLines(wxTextCoord lineLast) const;
 505
 506     // the initially specified control size
 507     wxSize m_sizeInitial;
 508
 509     // the global control text
 510     wxString m_value;
 511
 512     // current position
 513     wxTextPos m_curPos;
 514     wxTextCoord m_curCol,
 515                 m_curRow;
 516
 517     // last position (only used by GetLastPosition())
 518     wxTextPos m_posLast;
 519
 520     // selection
 521     wxTextPos m_selAnchor,
 522               m_selStart,
 523               m_selEnd;
 524
 525     // flags
 526     bool m_isModified:1,
 527          m_isEditable:1,
 528          m_hasCaret:1;
 529
 530     // the rectangle (in client coordinates) to draw text inside
 531     wxRect m_rectText;
 532
 533     // the height of one line (cached value of GetCharHeight)
 534     wxCoord m_heightLine;
 535
 536     // and the average char width (cached value of GetCharWidth)
 537     wxCoord m_widthAvg;
 538
 539     // we have some data which depends on the kind of control (single or multi
 540     // line)
 541     union
 542     {
 543         wxTextSingleLineData *sdata;
 544         wxTextMultiLineData *mdata;
 545         wxTextWrappedData *wdata;
 546         void *data;
 547     } m_data;
 548
 549     // the object to which we delegate our undo/redo implementation
 550     wxTextCtrlCommandProcessor *m_cmdProcessor;
 551
 552     DECLARE_EVENT_TABLE()
 553     DECLARE_DYNAMIC_CLASS(wxTextCtrl)
 554 };
 555
 556 // ----------------------------------------------------------------------------
 557 // wxStdTextCtrlInputHandler: this control handles only the mouse/kbd actions
 558 // common to Win32 and GTK, platform-specific things are implemented elsewhere
 559 // ----------------------------------------------------------------------------
 560
 561 class WXDLLEXPORT wxStdTextCtrlInputHandler : public wxStdInputHandler
 562 {
 563 public:
 564     wxStdTextCtrlInputHandler(wxInputHandler *inphand);
 565
 566     virtual bool HandleKey(wxInputConsumer *consumer,
 567                            const wxKeyEvent& event,
 568                            bool pressed);
 569     virtual bool HandleMouse(wxInputConsumer *consumer,
 570                              const wxMouseEvent& event);
 571     virtual bool HandleMouseMove(wxInputConsumer *consumer,
 572                                  const wxMouseEvent& event);
 573     virtual bool HandleFocus(wxInputConsumer *consumer, const wxFocusEvent& event);
 574
 575 protected:
 576     // get the position of the mouse click
 577     static wxTextPos HitTest(const wxTextCtrl *text, const wxPoint& pos);
 578
 579     // capture data
 580     wxTextCtrl *m_winCapture;
 581 };
 582
 583 #endif // _WX_UNIV_TEXTCTRL_H_
 584