| 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 wxWindows. All windows have the potential |
| 6 | to show a vertical scrollbar and/or a horizontal scrollbar: it's 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's 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 modelled. 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's 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's |
| 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{wxWindow::OnSize}{wxwindowonsize} event handler function. |
| 83 | |
| 84 | %\normalbox{{\bf For Windows programmers:} note that scrollbar range in wxWindows 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's easier |
| 87 | %to think in terms of the number of units that the whole scrollbar represents - the virtual |
| 88 | %window size - which is why wxWindows does it differently.} |
| 89 | |
| 90 | |