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@wxwindows.org>
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_VSCROLL_H_
  13 #define _WX_VSCROLL_H_
  14
  15 #if defined(__GNUG__) && !defined(__APPLE__)
  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     void RefreshLine(size_t line);
  99
 100     // redraw all lines in the specified range (inclusive)
 101     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 GetFirstVisibleLine() const { return m_lineFirst; }
 122
 123     // get the last currently visible line
 124     size_t GetLastVisibleLine() const { return m_lineFirst + m_nVisible - 1; }
 125
 126     // is this line currently visible?
 127     bool IsVisible(size_t line) const
 128         { return line >= m_lineFirst && line <= GetLastVisibleLine(); }
 129
 130
 131 protected:
 132     // this function must be overridden in the derived class and it should
 133     // return the height of the given line in pixels
 134     virtual wxCoord OnGetLineHeight(size_t n) const = 0;
 135
 136     // this function doesn't have to be overridden but it may be useful to do
 137     // it if calculating the lines heights is a relatively expensive operation
 138     // as it gives the user code a possibility to calculate several of them at
 139     // once
 140     //
 141     // OnGetLinesHint() is normally called just before OnGetLineHeight() but you
 142     // shouldn't rely on the latter being called for all lines in the interval
 143     // specified here. It is also possible that OnGetLineHeight() will be
 144     // called for the lines outside of this interval, so this is really just a
 145     // hint, not a promise.
 146     //
 147     // finally note that lineMin is inclusive, while lineMax is exclusive, as
 148     // usual
 149     virtual void OnGetLinesHint(size_t lineMin, size_t lineMax) const { }
 150
 151     // when the number of lines changes, we try to estimate the total height
 152     // of all lines which is a rather expensive operation in terms of lines
 153     // access, so if the user code may estimate the average height
 154     // better/faster than we do, it should override this function to implement
 155     // its own logic
 156     //
 157     // this function should return the best guess for the total height it may
 158     // make
 159     virtual wxCoord EstimateTotalHeight() const;
 160
 161
 162     // the event handlers
 163     void OnSize(wxSizeEvent& event);
 164     void OnScroll(wxScrollWinEvent& event);
 165
 166     // find the index of the line we need to show at the top of the window such
 167     // that the last (fully or partially) visible line is the given one
 168     size_t FindFirstFromBottom(size_t lineLast, bool fullyVisible = false);
 169
 170     // get the total height of the lines between lineMin (inclusive) and
 171     // lineMax (exclusive)
 172     wxCoord GetLinesHeight(size_t lineMin, size_t lineMax) const;
 173
 174     // update the thumb size shown by the scrollbar
 175     void UpdateScrollbar();
 176
 177 private:
 178     // common part of all ctors
 179     void Init();
 180
 181
 182     // the total number of (logical) lines
 183     size_t m_lineMax;
 184
 185     // the total (estimated) height
 186     wxCoord m_heightTotal;
 187
 188     // the first currently visible line
 189     size_t m_lineFirst;
 190
 191     // the number of currently visible lines (including the last, possibly only
 192     // partly, visible one)
 193     size_t m_nVisible;
 194
 195
 196     DECLARE_EVENT_TABLE()
 197 };
 198
 199 #endif // _WX_VSCROLL_H_
 200