1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: include/wx/vscroll.h 3 // Purpose: wxVScrolledWindow: generalization of wxScrolledWindow 4 // Author: Vadim Zeitlin 5 // Modified by: 6 // Created: 30.05.03 7 // RCS-ID: $Id: vscroll.h 38917 2006-04-26 00:17:52Z VZ $ 8 // Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org> 9 // Licence: wxWindows licence 10 ///////////////////////////////////////////////////////////////////////////// 11 12 #ifndef _WX_VSCROLL_H_ 13 #define _WX_VSCROLL_H_ 14 15 #include "wx/panel.h" // base class 16 17 // ---------------------------------------------------------------------------- 18 // wxVScrolledWindow 19 // ---------------------------------------------------------------------------- 20 21 /* 22 In the name of this class, "V" may stand for "variable" because it can be 23 used for scrolling lines of variable heights; "virtual" because it is not 24 necessary to know the heights of all lines in advance -- only those which 25 are shown on the screen need to be measured; or, even, "vertical" because 26 this class only supports scrolling in one direction currently (this could 27 and probably will change in the future however). 28 29 In any case, this is a generalization of the wxScrolledWindow class which 30 can be only used when all lines have the same height. It lacks some other 31 wxScrolledWindow features however, notably it currently lacks support for 32 horizontal scrolling; it can't scroll another window nor only a rectangle 33 of the window and not its entire client area. 34 */ 35 class WXDLLEXPORT wxVScrolledWindow : public wxPanel 36 { 37 public: 38 // constructors and such 39 // --------------------- 40 41 // default ctor, you must call Create() later wxVScrolledWindow()42 wxVScrolledWindow() { Init(); } 43 44 // normal ctor, no need to call Create() after this one 45 // 46 // note that wxVSCROLL is always automatically added to our style, there is 47 // no need to specify it explicitly 48 wxVScrolledWindow(wxWindow *parent, 49 wxWindowID id = wxID_ANY, 50 const wxPoint& pos = wxDefaultPosition, 51 const wxSize& size = wxDefaultSize, 52 long style = 0, 53 const wxString& name = wxPanelNameStr) 54 { 55 Init(); 56 57 (void)Create(parent, id, pos, size, style, name); 58 } 59 60 // same as the previous ctor but returns status code: true if ok 61 // 62 // just as with the ctor above, wxVSCROLL style is always used, there is no 63 // need to specify it 64 bool Create(wxWindow *parent, 65 wxWindowID id = wxID_ANY, 66 const wxPoint& pos = wxDefaultPosition, 67 const wxSize& size = wxDefaultSize, 68 long style = 0, 69 const wxString& name = wxPanelNameStr) 70 { 71 return wxPanel::Create(parent, id, pos, size, style | wxVSCROLL, name); 72 } 73 74 75 // operations 76 // ---------- 77 78 // set the number of lines the window contains: the derived class must 79 // provide the heights for all lines with indices up to the one given here 80 // in its OnGetLineHeight() 81 void SetLineCount(size_t count); 82 83 // scroll to the specified line: it will become the first visible line in 84 // the window 85 // 86 // return true if we scrolled the window, false if nothing was done 87 bool ScrollToLine(size_t line); 88 89 // scroll by the specified number of lines/pages 90 virtual bool ScrollLines(int lines); 91 virtual bool ScrollPages(int pages); 92 93 // redraw the specified line 94 virtual void RefreshLine(size_t line); 95 96 // redraw all lines in the specified range (inclusive) 97 virtual void RefreshLines(size_t from, size_t to); 98 99 // return the item at the specified (in physical coordinates) position or. 100 101 // wxNOT_FOUND if none, i.e. if it is below the last item 102 int HitTest(wxCoord x, wxCoord y) const; HitTest(const wxPoint & pt)103 int HitTest(const wxPoint& pt) const { return HitTest(pt.x, pt.y); } 104 105 // recalculate all our parameters and redisplay all lines 106 virtual void RefreshAll(); 107 108 109 // accessors 110 // --------- 111 112 // get the number of lines this window contains (previously set by 113 // SetLineCount()) GetLineCount()114 size_t GetLineCount() const { return m_lineMax; } 115 116 // get the first currently visible line GetVisibleBegin()117 size_t GetVisibleBegin() const { return m_lineFirst; } 118 119 // get the first currently visible line GetVisibleEnd()120 size_t GetVisibleEnd() const { return m_lineFirst + m_nVisible; } 121 122 // is this line currently visible? IsVisible(size_t line)123 bool IsVisible(size_t line) const 124 { return line >= GetVisibleBegin() && line < GetVisibleEnd(); } 125 126 127 // this is the same as GetVisibleBegin(), exists to match 128 // GetLastVisibleLine() and for backwards compatibility only GetFirstVisibleLine()129 size_t GetFirstVisibleLine() const { return m_lineFirst; } 130 131 // get the last currently visible line 132 // 133 // this function is unsafe as it returns (size_t)-1 (i.e. a huge positive 134 // number) if the control is empty, use GetVisibleEnd() instead, this one 135 // is kept for backwards compatibility GetLastVisibleLine()136 size_t GetLastVisibleLine() const { return GetVisibleEnd() - 1; } 137 138 // layout the children (including the sizer if needed) 139 virtual bool Layout(); 140 141 protected: 142 // this function must be overridden in the derived class and it should 143 // return the height of the given line in pixels 144 virtual wxCoord OnGetLineHeight(size_t n) const = 0; 145 146 // this function doesn't have to be overridden but it may be useful to do 147 // it if calculating the lines heights is a relatively expensive operation 148 // as it gives the user code a possibility to calculate several of them at 149 // once 150 // 151 // OnGetLinesHint() is normally called just before OnGetLineHeight() but you 152 // shouldn't rely on the latter being called for all lines in the interval 153 // specified here. It is also possible that OnGetLineHeight() will be 154 // called for the lines outside of this interval, so this is really just a 155 // hint, not a promise. 156 // 157 // finally note that lineMin is inclusive, while lineMax is exclusive, as 158 // usual OnGetLinesHint(size_t WXUNUSED (lineMin),size_t WXUNUSED (lineMax))159 virtual void OnGetLinesHint(size_t WXUNUSED(lineMin), 160 size_t WXUNUSED(lineMax)) const { } 161 162 // when the number of lines changes, we try to estimate the total height 163 // of all lines which is a rather expensive operation in terms of lines 164 // access, so if the user code may estimate the average height 165 // better/faster than we do, it should override this function to implement 166 // its own logic 167 // 168 // this function should return the best guess for the total height it may 169 // make 170 virtual wxCoord EstimateTotalHeight() const; 171 172 173 // the event handlers 174 void OnSize(wxSizeEvent& event); 175 void OnScroll(wxScrollWinEvent& event); 176 #if wxUSE_MOUSEWHEEL 177 void OnMouseWheel(wxMouseEvent& event); 178 #endif 179 180 // find the index of the line we need to show at the top of the window such 181 // that the last (fully or partially) visible line is the given one 182 size_t FindFirstFromBottom(size_t lineLast, bool fullyVisible = false); 183 184 // get the total height of the lines between lineMin (inclusive) and 185 // lineMax (exclusive) 186 wxCoord GetLinesHeight(size_t lineMin, size_t lineMax) const; 187 188 // update the thumb size shown by the scrollbar 189 void UpdateScrollbar(); 190 191 // remove the scrollbar completely because we don't need it 192 void RemoveScrollbar(); 193 194 private: 195 // common part of all ctors 196 void Init(); 197 198 199 // the total number of (logical) lines 200 size_t m_lineMax; 201 202 // the total (estimated) height 203 wxCoord m_heightTotal; 204 205 // the first currently visible line 206 size_t m_lineFirst; 207 208 // the number of currently visible lines (including the last, possibly only 209 // partly, visible one) 210 size_t m_nVisible; 211 212 // accumulated mouse wheel rotation 213 #if wxUSE_MOUSEWHEEL 214 int m_sumWheelRotation; 215 #endif 216 217 DECLARE_EVENT_TABLE() 218 DECLARE_NO_COPY_CLASS(wxVScrolledWindow) 219 DECLARE_ABSTRACT_CLASS(wxVScrolledWindow) 220 }; 221 222 #endif // _WX_VSCROLL_H_ 223 224