interface/wx/scrolbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        scrolbar.h
   3 // Purpose:     interface of wxScrollBar
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxScrollBar
  11
  12     A wxScrollBar is a control that represents a horizontal or vertical scrollbar.
  13
  14     It is distinct from the two scrollbars that some windows provide automatically,
  15     but the two types of scrollbar share the way events are received.
  16
  17     @remarks
  18     A scrollbar has the following main attributes: range, thumb size, page size, and position.
  19     The range is the total number of units associated with the view represented by the scrollbar.
  20     For a table with 15 columns, the range would be 15.
  21     The thumb size is the number of units that are currently visible.
  22     For the table example, the window might be sized so that only 5 columns are
  23     currently visible, in which case the application would set the thumb size to 5.
  24     When the thumb size becomes the same as or greater than the range, the scrollbar
  25     will be automatically hidden on most platforms.
  26     The page size is the number of units that the scrollbar should scroll by,
  27     when 'paging' through the data. This value is normally the same as the thumb
  28     size length, because it is natural to assume that the visible window size defines a page.
  29     The scrollbar position is the current thumb position.
  30     Most applications will find it convenient to provide a function called AdjustScrollbars()
  31     which can be called initially, from an OnSize event handler, and whenever the
  32     application data changes in size. It will adjust the view, object and page
  33     size according to the size of the window and the size of the data.
  34
  35     @beginStyleTable
  36     @style{wxSB_HORIZONTAL}
  37            Specifies a horizontal scrollbar.
  38     @style{wxSB_VERTICAL}
  39            Specifies a vertical scrollbar.
  40     @endStyleTable
  41
  42     @beginEventTable{wxScrollEvent}
  43     You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting
  44     scroll events from controls, or EVT_SCROLL... macros without window IDs for
  45     intercepting scroll events from the receiving window -- except for this,
  46     the macros behave exactly the same.
  47     @event{EVT_SCROLL(func)}
  48         Process all scroll events.
  49     @event{EVT_SCROLL_TOP(func)}
  50         Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
  51     @event{EVT_SCROLL_BOTTOM(func)}
  52         Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
  53     @event{EVT_SCROLL_LINEUP(func)}
  54         Process wxEVT_SCROLL_LINEUP line up events.
  55     @event{EVT_SCROLL_LINEDOWN(func)}
  56         Process wxEVT_SCROLL_LINEDOWN line down events.
  57     @event{EVT_SCROLL_PAGEUP(func)}
  58         Process wxEVT_SCROLL_PAGEUP page up events.
  59     @event{EVT_SCROLL_PAGEDOWN(func)}
  60         Process wxEVT_SCROLL_PAGEDOWN page down events.
  61     @event{EVT_SCROLL_THUMBTRACK(func)}
  62         Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
  63         (frequent events sent as the user drags the thumbtrack).
  64     @event{EVT_SCROLL_THUMBRELEASE(func)}
  65         Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
  66     @event{EVT_SCROLL_CHANGED(func)}
  67         Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
  68     @event{EVT_COMMAND_SCROLL(id, func)}
  69         Process all scroll events.
  70     @event{EVT_COMMAND_SCROLL_TOP(id, func)}
  71         Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position).
  72     @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)}
  73         Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position).
  74     @event{EVT_COMMAND_SCROLL_LINEUP(id, func)}
  75         Process wxEVT_SCROLL_LINEUP line up events.
  76     @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)}
  77         Process wxEVT_SCROLL_LINEDOWN line down events.
  78     @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)}
  79         Process wxEVT_SCROLL_PAGEUP page up events.
  80     @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)}
  81         Process wxEVT_SCROLL_PAGEDOWN page down events.
  82     @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)}
  83         Process wxEVT_SCROLL_THUMBTRACK thumbtrack events
  84         (frequent events sent as the user drags the thumbtrack).
  85     @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)}
  86         Process wxEVT_SCROLL_THUMBRELEASE thumb release events.
  87     @event{EVT_COMMAND_SCROLL_CHANGED(func)}
  88         Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only).
  89     @endEventTable
  90
  91     @section scrollbar_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
  92
  93     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the
  94     thumb using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event
  95     is also followed by an EVT_SCROLL_CHANGED event).
  96
  97     The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change
  98     the thumb position, and when clicking next to the thumb
  99     (In all these cases the EVT_SCROLL_THUMBRELEASE event does not happen).
 100
 101     In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/moving has
 102     finished independently of the way it had started. Please see the widgets sample
 103     ("Slider" page) to see the difference between EVT_SCROLL_THUMBRELEASE and
 104     EVT_SCROLL_CHANGED in action.
 105
 106     @library{wxcore}
 107     @category{ctrl}
 108     @appearance{scrollbar.png}
 109
 110     @see @ref overview_scrolling, @ref overview_eventhandling, wxScrolled
 111 */
 112 class wxScrollBar : public wxControl
 113 {
 114 public:
 115     /**
 116       Default constructor
 117     */
 118     wxScrollBar();
 119
 120     /**
 121         Constructor, creating and showing a scrollbar.
 122
 123         @param parent
 124             Parent window. Must be non-@NULL.
 125         @param id
 126             Window identifier. The value wxID_ANY indicates a default value.
 127         @param pos
 128             Window position. If wxDefaultPosition is specified then a default
 129         position is chosen.
 130         @param size
 131             Window size. If wxDefaultSize is specified then a default size
 132         is chosen.
 133         @param style
 134             Window style. See wxScrollBar.
 135         @param validator
 136             Window validator.
 137         @param name
 138             Window name.
 139
 140         @see Create(), wxValidator
 141     */
 142     wxScrollBar(wxWindow* parent, wxWindowID id,
 143                 const wxPoint& pos = wxDefaultPosition,
 144                 const wxSize& size = wxDefaultSize,
 145                 long style = wxSB_HORIZONTAL,
 146                 const wxValidator& validator = wxDefaultValidator,
 147                 const wxString& name = "scrollBar");
 148
 149     /**
 150         Destructor, destroying the scrollbar.
 151     */
 152     virtual ~wxScrollBar();
 153
 154     /**
 155         Scrollbar creation function called by the scrollbar constructor.
 156         See wxScrollBar() for details.
 157     */
 158     bool Create(wxWindow* parent, wxWindowID id,
 159                 const wxPoint& pos = wxDefaultPosition,
 160                 const wxSize& size = wxDefaultSize,
 161                 long style = wxSB_HORIZONTAL,
 162                 const wxValidator& validator = wxDefaultValidator,
 163                 const wxString& name = "scrollBar");
 164
 165     /**
 166         Returns the page size of the scrollbar.
 167
 168         This is the number of scroll units that will be scrolled when the user
 169         pages up or down. Often it is the same as the thumb size.
 170
 171         @see SetScrollbar()
 172     */
 173     virtual int GetPageSize() const;
 174
 175     /**
 176         Returns the length of the scrollbar.
 177
 178         @see SetScrollbar()
 179     */
 180     virtual int GetRange() const;
 181
 182     /**
 183         Returns the current position of the scrollbar thumb.
 184
 185         @see SetThumbPosition()
 186     */
 187     virtual int GetThumbPosition() const;
 188
 189     /**
 190         Returns the thumb or 'view' size.
 191
 192         @see SetScrollbar()
 193     */
 194     virtual int GetThumbSize() const;
 195
 196     /**
 197         Sets the scrollbar properties.
 198
 199         @param position
 200             The position of the scrollbar in scroll units.
 201         @param thumbSize
 202             The size of the thumb, or visible portion of the scrollbar, in scroll units.
 203         @param range
 204             The maximum position of the scrollbar.
 205         @param pageSize
 206             The size of the page size in scroll units. This is the number of units
 207             the scrollbar will scroll when it is paged up or down.
 208             Often it is the same as the thumb size.
 209         @param refresh
 210             @true to redraw the scrollbar, @false otherwise.
 211
 212         @remarks
 213             Let's say you wish to display 50 lines of text, using the same
 214             font. The window is sized so that you can only see 16 lines at a time.
 215             You would use:
 216             @code
 217             scrollbar->SetScrollbar(0, 16, 50, 15);
 218             @endcode
 219             The page size is 1 less than the thumb size so that the last line of
 220             the previous page will be visible on the next page, to help orient the user.
 221             Note that with the window at this size, the thumb position can never
 222             go above 50 minus 16, or 34.
 223             You can determine how many lines are currently visible by dividing
 224             the current view size by the character height in pixels.
 225             When defining your own scrollbar behaviour, you will always need to
 226             recalculate the scrollbar settings when the window size changes.
 227             You could therefore put your scrollbar calculations and SetScrollbar()
 228             call into a function named AdjustScrollbars, which can be called
 229             initially and also from a wxSizeEvent event handler function.
 230     */
 231     virtual void SetScrollbar(int position, int thumbSize, int range,
 232                               int pageSize,
 233                               bool refresh = true);
 234
 235     /**
 236         Sets the position of the scrollbar.
 237
 238         @param viewStart
 239             The position of the scrollbar thumb.
 240
 241         @see GetThumbPosition()
 242     */
 243     virtual void SetThumbPosition(int viewStart);
 244 };
 245