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 licence
   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     @beginEventEmissionTable{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_events, 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.
 129             If ::wxDefaultPosition is specified then a default position is chosen.
 130         @param size
 131             Window size.
 132             If ::wxDefaultSize is specified then a default size 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 = wxScrollBarNameStr);
 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, long style = wxSB_HORIZONTAL,
 161                 const wxValidator& validator = wxDefaultValidator,
 162                 const wxString& name = wxScrollBarNameStr);
 163
 164     /**
 165         Returns the page size of the scrollbar.
 166
 167         This is the number of scroll units that will be scrolled when the user
 168         pages up or down. Often it is the same as the thumb size.
 169
 170         @see SetScrollbar()
 171     */
 172     virtual int GetPageSize() const;
 173
 174     /**
 175         Returns the length of the scrollbar.
 176
 177         @see SetScrollbar()
 178     */
 179     virtual int GetRange() const;
 180
 181     /**
 182         Returns the current position of the scrollbar thumb.
 183
 184         @see SetThumbPosition()
 185     */
 186     virtual int GetThumbPosition() const;
 187
 188     /**
 189         Returns the thumb or 'view' size.
 190
 191         @see SetScrollbar()
 192     */
 193     virtual int GetThumbSize() const;
 194
 195     /**
 196         Sets the scrollbar properties.
 197
 198         @param position
 199             The position of the scrollbar in scroll units.
 200         @param thumbSize
 201             The size of the thumb, or visible portion of the scrollbar, in scroll units.
 202         @param range
 203             The maximum position of the scrollbar.
 204         @param pageSize
 205             The size of the page size in scroll units. This is the number of units
 206             the scrollbar will scroll when it is paged up or down.
 207             Often it is the same as the thumb size.
 208         @param refresh
 209             @true to redraw the scrollbar, @false otherwise.
 210
 211         @remarks
 212             Let's say you wish to display 50 lines of text, using the same
 213             font. The window is sized so that you can only see 16 lines at a time.
 214             You would use:
 215             @code
 216             scrollbar->SetScrollbar(0, 16, 50, 15);
 217             @endcode
 218             The page size is 1 less than the thumb size so that the last line of
 219             the previous page will be visible on the next page, to help orient the user.
 220             Note that with the window at this size, the thumb position can never
 221             go above 50 minus 16, or 34.
 222             You can determine how many lines are currently visible by dividing
 223             the current view size by the character height in pixels.
 224             When defining your own scrollbar behaviour, you will always need to
 225             recalculate the scrollbar settings when the window size changes.
 226             You could therefore put your scrollbar calculations and SetScrollbar()
 227             call into a function named AdjustScrollbars, which can be called
 228             initially and also from a wxSizeEvent event handler function.
 229     */
 230     virtual void SetScrollbar(int position, int thumbSize, int range,
 231                               int pageSize,
 232                               bool refresh = true);
 233
 234     /**
 235         Sets the position of the scrollbar.
 236
 237         @param viewStart
 238             The position of the scrollbar thumb.
 239
 240         @see GetThumbPosition()
 241     */
 242     virtual void SetThumbPosition(int viewStart);
 243 };
 244