docs/latex/wx/tscroll.tex

   1 \section{Scrolling overview}\label{scrollingoverview}
   2
   3 Classes: \helpref{wxWindow}{wxwindow}, \helpref{wxScrolledWindow}{wxscrolledwindow}, \helpref{wxIcon}{wxicon}, \helpref{wxScrollBar}{wxscrollbar}.
   4
   5 Scrollbars come in various guises in wxWidgets. All windows have the potential
   6 to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window.
   7 However, in practice, not all windows do make use of scrollbars, such as a single-line wxTextCtrl.
   8
   9 Because any class derived from  \helpref{wxWindow}{wxwindow} may have scrollbars,
  10 there are functions to manipulate the scrollbars and event handlers to intercept
  11 scroll events. But just because a window generates a scroll event, doesn't mean
  12 that the window necessarily handles it and physically scrolls the window. The base class
  13 wxWindow in fact doesn't have any default functionality to handle scroll events.
  14 If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing
  15 at all would happen. This is deliberate, because the {\it interpretation} of scroll
  16 events varies from one window class to another.
  17
  18 \helpref{wxScrolledWindow}{wxscrolledwindow} (formerly wxCanvas) is an example of a window that
  19 adds functionality to make scrolling really work. It assumes that scrolling happens in
  20 consistent units, not different-sized jumps, and that page size is represented
  21 by the visible portion of the window. It is suited to drawing applications, but perhaps
  22 not so suitable for a sophisticated editor in which the amount scrolled may vary according
  23 to the size of text on a given line. For this, you would derive from wxWindow and
  24 implement scrolling yourself. \helpref{wxGrid}{wxgrid} is an example of a class
  25 that implements its own scrolling, largely because columns and rows can vary in size.
  26
  27 \wxheading{The scrollbar model}
  28
  29 The function \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar} gives a clue about
  30 the way a scrollbar is modeled. This function takes the following arguments:
  31
  32 \twocolwidtha{5cm}%
  33 \begin{twocollist}
  34 \twocolitem{orientation}{Which scrollbar: wxVERTICAL or wxHORIZONTAL.}
  35 \twocolitem{position}{The position of the scrollbar in scroll units.}
  36 \twocolitem{visible}{The size of the visible portion of the scrollbar, in scroll units.}
  37 \twocolitem{range}{The maximum position of the scrollbar.}
  38 \twocolitem{refresh}{Whether the scrollbar should be repainted.}
  39 \end{twocollist}%
  40
  41 {\it orientation} determines whether we're talking about
  42 the built-in horizontal or vertical scrollbar.
  43
  44 {\it position} is simply the position of the `thumb' (the bit you drag to scroll around).
  45 It is given in scroll units, and so is relative to the total range of the scrollbar.
  46
  47 {\it visible} gives the number of scroll units that represents the portion of the
  48 window currently visible. Normally, a scrollbar is capable of indicating this visually
  49 by showing a different length of thumb.
  50
  51 {\it range} is the maximum value of the scrollbar, where zero is the start
  52 position. You choose the units that suit you,
  53 so if you wanted to display text that has 100 lines, you would set this to 100.
  54 Note that this doesn't have to correspond to the number of pixels scrolled - it is
  55 up to you how you actually show the contents of the window.
  56
  57 {\it refresh} just indicates whether the scrollbar should be repainted immediately or not.
  58
  59 \wxheading{An example}
  60
  61 Let's say you wish to display 50 lines of text, using the same font.
  62 The window is sized so that you can only see 16 lines at a time.
  63
  64 You would use:
  65
  66 {\small%
  67 \begin{verbatim}
  68   SetScrollbar(wxVERTICAL, 0, 16, 50);
  69 \end{verbatim}
  70 }
  71
  72 Note that with the window at this size, the thumb position can never go
  73 above 50 minus 16, or 34.
  74
  75 You can determine how many lines are currently visible by dividing the current view
  76 size by the character height in pixels.
  77
  78 When defining your own scrollbar behaviour, you will always need to recalculate
  79 the scrollbar settings when the window size changes. You could therefore put your
  80 scrollbar calculations and SetScrollbar
  81 call into a function named AdjustScrollbars, which can be called initially and also
  82 from your \helpref{wxSizeEvent}{wxsizeevent} handler function.
  83
  84 %\normalbox{{\bf For Windows programmers:} note that scrollbar range in wxWidgets has a different meaning
  85 %from that in Windows. In native Windows scrollbar calls, range is the number of positions that the scrollbar
  86 %can physically scroll through - in our example above, it would be 34. But it is easier
  87 %to think in terms of the number of units that the whole scrollbar represents - the virtual
  88 %window size - which is why wxWidgets does it differently.}
  89
  90