fc2171bd4c
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@27090 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
91 lines
4.5 KiB
TeX
91 lines
4.5 KiB
TeX
\section{Scrolling overview}\label{scrollingoverview}
|
|
|
|
Classes: \helpref{wxWindow}{wxwindow}, \helpref{wxScrolledWindow}{wxscrolledwindow}, \helpref{wxIcon}{wxicon}, \helpref{wxScrollBar}{wxscrollbar}.
|
|
|
|
Scrollbars come in various guises in wxWidgets. All windows have the potential
|
|
to show a vertical scrollbar and/or a horizontal scrollbar: it is a basic capability of a window.
|
|
However, in practice, not all windows do make use of scrollbars, such as a single-line wxTextCtrl.
|
|
|
|
Because any class derived from \helpref{wxWindow}{wxwindow} may have scrollbars,
|
|
there are functions to manipulate the scrollbars and event handlers to intercept
|
|
scroll events. But just because a window generates a scroll event, doesn't mean
|
|
that the window necessarily handles it and physically scrolls the window. The base class
|
|
wxWindow in fact doesn't have any default functionality to handle scroll events.
|
|
If you created a wxWindow object with scrollbars, and then clicked on the scrollbars, nothing
|
|
at all would happen. This is deliberate, because the {\it interpretation} of scroll
|
|
events varies from one window class to another.
|
|
|
|
\helpref{wxScrolledWindow}{wxscrolledwindow} (formerly wxCanvas) is an example of a window that
|
|
adds functionality to make scrolling really work. It assumes that scrolling happens in
|
|
consistent units, not different-sized jumps, and that page size is represented
|
|
by the visible portion of the window. It is suited to drawing applications, but perhaps
|
|
not so suitable for a sophisticated editor in which the amount scrolled may vary according
|
|
to the size of text on a given line. For this, you would derive from wxWindow and
|
|
implement scrolling yourself. \helpref{wxGrid}{wxgrid} is an example of a class
|
|
that implements its own scrolling, largely because columns and rows can vary in size.
|
|
|
|
\wxheading{The scrollbar model}
|
|
|
|
The function \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar} gives a clue about
|
|
the way a scrollbar is modeled. This function takes the following arguments:
|
|
|
|
\twocolwidtha{5cm}%
|
|
\begin{twocollist}
|
|
\twocolitem{orientation}{Which scrollbar: wxVERTICAL or wxHORIZONTAL.}
|
|
\twocolitem{position}{The position of the scrollbar in scroll units.}
|
|
\twocolitem{visible}{The size of the visible portion of the scrollbar, in scroll units.}
|
|
\twocolitem{range}{The maximum position of the scrollbar.}
|
|
\twocolitem{refresh}{Whether the scrollbar should be repainted.}
|
|
\end{twocollist}%
|
|
|
|
{\it orientation} determines whether we're talking about
|
|
the built-in horizontal or vertical scrollbar.
|
|
|
|
{\it position} is simply the position of the `thumb' (the bit you drag to scroll around).
|
|
It is given in scroll units, and so is relative to the total range of the scrollbar.
|
|
|
|
{\it visible} gives the number of scroll units that represents the portion of the
|
|
window currently visible. Normally, a scrollbar is capable of indicating this visually
|
|
by showing a different length of thumb.
|
|
|
|
{\it range} is the maximum value of the scrollbar, where zero is the start
|
|
position. You choose the units that suit you,
|
|
so if you wanted to display text that has 100 lines, you would set this to 100.
|
|
Note that this doesn't have to correspond to the number of pixels scrolled - it is
|
|
up to you how you actually show the contents of the window.
|
|
|
|
{\it refresh} just indicates whether the scrollbar should be repainted immediately or not.
|
|
|
|
\wxheading{An example}
|
|
|
|
Let's say you wish to display 50 lines of text, using the same font.
|
|
The window is sized so that you can only see 16 lines at a time.
|
|
|
|
You would use:
|
|
|
|
{\small%
|
|
\begin{verbatim}
|
|
SetScrollbar(wxVERTICAL, 0, 16, 50);
|
|
\end{verbatim}
|
|
}
|
|
|
|
Note that with the window at this size, the thumb position can never go
|
|
above 50 minus 16, or 34.
|
|
|
|
You can determine how many lines are currently visible by dividing the current view
|
|
size by the character height in pixels.
|
|
|
|
When defining your own scrollbar behaviour, you will always need to recalculate
|
|
the scrollbar settings when the window size changes. You could therefore put your
|
|
scrollbar calculations and SetScrollbar
|
|
call into a function named AdjustScrollbars, which can be called initially and also
|
|
from your \helpref{wxSizeEvent}{wxsizeevent} handler function.
|
|
|
|
%\normalbox{{\bf For Windows programmers:} note that scrollbar range in wxWidgets has a different meaning
|
|
%from that in Windows. In native Windows scrollbar calls, range is the number of positions that the scrollbar
|
|
%can physically scroll through - in our example above, it would be 34. But it is easier
|
|
%to think in terms of the number of units that the whole scrollbar represents - the virtual
|
|
%window size - which is why wxWidgets does it differently.}
|
|
|
|
|