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