include/wx/vscroll.h

   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$
   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
  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;
 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())
 114     size_t GetLineCount() const { return m_lineMax; }
 115
 116     // get the first currently visible line
 117     size_t GetVisibleBegin() const { return m_lineFirst; }
 118
 119     // get the first currently visible line
 120     size_t GetVisibleEnd() const { return m_lineFirst + m_nVisible; }
 121
 122     // is this line currently visible?
 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
 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
 136     size_t GetLastVisibleLine() const { return GetVisibleEnd() - 1; }
 137
 138
 139 protected:
 140     // this function must be overridden in the derived class and it should
 141     // return the height of the given line in pixels
 142     virtual wxCoord OnGetLineHeight(size_t n) const = 0;
 143
 144     // this function doesn't have to be overridden but it may be useful to do
 145     // it if calculating the lines heights is a relatively expensive operation
 146     // as it gives the user code a possibility to calculate several of them at
 147     // once
 148     //
 149     // OnGetLinesHint() is normally called just before OnGetLineHeight() but you
 150     // shouldn't rely on the latter being called for all lines in the interval
 151     // specified here. It is also possible that OnGetLineHeight() will be
 152     // called for the lines outside of this interval, so this is really just a
 153     // hint, not a promise.
 154     //
 155     // finally note that lineMin is inclusive, while lineMax is exclusive, as
 156     // usual
 157     virtual void OnGetLinesHint(size_t WXUNUSED(lineMin),
 158                                 size_t WXUNUSED(lineMax)) const { }
 159
 160     // when the number of lines changes, we try to estimate the total height
 161     // of all lines which is a rather expensive operation in terms of lines
 162     // access, so if the user code may estimate the average height
 163     // better/faster than we do, it should override this function to implement
 164     // its own logic
 165     //
 166     // this function should return the best guess for the total height it may
 167     // make
 168     virtual wxCoord EstimateTotalHeight() const;
 169
 170
 171     // the event handlers
 172     void OnSize(wxSizeEvent& event);
 173     void OnScroll(wxScrollWinEvent& event);
 174 #if wxUSE_MOUSEWHEEL
 175     void OnMouseWheel(wxMouseEvent& event);
 176 #endif
 177
 178     // find the index of the line we need to show at the top of the window such
 179     // that the last (fully or partially) visible line is the given one
 180     size_t FindFirstFromBottom(size_t lineLast, bool fullyVisible = false);
 181
 182     // get the total height of the lines between lineMin (inclusive) and
 183     // lineMax (exclusive)
 184     wxCoord GetLinesHeight(size_t lineMin, size_t lineMax) const;
 185
 186     // update the thumb size shown by the scrollbar
 187     void UpdateScrollbar();
 188
 189 private:
 190     // common part of all ctors
 191     void Init();
 192
 193
 194     // the total number of (logical) lines
 195     size_t m_lineMax;
 196
 197     // the total (estimated) height
 198     wxCoord m_heightTotal;
 199
 200     // the first currently visible line
 201     size_t m_lineFirst;
 202
 203     // the number of currently visible lines (including the last, possibly only
 204     // partly, visible one)
 205     size_t m_nVisible;
 206
 207     // accumulated mouse wheel rotation
 208 #if wxUSE_MOUSEWHEEL
 209     int m_sumWheelRotation;
 210 #endif
 211
 212     DECLARE_EVENT_TABLE()
 213     DECLARE_NO_COPY_CLASS(wxVScrolledWindow)
 214     DECLARE_ABSTRACT_CLASS(wxVScrolledWindow)
 215 };
 216
 217 #endif // _WX_VSCROLL_H_
 218