docs/latex/wx/scrolbar.tex

   1 \section{\class{wxScrollBar}}\label{wxscrollbar}
   2
   3 A wxScrollBar is a control that represents a horizontal or
   4 vertical scrollbar. It is distinct from the two scrollbars that some windows
   5 provide automatically, but the two types of scrollbar share the way
   6 events are received.
   7
   8 \wxheading{Derived from}
   9
  10 \helpref{wxControl}{wxcontrol}\\
  11 \helpref{wxWindow}{wxwindow}\\
  12 \helpref{wxEvtHandler}{wxevthandler}\\
  13 \helpref{wxObject}{wxobject}
  14
  15 \wxheading{Include files}
  16
  17 <wx/scrolbar.h>
  18
  19 \wxheading{Remarks}
  20
  21 A scrollbar has the following main attributes: {\it range}, {\it thumb size}, {\it page size}, and {\it position}.
  22
  23 The range is the total number of units associated with the view represented by the scrollbar.
  24 For a table with 15 columns, the range would be 15.
  25
  26 The thumb size is the number of units that are currently visible. For the table example, the window
  27 might be sized so that only 5 columns are currently visible, in which case the application would
  28 set the thumb size to 5. When the thumb size becomes the same as or greater than the range,
  29 the scrollbar will be automatically hidden on most platforms.
  30
  31 The page size is the number of units that the scrollbar should scroll by, when `paging' through
  32 the data. This value is normally the same as the thumb size length, because
  33 it is natural to assume that the visible window size defines a page.
  34
  35 The scrollbar position is the current thumb position.
  36
  37 Most applications will find it convenient to provide a function called {\bf AdjustScrollbars} which can
  38 be called initially, from an {\bf OnSize} event handler, and whenever the application data
  39 changes in size. It will adjust the view, object and page size according
  40 to the size of the window and the size of the data.
  41
  42 \wxheading{Window styles}
  43
  44 \twocolwidtha{5cm}
  45 \begin{twocollist}\itemsep=0pt
  46 \twocolitem{\windowstyle{wxSB\_HORIZONTAL}}{Specifies a horizontal scrollbar.}
  47 \twocolitem{\windowstyle{wxSB\_VERTICAL}}{Specifies a vertical scrollbar.}
  48 \end{twocollist}
  49
  50 See also \helpref{window styles overview}{windowstyles}.
  51
  52 \input scrolevt.inc
  53
  54 \wxheading{See also}
  55
  56 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
  57 \helpref{Event handling overview}{eventhandlingoverview},\rtfsp
  58 \helpref{wxScrolledWindow}{wxscrolledwindow}
  59
  60 \latexignore{\rtfignore{\wxheading{Members}}}
  61
  62 \membersection{wxScrollBar::wxScrollBar}\label{wxscrollbarconstr}
  63
  64 \func{}{wxScrollBar}{\void}
  65
  66 Default constructor.
  67
  68 \func{}{wxScrollBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
  69 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  70 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
  71 \param{const wxString\& }{name = ``scrollBar"}}
  72
  73 Constructor, creating and showing a scrollbar.
  74
  75 \wxheading{Parameters}
  76
  77 \docparam{parent}{Parent window. Must not be NULL.}
  78
  79 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  80
  81 \docparam{pos}{Window position. If the position (-1, -1) is specified then a default position is chosen.}
  82
  83 \docparam{size}{Window size. If the default size (-1, -1) is specified then a default size is chosen.}
  84
  85 \docparam{style}{Window style. See \helpref{wxScrollBar}{wxscrollbar}.}
  86
  87 \docparam{validator}{Window validator.}
  88
  89 \docparam{name}{Window name.}
  90
  91 \wxheading{See also}
  92
  93 \helpref{wxScrollBar::Create}{wxscrollbarcreate}, \helpref{wxValidator}{wxvalidator}
  94
  95 \membersection{wxScrollBar::\destruct{wxScrollBar}}
  96
  97 \func{void}{\destruct{wxScrollBar}}{\void}
  98
  99 Destructor, destroying the scrollbar.
 100
 101 \membersection{wxScrollBar::Create}\label{wxscrollbarcreate}
 102
 103 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
 104 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 105 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
 106 \param{const wxString\& }{name = ``scrollBar"}}
 107
 108 Scrollbar creation function called by the scrollbar constructor.
 109 See \helpref{wxScrollBar::wxScrollBar}{wxscrollbarconstr} for details.
 110
 111 \membersection{wxScrollBar::GetRange}\label{wxscrollbargetrange}
 112
 113 \constfunc{int}{GetRange}{\void}
 114
 115 Returns the length of the scrollbar.
 116
 117 \wxheading{See also}
 118
 119 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 120
 121 \membersection{wxScrollBar::GetPageSize}\label{wxscrollbargetpagesize}
 122
 123 \constfunc{int}{GetPageSize}{\void}
 124
 125 Returns the page size of the scrollbar. This is the number of scroll units
 126 that will be scrolled when the user pages up or down. Often it is the
 127 same as the thumb size.
 128
 129 \wxheading{See also}
 130
 131 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 132
 133 \membersection{wxScrollBar::GetThumbPosition}\label{wxscrollbargetthumbposition}
 134
 135 \constfunc{int}{GetThumbPosition}{\void}
 136
 137 Returns the current position of the scrollbar thumb.
 138
 139 \wxheading{See also}
 140
 141 \helpref{wxScrollBar::SetThumbPosition}{wxscrollbarsetthumbposition}
 142
 143 \membersection{wxScrollBar::GetThumbLength}\label{wxscrollbargetthumblength}
 144
 145 \constfunc{int}{GetThumbLength}{\void}
 146
 147 Returns the thumb or `view' size.
 148
 149 \wxheading{See also}
 150
 151 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 152
 153 \begin{comment}
 154 \membersection{wxScrollBar::SetObjectLength}\label{wxscrollbarsetobjectlength}
 155
 156 \func{void}{SetObjectLength}{\param{int}{ objectLength}}
 157
 158 Sets the object length for the scrollbar. This is the total object size (virtual size). You must
 159 call \helpref{SetViewLength}{wxscrollbarsetviewlength} {\it before} calling SetObjectLength.
 160
 161 \wxheading{Parameters}
 162
 163 \docparam{objectLength}{The object length of the scrollbar.}
 164
 165 \wxheading{Remarks}
 166
 167 Example: you are implementing scrollbars on a text window, where text lines have a maximum width
 168 of 100 characters. Your text window has a current width of 60 characters. So the view length is 60,
 169 and the object length is 100. The scrollbar will then enable you to scroll to see the other 40 characters.
 170
 171 You will need to call {\bf SetViewLength} and {\bf SetObjectLength} whenever there
 172 is a change in the size of the window (the view size) or the size of the
 173 contents (the object length).
 174
 175 \wxheading{See also}
 176
 177 \helpref{wxScrollBar::GetObjectLength}{wxscrollbargetobjectlength}
 178
 179 \membersection{wxScrollBar::SetPageSize}\label{wxscrollbarsetpagesize}
 180
 181 \func{void}{SetPageSize}{\param{int}{ pageSize}}
 182
 183 Sets the page size for the scrollbar. This is the number of scroll units which are scrolled when the
 184 user pages down (clicks on the scrollbar outside the thumbtrack area).
 185
 186 \wxheading{Parameters}
 187
 188 \docparam{pageSize}{The page size in scroll units.}
 189
 190 \wxheading{Remarks}
 191
 192 At present, this needs to be called {\it before} other set functions.
 193
 194 \wxheading{See also}
 195
 196 \helpref{wxScrollBar::GetPageSize}{wxscrollbargetpagesize}
 197 \end{comment}
 198
 199 \membersection{wxScrollBar::SetThumbPosition}\label{wxscrollbarsetthumbposition}
 200
 201 \func{void}{SetThumbPosition}{\param{int}{ viewStart}}
 202
 203 Sets the position of the scrollbar.
 204
 205 \wxheading{Parameters}
 206
 207 \docparam{viewStart}{The position of the scrollbar thumb.}
 208
 209 \wxheading{See also}
 210
 211 \helpref{wxScrollBar::GetThumbPosition}{wxscrollbargetthumbposition}
 212
 213 \membersection{wxScrollBar::SetScrollbar}\label{wxscrollbarsetscrollbar}
 214
 215 \func{virtual void}{SetScrollbar}{\param{int }{position},\rtfsp
 216 \param{int }{thumbSize}, \param{int }{range},\rtfsp
 217 \param{int }{pageSize},\rtfsp
 218 \param{const bool }{refresh = true}}
 219
 220 Sets the scrollbar properties.
 221
 222 \wxheading{Parameters}
 223
 224 \docparam{position}{The position of the scrollbar in scroll units.}
 225
 226 \docparam{thumbSize}{The size of the thumb, or visible portion of the scrollbar, in scroll units.}
 227
 228 \docparam{range}{The maximum position of the scrollbar.}
 229
 230 \docparam{pageSize}{The size of the page size in scroll units. This is the number of units
 231 the scrollbar will scroll when it is paged up or down. Often it is the same as
 232 the thumb size.}
 233
 234 \docparam{refresh}{true to redraw the scrollbar, false otherwise.}
 235
 236 \wxheading{Remarks}
 237
 238 Let's say you wish to display 50 lines of text, using the same font.
 239 The window is sized so that you can only see 16 lines at a time.
 240
 241 You would use:
 242
 243 {\small%
 244 \begin{verbatim}
 245   scrollbar->SetScrollbar(0, 16, 50, 15);
 246 \end{verbatim}
 247 }
 248
 249 The page size is 1 less than the thumb size so that the last line of the previous
 250 page will be visible on the next page, to help orient the user.
 251
 252 Note that with the window at this size, the thumb position can never go
 253 above 50 minus 16, or 34.
 254
 255 You can determine how many lines are currently visible by dividing the current view
 256 size by the character height in pixels.
 257
 258 When defining your own scrollbar behaviour, you will always need to recalculate
 259 the scrollbar settings when the window size changes. You could therefore put your
 260 scrollbar calculations and SetScrollbar
 261 call into a function named AdjustScrollbars, which can be called initially and also
 262 from a \helpref{wxSizeEvent}{wxsizeevent} event handler function.
 263
 264 \wxheading{See also}
 265
 266 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
 267 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 268
 269 \begin{comment}
 270 \membersection{wxScrollBar::SetViewLength}\label{wxscrollbarsetviewlength}
 271
 272 \func{void}{SetViewLength}{\param{int}{ viewLength}}
 273
 274 Sets the view length for the scrollbar.
 275
 276 \wxheading{Parameters}
 277
 278 \docparam{viewLength}{View length.}
 279
 280 \wxheading{See also}
 281
 282 \helpref{wxScrollBar::GetViewLength}{wxscrollbargetviewlength}
 283 \end{comment}
 284