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, 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         @param id
  43             Window identifier. The value wxID_ANY indicates a default value.
  44         @param pos
  45             Window position. If wxDefaultPosition is specified then a default
  46         position is chosen.
  47         @param size
  48             Window size. If wxDefaultSize is specified then a default size
  49         is chosen.
  50         @param style
  51             Window style. See wxScrollBar.
  52         @param validator
  53             Window validator.
  54         @param name
  55             Window name.
  56
  57         @see Create(), wxValidator
  58     */
  59     wxScrollBar();
  60     wxScrollBar(wxWindow* parent, wxWindowID id,
  61                 const wxPoint& pos = wxDefaultPosition,
  62                 const wxSize& size = wxDefaultSize,
  63                 long style = wxSB_HORIZONTAL,
  64                 const wxValidator& validator = wxDefaultValidator,
  65                 const wxString& name = "scrollBar");
  66     //@}
  67
  68     /**
  69         Destructor, destroying the scrollbar.
  70     */
  71     ~wxScrollBar();
  72
  73     /**
  74         Scrollbar creation function called by the scrollbar constructor.
  75         See wxScrollBar() for details.
  76     */
  77     bool Create(wxWindow* parent, wxWindowID id,
  78                 const wxPoint& pos = wxDefaultPosition,
  79                 const wxSize& size = wxDefaultSize,
  80                 long style = wxSB_HORIZONTAL,
  81                 const wxValidator& validator = wxDefaultValidator,
  82                 const wxString& name = "scrollBar");
  83
  84     /**
  85         Returns the page size of the scrollbar. This is the number of scroll units
  86         that will be scrolled when the user pages up or down. Often it is the
  87         same as the thumb size.
  88
  89         @see SetScrollbar()
  90     */
  91     int GetPageSize() const;
  92
  93     /**
  94         Returns the length of the scrollbar.
  95
  96         @see SetScrollbar()
  97     */
  98     int GetRange() const;
  99
 100     /**
 101         Returns the current position of the scrollbar thumb.
 102
 103         @see SetThumbPosition()
 104     */
 105     int GetThumbPosition() const;
 106
 107     /**
 108         Returns the thumb or 'view' size.
 109
 110         @see SetScrollbar()
 111     */
 112     int GetThumbSize() const;
 113
 114     /**
 115         Sets the scrollbar properties.
 116
 117         @param position
 118             The position of the scrollbar in scroll units.
 119         @param thumbSize
 120             The size of the thumb, or visible portion of the scrollbar, in scroll units.
 121         @param range
 122             The maximum position of the scrollbar.
 123         @param pageSize
 124             The size of the page size in scroll units. This is the number of units
 125             the scrollbar will scroll when it is paged up or down. Often it is the same
 126         as
 127             the thumb size.
 128         @param refresh
 129             @true to redraw the scrollbar, @false otherwise.
 130
 131         @remarks Let's say you wish to display 50 lines of text, using the same
 132                  font. The window is sized so that you can only see 16
 133                  lines at a time.
 134     */
 135     virtual void SetScrollbar(int position, int thumbSize, int range,
 136                               int pageSize,
 137                               bool refresh = true);
 138
 139     /**
 140         Sets the position of the scrollbar.
 141
 142         @param viewStart
 143             The position of the scrollbar thumb.
 144
 145         @see GetThumbPosition()
 146     */
 147     void SetThumbPosition(int viewStart);
 148 };