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