-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% 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}\\
-\helpref{wxWindow}{wxwindow}\\
-\helpref{wxEvtHandler}{wxevthandler}\\
-\helpref{wxObject}{wxobject}
-
-\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}.
-
projects / wxWidgets.git / commitdiff
