interface/scrolbar.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        scrolbar.h
   3 // Purpose:     documentation for wxScrollBar class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxScrollBar
  11     @wxheader{scrolbar.h}
  12
  13     A wxScrollBar is a control that represents a horizontal or
  14     vertical scrollbar. It is distinct from the two scrollbars that some windows
  15     provide automatically, but the two types of scrollbar share the way
  16     events are received.
  17
  18     @beginStyleTable
  19     @style{wxSB_HORIZONTAL}:
  20            Specifies a horizontal scrollbar.
  21     @style{wxSB_VERTICAL}:
  22            Specifies a vertical scrollbar.
  23     @endStyleTable
  24
  25     @library{wxcore}
  26     @category{ctrl}
  27     @appearance{scrollbar.png}
  28
  29     @seealso
  30     @ref overview_scrollingoverview "Scrolling overview", @ref
  31     overview_eventhandlingoverview "Event handling overview", wxScrolledWindow
  32 */
  33 class wxScrollBar : public wxControl
  34 {
  35 public:
  36     //@{
  37     /**
  38         Constructor, creating and showing a scrollbar.
  39
  40         @param parent
  41         Parent window. Must be non-@NULL.
  42
  43         @param id
  44         Window identifier. The value wxID_ANY indicates a default value.
  45
  46         @param pos
  47         Window position. If wxDefaultPosition is specified then a default position
  48         is chosen.
  49
  50         @param size
  51         Window size. If wxDefaultSize is specified then a default size is
  52         chosen.
  53
  54         @param style
  55         Window style. See wxScrollBar.
  56
  57         @param validator
  58         Window validator.
  59
  60         @param name
  61         Window name.
  62
  63         @sa Create(), wxValidator
  64     */
  65     wxScrollBar();
  66     wxScrollBar(wxWindow* parent, wxWindowID id,
  67                 const wxPoint& pos = wxDefaultPosition,
  68                 const wxSize& size = wxDefaultSize,
  69                 long style = wxSB_HORIZONTAL,
  70                 const wxValidator& validator = wxDefaultValidator,
  71                 const wxString& name = "scrollBar");
  72     //@}
  73
  74     /**
  75         Destructor, destroying the scrollbar.
  76     */
  77     ~wxScrollBar();
  78
  79     /**
  80         Scrollbar creation function called by the scrollbar constructor.
  81         See wxScrollBar() for details.
  82     */
  83     bool Create(wxWindow* parent, wxWindowID id,
  84                 const wxPoint& pos = wxDefaultPosition,
  85                 const wxSize& size = wxDefaultSize,
  86                 long style = wxSB_HORIZONTAL,
  87                 const wxValidator& validator = wxDefaultValidator,
  88                 const wxString& name = "scrollBar");
  89
  90     /**
  91         Returns the page size of the scrollbar. This is the number of scroll units
  92         that will be scrolled when the user pages up or down. Often it is the
  93         same as the thumb size.
  94
  95         @sa SetScrollbar()
  96     */
  97     int GetPageSize();
  98
  99     /**
 100         Returns the length of the scrollbar.
 101
 102         @sa SetScrollbar()
 103     */
 104     int GetRange();
 105
 106     /**
 107         Returns the current position of the scrollbar thumb.
 108
 109         @sa SetThumbPosition()
 110     */
 111     int GetThumbPosition();
 112
 113     /**
 114         Returns the thumb or 'view' size.
 115
 116         @sa SetScrollbar()
 117     */
 118     int GetThumbSize();
 119
 120     /**
 121         Sets the scrollbar properties.
 122
 123         @param position
 124         The position of the scrollbar in scroll units.
 125
 126         @param thumbSize
 127         The size of the thumb, or visible portion of the scrollbar, in scroll units.
 128
 129         @param range
 130         The maximum position of the scrollbar.
 131
 132         @param pageSize
 133         The size of the page size in scroll units. This is the number of units
 134         the scrollbar will scroll when it is paged up or down. Often it is the same as
 135         the thumb size.
 136
 137         @param refresh
 138         @true to redraw the scrollbar, @false otherwise.
 139
 140         @remarks Let's say you wish to display 50 lines of text, using the same
 141                    font. The window is sized so that you can only see 16
 142                    lines at a time.
 143     */
 144     virtual void SetScrollbar(int position, int thumbSize, int range,
 145                               int pageSize,
 146                               bool refresh = @true);
 147
 148     /**
 149         Sets the position of the scrollbar.
 150
 151         @param viewStart
 152         The position of the scrollbar thumb.
 153
 154         @sa GetThumbPosition()
 155     */
 156     void SetThumbPosition(int viewStart);
 157 };