interface/wx/scrolbar.h

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