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