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 \wxheading{Event handling}
  53
  54 To process input from a scrollbar, use one of these event handler macros to direct input to member
  55 functions that take a \helpref{wxScrollEvent}{wxscrollevent} argument:
  56
  57 \twocolwidtha{7cm}
  58 \begin{twocollist}
  59 \twocolitem{{\bf EVT\_COMMAND\_SCROLL(id, func)}}{Catch all scroll commands.}
  60 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_TOP(id, func)}}{Catch a command to put the scroll thumb at the maximum position.}
  61 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_BOTTOM(id, func)}}{Catch a command to put the scroll thumb at the maximum position.}
  62 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_LINEUP(id, func)}}{Catch a line up command.}
  63 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_LINEDOWN(id, func)}}{Catch a line down command.}
  64 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_PAGEUP(id, func)}}{Catch a page up command.}
  65 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_PAGEDOWN(id, func)}}{Catch a page down command.}
  66 \twocolitem{{\bf EVT\_COMMAND\_SCROLL\_THUMBTRACK(id, func)}}{Catch a thumbtrack command (continuous movement of the scroll thumb).}
  67 \end{twocollist}%
  68
  69 \wxheading{See also}
  70
  71 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
  72 \helpref{Event handling overview}{eventhandlingoverview},\rtfsp
  73 \helpref{wxScrolledWindow}{wxscrolledwindow}
  74
  75 \latexignore{\rtfignore{\wxheading{Members}}}
  76
  77 \membersection{wxScrollBar::wxScrollBar}\label{wxscrollbarconstr}
  78
  79 \func{}{wxScrollBar}{\void}
  80
  81 Default constructor.
  82
  83 \func{}{wxScrollBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
  84 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  85 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
  86 \param{const wxString\& }{name = ``scrollBar"}}
  87
  88 Constructor, creating and showing a scrollbar.
  89
  90 \wxheading{Parameters}
  91
  92 \docparam{parent}{Parent window. Must not be NULL.}
  93
  94 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  95
  96 \docparam{pos}{Window position. If the position (-1, -1) is specified then a default position is chosen.}
  97
  98 \docparam{size}{Window size. If the default size (-1, -1) is specified then a default size is chosen.}
  99
 100 \docparam{style}{Window style. See \helpref{wxScrollBar}{wxscrollbar}.}
 101
 102 \docparam{validator}{Window validator.}
 103
 104 \docparam{name}{Window name.}
 105
 106 \wxheading{See also}
 107
 108 \helpref{wxScrollBar::Create}{wxscrollbarcreate}, \helpref{wxValidator}{wxvalidator}
 109
 110 \membersection{wxScrollBar::\destruct{wxScrollBar}}
 111
 112 \func{void}{\destruct{wxScrollBar}}{\void}
 113
 114 Destructor, destroying the scrollbar.
 115
 116 \membersection{wxScrollBar::Create}\label{wxscrollbarcreate}
 117
 118 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
 119 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 120 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
 121 \param{const wxString\& }{name = ``scrollBar"}}
 122
 123 Scrollbar creation function called by the scrollbar constructor.
 124 See \helpref{wxScrollBar::wxScrollBar}{wxscrollbarconstr} for details.
 125
 126 \membersection{wxScrollBar::GetRange}\label{wxscrollbargetrange}
 127
 128 \constfunc{int}{GetRange}{\void}
 129
 130 Returns the length of the scrollbar.
 131
 132 \wxheading{See also}
 133
 134 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 135
 136 \membersection{wxScrollBar::GetPageSize}\label{wxscrollbargetpagesize}
 137
 138 \constfunc{int}{GetPageSize}{\void}
 139
 140 Returns the page size of the scrollbar. This is the number of scroll units
 141 that will be scrolled when the user pages up or down. Often it is the
 142 same as the thumb size.
 143
 144 \wxheading{See also}
 145
 146 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 147
 148 \membersection{wxScrollBar::GetThumbPosition}\label{wxscrollbargetthumbposition}
 149
 150 \constfunc{int}{GetThumbPosition}{\void}
 151
 152 Returns the current position of the scrollbar thumb.
 153
 154 \wxheading{See also}
 155
 156 \helpref{wxScrollBar::SetThumbPosition}{wxscrollbarsetthumbposition}
 157
 158 \membersection{wxScrollBar::GetThumbLength}\label{wxscrollbargetthumblength}
 159
 160 \constfunc{int}{GetThumbLength}{\void}
 161
 162 Returns the thumb or `view' size.
 163
 164 \wxheading{See also}
 165
 166 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 167
 168 \begin{comment}
 169 \membersection{wxScrollBar::SetObjectLength}\label{wxscrollbarsetobjectlength}
 170
 171 \func{void}{SetObjectLength}{\param{int}{ objectLength}}
 172
 173 Sets the object length for the scrollbar. This is the total object size (virtual size). You must
 174 call \helpref{SetViewLength}{wxscrollbarsetviewlength} {\it before} calling SetObjectLength.
 175
 176 \wxheading{Parameters}
 177
 178 \docparam{objectLength}{The object length of the scrollbar.}
 179
 180 \wxheading{Remarks}
 181
 182 Example: you are implementing scrollbars on a text window, where text lines have a maximum width
 183 of 100 characters. Your text window has a current width of 60 characters. So the view length is 60,
 184 and the object length is 100. The scrollbar will then enable you to scroll to see the other 40 characters.
 185
 186 You will need to call {\bf SetViewLength} and {\bf SetObjectLength} whenever there
 187 is a change in the size of the window (the view size) or the size of the
 188 contents (the object length).
 189
 190 \wxheading{See also}
 191
 192 \helpref{wxScrollBar::GetObjectLength}{wxscrollbargetobjectlength}
 193
 194 \membersection{wxScrollBar::SetPageSize}\label{wxscrollbarsetpagesize}
 195
 196 \func{void}{SetPageSize}{\param{int}{ pageSize}}
 197
 198 Sets the page size for the scrollbar. This is the number of scroll units which are scrolled when the
 199 user pages down (clicks on the scrollbar outside the thumbtrack area).
 200
 201 \wxheading{Parameters}
 202
 203 \docparam{pageSize}{The page size in scroll units.}
 204
 205 \wxheading{Remarks}
 206
 207 At present, this needs to be called {\it before} other set functions.
 208
 209 \wxheading{See also}
 210
 211 \helpref{wxScrollBar::GetPageSize}{wxscrollbargetpagesize}
 212 \end{comment}
 213
 214 \membersection{wxScrollBar::SetThumbPosition}\label{wxscrollbarsetthumbposition}
 215
 216 \func{void}{SetThumbPosition}{\param{int}{ viewStart}}
 217
 218 Sets the position of the scrollbar.
 219
 220 \wxheading{Parameters}
 221
 222 \docparam{viewStart}{The position of the scrollbar thumb.}
 223
 224 \wxheading{See also}
 225
 226 \helpref{wxScrollBar::GetThumbPosition}{wxscrollbargetthumbposition}
 227
 228 \membersection{wxScrollBar::SetScrollbar}\label{wxscrollbarsetscrollbar}
 229
 230 \func{virtual void}{SetScrollbar}{\param{int }{position},\rtfsp
 231 \param{int }{thumbSize}, \param{int }{range},\rtfsp
 232 \param{int }{pageSize},\rtfsp
 233 \param{const bool }{refresh = TRUE}}
 234
 235 Sets the scrollbar properties.
 236
 237 \wxheading{Parameters}
 238
 239 \docparam{position}{The position of the scrollbar in scroll units.}
 240
 241 \docparam{thumbSize}{The size of the thumb, or visible portion of the scrollbar, in scroll units.}
 242
 243 \docparam{range}{The maximum position of the scrollbar.}
 244
 245 \docparam{pageSize}{The size of the page size in scroll units. This is the number of units
 246 the scrollbar will scroll when it is paged up or down. Often it is the same as
 247 the thumb size.}
 248
 249 \docparam{refresh}{TRUE to redraw the scrollbar, FALSE otherwise.}
 250
 251 \wxheading{Remarks}
 252
 253 Let's say you wish to display 50 lines of text, using the same font.
 254 The window is sized so that you can only see 16 lines at a time.
 255
 256 You would use:
 257
 258 {\small%
 259 \begin{verbatim}
 260   scrollbar->SetScrollbar(0, 16, 50, 15);
 261 \end{verbatim}
 262 }
 263
 264 The page size is 1 less than the thumb size so that the last line of the previous
 265 page will be visible on the next page, to help orient the user.
 266
 267 Note that with the window at this size, the thumb position can never go
 268 above 50 minus 16, or 34.
 269
 270 You can determine how many lines are currently visible by dividing the current view
 271 size by the character height in pixels.
 272
 273 When defining your own scrollbar behaviour, you will always need to recalculate
 274 the scrollbar settings when the window size changes. You could therefore put your
 275 scrollbar calculations and SetScrollbar
 276 call into a function named AdjustScrollbars, which can be called initially and also
 277 from a \helpref{wxSizeEvent}{wxsizeevent} event handler function.
 278
 279 \wxheading{See also}
 280
 281 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
 282 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}, \helpref{wxScrolledWindow}{wxscrolledwindow}
 283
 284 \begin{comment}
 285 \membersection{wxScrollBar::SetViewLength}\label{wxscrollbarsetviewlength}
 286
 287 \func{void}{SetViewLength}{\param{int}{ viewLength}}
 288
 289 Sets the view length for the scrollbar.
 290
 291 \wxheading{Parameters}
 292
 293 \docparam{viewLength}{View length.}
 294
 295 \wxheading{See also}
 296
 297 \helpref{wxScrollBar::GetViewLength}{wxscrollbargetviewlength}
 298 \end{comment}
 299