41e9579283
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@38060 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
301 lines
11 KiB
TeX
301 lines
11 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: vscroll.tex
|
|
%% Purpose: wxVScrolledWindow documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 30.05.03
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxVScrolledWindow}}\label{wxvscrolledwindow}
|
|
|
|
In the name of this class, "V" may stand for "variable" because it can be
|
|
used for scrolling lines of variable heights; "virtual" because it is not
|
|
necessary to know the heights of all lines in advance -- only those which
|
|
are shown on the screen need to be measured; or, even, "vertical" because
|
|
this class only supports scrolling in one direction currently (this could
|
|
and probably will change in the future however).
|
|
|
|
In any case, this is a generalization of the
|
|
\helpref{wxScrolledWindow}{wxscrolledwindow} class which can be only used when
|
|
all lines have the same height. It lacks some other wxScrolledWindow features
|
|
however, notably there is currently no support for horizontal scrolling; it
|
|
can't scroll another window nor only a rectangle of the window and not its
|
|
entire client area.
|
|
|
|
To use this class, you need to derive from it and implement
|
|
\helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} pure virtual
|
|
method. You also must call \helpref{SetLineCount}{wxvscrolledwindowsetlinecount}
|
|
to let the base class know how many lines it should display but from that
|
|
moment on the scrolling is handled entirely by wxVScrolledWindow, you only
|
|
need to draw the visible part of contents in your {\tt OnPaint()} method as
|
|
usual. You should use \helpref{GetFirstVisibleLine()}{wxvscrolledwindowgetfirstvisibleline}
|
|
and \helpref{GetLastVisibleLine()}{wxvscrolledwindowgetlastvisibleline} to
|
|
select the lines to display. Note that the device context origin is not shifted
|
|
so the first visible line always appears at the point $(0, 0)$ in physical as
|
|
well as logical coordinates.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxPanel}{wxpanel}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/vscroll.h>
|
|
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::wxVScrolledWindow}\label{wxvscrolledwindowctor}
|
|
|
|
\func{}{wxVScrolledWindow}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
|
|
|
|
This is the normal constructor, no need to call Create() after using this one.
|
|
|
|
Note that {\tt wxVSCROLL} is always automatically added to our style, there is
|
|
no need to specify it explicitly.
|
|
|
|
\func{}{wxVScrolledWindow}{\void}
|
|
|
|
Default constructor, you must call \helpref{Create()}{wxvscrolledwindowcreate}
|
|
later.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{The parent window, must not be {\tt NULL}}
|
|
|
|
\docparam{id}{The identifier of this window, {\tt wxID\_ANY} by default}
|
|
|
|
\docparam{pos}{The initial window position}
|
|
|
|
\docparam{size}{The initial window size}
|
|
|
|
\docparam{style}{The window style. There are no special style bits defined for
|
|
this class.}
|
|
|
|
\docparam{name}{The name for this window; usually not used}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::Create}\label{wxvscrolledwindowcreate}
|
|
|
|
\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxPanelNameStr}}
|
|
|
|
Same as the \helpref{non default ctor}{wxvscrolledwindowctor} but returns
|
|
status code: {\tt true} if ok, {\tt false} if the window couldn't have been created.
|
|
|
|
Just as with the ctor above, {\tt wxVSCROLL} style is always used, there is no
|
|
need to specify it explicitly.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::EstimateTotalHeight}\label{wxvscrolledwindowestimatetotalheight}
|
|
|
|
\constfunc{virtual wxCoord}{EstimateTotalHeight}{\void}
|
|
|
|
This protected function is used internally by wxVScrolledWindow to estimate the
|
|
total height of the window when \helpref{SetLineCount}{wxvscrolledwindowsetlinecount}
|
|
is called. The default implementation uses the brute force approach if the
|
|
number of the items in the control is small enough. Otherwise, it tries to find
|
|
the average line height using some lines in the beginning, middle and the end.
|
|
|
|
If it is undesirable to access all these lines (some of which might be never
|
|
shown) just for the total height calculation, you may override the function and
|
|
provide your own guess better and/or faster.
|
|
|
|
Note that although returning a totally wrong value would still work, it risks
|
|
to result in very strange scrollbar behaviour so this function should really
|
|
try to make the best guess possible.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::GetFirstVisibleLine}\label{wxvscrolledwindowgetfirstvisibleline}
|
|
|
|
\constfunc{size\_t}{GetFirstVisibleLine}{\void}
|
|
|
|
Returns the index of the first currently visible line.
|
|
|
|
This is same as \helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin} and
|
|
exists only for symmetry with \helpref{GetLastVisibleLine}{wxvscrolledwindowgetlastvisibleline}.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::GetLastVisibleLine}\label{wxvscrolledwindowgetlastvisibleline}
|
|
|
|
\constfunc{size\_t}{GetLastVisibleLine}{\void}
|
|
|
|
Returns the index of the last currently visible line. Note that this method
|
|
returns \texttt{(size\_t)-1} (i.e. a huge positive number) if the control is
|
|
empty so if this is possible you should use \helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
|
|
instead.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{GetFirstVisibleLine}{wxvscrolledwindowgetfirstvisibleline}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::GetLineCount}\label{wxvscrolledwindowgetlinecount}
|
|
|
|
\constfunc{size\_t}{GetLineCount}{\void}
|
|
|
|
Get the number of lines this window contains (previously set by
|
|
\helpref{SetLineCount()}{wxvscrolledwindowsetlinecount})
|
|
|
|
|
|
\membersection{wxVScrolledWindow::GetVisibleBegin}\label{wxvscrolledwindowgetvisiblebegin}
|
|
|
|
\constfunc{size\_t}{GetVisibleBegin}{\void}
|
|
|
|
Returns the index of the first currently visible line.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{GetVisibleEnd}{wxvscrolledwindowgetvisibleend}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::GetVisibleEnd}\label{wxvscrolledwindowgetvisibleend}
|
|
|
|
\constfunc{size\_t}{GetVisibleEnd}{\void}
|
|
|
|
Returns the index of the first line after the currently visible one. If the
|
|
return value is $0$ it means that no lines are currently shown (which only
|
|
happens if the control is empty). Note that the index returned by this method
|
|
is not always a valid index as it may be equal to \helpref{GetLineCount}{wxvscrolledwindowgetlinecount}.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{GetVisibleBegin}{wxvscrolledwindowgetvisiblebegin}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::HitTest}\label{wxvscrolledwindowhittest}
|
|
|
|
\constfunc{int}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}
|
|
|
|
\constfunc{int}{HitTest}{\param{const wxPoint\& }{pt}}
|
|
|
|
Return the item at the specified (in physical coordinates) position or
|
|
{\tt wxNOT\_FOUND} if none, i.e. if it is below the last item.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::IsVisible}\label{wxvscrolledwindowisvisible}
|
|
|
|
\constfunc{bool}{IsVisible}{\param{size\_t }{line}}
|
|
|
|
Returns {\tt true} if the given line is (at least partially) visible or
|
|
{\tt false} otherwise.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::OnGetLineHeight}\label{wxvscrolledwindowongetlineheight}
|
|
|
|
\constfunc{virtual wxCoord}{OnGetLineHeight}{\param{size\_t }{n}}
|
|
|
|
This protected virtual function must be overridden in the derived class and it
|
|
should return the height of the given line in pixels.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{OnGetLinesHint}{wxvscrolledwindowongetlineshint}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::OnGetLinesHint}\label{wxvscrolledwindowongetlineshint}
|
|
|
|
\constfunc{virtual void}{OnGetLinesHint}{\param{size\_t }{lineMin}, \param{size\_t }{lineMax}}
|
|
|
|
This function doesn't have to be overridden but it may be useful to do
|
|
it if calculating the lines heights is a relatively expensive operation
|
|
as it gives the user code a possibility to calculate several of them at
|
|
once.
|
|
|
|
{\tt OnGetLinesHint()} is normally called just before
|
|
\helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight} but you
|
|
shouldn't rely on the latter being called for all lines in the interval
|
|
specified here. It is also possible that OnGetLineHeight() will be
|
|
called for the lines outside of this interval, so this is really just a
|
|
hint, not a promise.
|
|
|
|
Finally note that {\it lineMin} is inclusive, while {\it lineMax} is exclusive,
|
|
as usual.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::RefreshLine}\label{wxvscrolledwindowrefreshline}
|
|
|
|
\func{void}{RefreshLine}{\param{size\_t }{line}}
|
|
|
|
Refreshes the specified line -- it will be redrawn during the next main loop
|
|
iteration.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{RefreshLines}{wxvscrolledwindowrefreshlines}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::RefreshLines}\label{wxvscrolledwindowrefreshlines}
|
|
|
|
\func{void}{RefreshLines}{\param{size\_t }{from}, \param{size\_t }{to}}
|
|
|
|
Refreshes all lines between {\it from} and {\it to}, inclusive. {\it from}
|
|
should be less than or equal to {\it to}.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{RefreshLine}{wxvscrolledwindowrefreshline}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::RefreshAll}\label{wxvscrolledwindowrefreshall}
|
|
|
|
\func{void}{RefreshAll}{\void}
|
|
|
|
This function completely refreshes the control, recalculating the number of
|
|
items shown on screen and repainting them. It should be called when the values
|
|
returned by \helpref{OnGetLineHeight}{wxvscrolledwindowongetlineheight} change
|
|
for some reason and the window must be updated to reflect this.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::ScrollLines}\label{wxvscrolledwindowscrolllines}
|
|
|
|
\func{bool}{ScrollLines}{\param{int }{lines}}
|
|
|
|
Scroll by the specified number of lines which may be positive (to scroll down)
|
|
or negative (to scroll up).
|
|
|
|
Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
|
|
example if we're trying to scroll down but we are already showing the last
|
|
line).
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::ScrollPages}\label{wxvscrolledwindowscrollpages}
|
|
|
|
\func{bool}{ScrollPages}{\param{int }{pages}}
|
|
|
|
Scroll by the specified number of pages which may be positive (to scroll down)
|
|
or negative (to scroll up).
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{ScrollLines}{wxvscrolledwindowscrolllines},\\
|
|
\helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}
|
|
|
|
|
|
\membersection{wxVScrolledWindow::ScrollToLine}\label{wxvscrolledwindowscrolltoline}
|
|
|
|
\func{bool}{ScrollToLine}{\param{size\_t }{line}}
|
|
|
|
Scroll to the specified line: it will become the first visible line in
|
|
the window.
|
|
|
|
Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.
|
|
|
|
|
|
\membersection{wxVScrolledWindow::SetLineCount}\label{wxvscrolledwindowsetlinecount}
|
|
|
|
\func{void}{SetLineCount}{\param{size\_t }{count}}
|
|
|
|
Set the number of lines the window contains: the derived class must
|
|
provide the heights for all lines with indices up to the one given here
|
|
in its \helpref{OnGetLineHeight()}{wxvscrolledwindowongetlineheight}.
|
|
|
|
|