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{Library}
  20
  21 \helpref{wxCore}{librarieslist}
  22
  23 \wxheading{Remarks}
  24
  25 A scrollbar has the following main attributes: {\it range}, {\it thumb size}, {\it page size}, and {\it position}.
  26
  27 The range is the total number of units associated with the view represented by the scrollbar.
  28 For a table with 15 columns, the range would be 15.
  29
  30 The thumb size is the number of units that are currently visible. For the table example, the window
  31 might be sized so that only 5 columns are currently visible, in which case the application would
  32 set the thumb size to 5. When the thumb size becomes the same as or greater than the range,
  33 the scrollbar will be automatically hidden on most platforms.
  34
  35 The page size is the number of units that the scrollbar should scroll by, when `paging' through
  36 the data. This value is normally the same as the thumb size length, because
  37 it is natural to assume that the visible window size defines a page.
  38
  39 The scrollbar position is the current thumb position.
  40
  41 Most applications will find it convenient to provide a function called {\bf AdjustScrollbars} which can
  42 be called initially, from an {\bf OnSize} event handler, and whenever the application data
  43 changes in size. It will adjust the view, object and page size according
  44 to the size of the window and the size of the data.
  45
  46 \wxheading{Window styles}
  47
  48 \twocolwidtha{5cm}
  49 \begin{twocollist}\itemsep=0pt
  50 \twocolitem{\windowstyle{wxSB\_HORIZONTAL}}{Specifies a horizontal scrollbar.}
  51 \twocolitem{\windowstyle{wxSB\_VERTICAL}}{Specifies a vertical scrollbar.}
  52 \end{twocollist}
  53
  54 See also \helpref{window styles overview}{windowstyles}.
  55
  56 \input scrolevt.inc
  57
  58 \wxheading{See also}
  59
  60 \helpref{Scrolling overview}{scrollingoverview},\rtfsp
  61 \helpref{Event handling overview}{eventhandlingoverview},\rtfsp
  62 \helpref{wxScrolledWindow}{wxscrolledwindow}
  63
  64 \latexignore{\rtfignore{\wxheading{Members}}}
  65
  66
  67 \membersection{wxScrollBar::wxScrollBar}\label{wxscrollbarctor}
  68
  69 \func{}{wxScrollBar}{\void}
  70
  71 Default constructor.
  72
  73 \func{}{wxScrollBar}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
  74 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  75 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
  76 \param{const wxString\& }{name = ``scrollBar"}}
  77
  78 Constructor, creating and showing a scrollbar.
  79
  80 \wxheading{Parameters}
  81
  82 \docparam{parent}{Parent window. Must be non-NULL.}
  83
  84 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  85
  86 \docparam{pos}{Window position. If the position (-1, -1) is specified then a default position is chosen.}
  87
  88 \docparam{size}{Window size. If the default size (-1, -1) is specified then a default size is chosen.}
  89
  90 \docparam{style}{Window style. See \helpref{wxScrollBar}{wxscrollbar}.}
  91
  92 \docparam{validator}{Window validator.}
  93
  94 \docparam{name}{Window name.}
  95
  96 \wxheading{See also}
  97
  98 \helpref{wxScrollBar::Create}{wxscrollbarcreate}, \helpref{wxValidator}{wxvalidator}
  99
 100
 101 \membersection{wxScrollBar::\destruct{wxScrollBar}}\label{wxscrollbardtor}
 102
 103 \func{void}{\destruct{wxScrollBar}}{\void}
 104
 105 Destructor, destroying the scrollbar.
 106
 107
 108 \membersection{wxScrollBar::Create}\label{wxscrollbarcreate}
 109
 110 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id},\rtfsp
 111 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
 112 \param{long}{ style = wxSB\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator},\rtfsp
 113 \param{const wxString\& }{name = ``scrollBar"}}
 114
 115 Scrollbar creation function called by the scrollbar constructor.
 116 See \helpref{wxScrollBar::wxScrollBar}{wxscrollbarctor} for details.
 117
 118
 119 \membersection{wxScrollBar::GetRange}\label{wxscrollbargetrange}
 120
 121 \constfunc{int}{GetRange}{\void}
 122
 123 Returns the length of the scrollbar.
 124
 125 \wxheading{See also}
 126
 127 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 128
 129
 130 \membersection{wxScrollBar::GetPageSize}\label{wxscrollbargetpagesize}
 131
 132 \constfunc{int}{GetPageSize}{\void}
 133
 134 Returns the page size of the scrollbar. This is the number of scroll units
 135 that will be scrolled when the user pages up or down. Often it is the
 136 same as the thumb size.
 137
 138 \wxheading{See also}
 139
 140 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 141
 142
 143 \membersection{wxScrollBar::GetThumbPosition}\label{wxscrollbargetthumbposition}
 144
 145 \constfunc{int}{GetThumbPosition}{\void}
 146
 147 Returns the current position of the scrollbar thumb.
 148
 149 \wxheading{See also}
 150
 151 \helpref{wxScrollBar::SetThumbPosition}{wxscrollbarsetthumbposition}
 152
 153
 154 \membersection{wxScrollBar::GetThumbSize}\label{wxscrollbargetthumbsize}
 155
 156 \constfunc{int}{GetThumbSize}{\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
 166 \membersection{wxScrollBar::SetObjectLength}\label{wxscrollbarsetobjectlength}
 167
 168 \func{void}{SetObjectLength}{\param{int}{ objectLength}}
 169
 170 Sets the object length for the scrollbar. This is the total object size (virtual size). You must
 171 call \helpref{SetViewLength}{wxscrollbarsetviewlength} {\it before} calling SetObjectLength.
 172
 173 \wxheading{Parameters}
 174
 175 \docparam{objectLength}{The object length of the scrollbar.}
 176
 177 \wxheading{Remarks}
 178
 179 Example: you are implementing scrollbars on a text window, where text lines have a maximum width
 180 of 100 characters. Your text window has a current width of 60 characters. So the view length is 60,
 181 and the object length is 100. The scrollbar will then enable you to scroll to see the other 40 characters.
 182
 183 You will need to call {\bf SetViewLength} and {\bf SetObjectLength} whenever there
 184 is a change in the size of the window (the view size) or the size of the
 185 contents (the object length).
 186
 187 \wxheading{See also}
 188
 189 \helpref{wxScrollBar::GetObjectLength}{wxscrollbargetobjectlength}
 190
 191
 192 \membersection{wxScrollBar::SetPageSize}\label{wxscrollbarsetpagesize}
 193
 194 \func{void}{SetPageSize}{\param{int}{ pageSize}}
 195
 196 Sets the page size for the scrollbar. This is the number of scroll units which are scrolled when the
 197 user pages down (clicks on the scrollbar outside the thumbtrack area).
 198
 199 \wxheading{Parameters}
 200
 201 \docparam{pageSize}{The page size in scroll units.}
 202
 203 \wxheading{Remarks}
 204
 205 At present, this needs to be called {\it before} other set functions.
 206
 207 \wxheading{See also}
 208
 209 \helpref{wxScrollBar::GetPageSize}{wxscrollbargetpagesize}
 210 \end{comment}
 211
 212
 213 \membersection{wxScrollBar::SetThumbPosition}\label{wxscrollbarsetthumbposition}
 214
 215 \func{void}{SetThumbPosition}{\param{int}{ viewStart}}
 216
 217 Sets the position of the scrollbar.
 218
 219 \wxheading{Parameters}
 220
 221 \docparam{viewStart}{The position of the scrollbar thumb.}
 222
 223 \wxheading{See also}
 224
 225 \helpref{wxScrollBar::GetThumbPosition}{wxscrollbargetthumbposition}
 226
 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{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
 285 \begin{comment}
 286
 287 \membersection{wxScrollBar::SetViewLength}\label{wxscrollbarsetviewlength}
 288
 289 \func{void}{SetViewLength}{\param{int}{ viewLength}}
 290
 291 Sets the view length for the scrollbar.
 292
 293 \wxheading{Parameters}
 294
 295 \docparam{viewLength}{View length.}
 296
 297 \wxheading{See also}
 298
 299 \helpref{wxScrollBar::GetViewLength}{wxscrollbargetviewlength}
 300 \end{comment}
 301