]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: scrolling.h | |
3 | // Purpose: topic overview | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | ||
11 | @page overview_scrolling Scrolled Windows | |
12 | ||
13 | Classes: wxWindow, wxScrolledWindow, wxScrollBar | |
14 | ||
15 | @li @ref overview_scrolling_model | |
16 | @li @ref overview_scrolling_example | |
17 | ||
18 | <hr> | |
19 | ||
20 | ||
21 | Scrollbars come in various guises in wxWidgets. All windows have the potential | |
22 | to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic | |
23 | capability of a window. However, in practice, not all windows do make use of | |
24 | scrollbars, such as a single-line wxTextCtrl. | |
25 | ||
26 | Because any class derived from wxWindow may have scrollbars, there are | |
27 | functions to manipulate the scrollbars and event handlers to intercept scroll | |
28 | events. But just because a window generates a scroll event, doesn't mean that | |
29 | the window necessarily handles it and physically scrolls the window. The base | |
30 | class wxWindow in fact doesn't have any default functionality to handle scroll | |
31 | events. If you created a wxWindow object with scrollbars, and then clicked on | |
32 | the scrollbars, nothing at all would happen. This is deliberate, because the | |
33 | @e interpretation of scroll events varies from one window class to another. | |
34 | ||
35 | ::wxScrolledWindow (formerly wxCanvas) is an example of a window that adds | |
36 | functionality to make scrolling really work. It assumes that scrolling happens | |
37 | in consistent units, not different-sized jumps, and that page size is | |
38 | represented by the visible portion of the window. It is suited to drawing | |
39 | applications, but perhaps not so suitable for a sophisticated editor in which | |
40 | the amount scrolled may vary according to the size of text on a given line. For | |
41 | this, you would derive from wxWindow and implement scrolling yourself. wxGrid | |
42 | is an example of a class that implements its own scrolling, largely because | |
43 | columns and rows can vary in size. | |
44 | ||
45 | ||
46 | @section overview_scrolling_model The Scrollbar Model | |
47 | ||
48 | The function wxWindow::SetScrollbar gives a clue about the way a scrollbar is | |
49 | modeled. This function takes the following arguments: | |
50 | ||
51 | @beginTable | |
52 | @row2col{ @c orientation , Which scrollbar: wxVERTICAL or wxHORIZONTAL. } | |
53 | @row2col{ @c position , The position of the scrollbar in scroll units. } | |
54 | @row2col{ @c visible , The size of the visible portion of the scrollbar, | |
55 | in scroll units. } | |
56 | @row2col{ @c range , The maximum position of the scrollbar. } | |
57 | @row2col{ @c refresh , Whether the scrollbar should be repainted. } | |
58 | @endTable | |
59 | ||
60 | @c orientation determines whether we're talking about the built-in horizontal | |
61 | or vertical scrollbar. | |
62 | ||
63 | @c position is simply the position of the 'thumb' (the bit you drag to scroll | |
64 | around). It is given in scroll units, and so is relative to the total range of | |
65 | the scrollbar. | |
66 | ||
67 | @c visible gives the number of scroll units that represents the portion of the | |
68 | window currently visible. Normally, a scrollbar is capable of indicating this | |
69 | visually by showing a different length of thumb. | |
70 | ||
71 | @c range is the maximum value of the scrollbar, where zero is the start | |
72 | position. You choose the units that suit you, so if you wanted to display text | |
73 | that has 100 lines, you would set this to 100. Note that this doesn't have to | |
74 | correspond to the number of pixels scrolled - it is up to you how you actually | |
75 | show the contents of the window. | |
76 | ||
77 | @c refresh just indicates whether the scrollbar should be repainted immediately | |
78 | or not. | |
79 | ||
80 | ||
81 | @section overview_scrolling_example An Example | |
82 | ||
83 | Let's say you wish to display 50 lines of text, using the same font. The window | |
84 | is sized so that you can only see 16 lines at a time. You would use: | |
85 | ||
86 | @code | |
87 | SetScrollbar(wxVERTICAL, 0, 16, 50); | |
88 | @endcode | |
89 | ||
90 | Note that with the window at this size, the thumb position can never go above | |
91 | 50 minus 16, or 34. You can determine how many lines are currently visible by | |
92 | dividing the current view size by the character height in pixels. | |
93 | ||
94 | When defining your own scrollbar behaviour, you will always need to recalculate | |
95 | the scrollbar settings when the window size changes. You could therefore put | |
96 | your scrollbar calculations and SetScrollbar call into a function named | |
97 | AdjustScrollbars, which can be called initially and also from your wxSizeEvent | |
98 | handler function. | |
99 | ||
100 | */ | |
101 |