document WX_PREPEND_ARRAY (part of patch 1590194)

[wxWidgets.git] / docs / latex / wx / hvscroll.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        hvscroll.tex
%% Purpose:     wxHVScrolledWindow documentation
%% Author:      Vadim Zeitlin
%% Modified by: Brad Anderson
%% Created:     24.01.06
%% RCS-ID:      $Id$
%% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxHVScrolledWindow}}\label{wxhvscrolledwindow}

This class is strongly influenced by 
\helpref{wxVScrolledWindow}{wxvscrolledwindow}. 
Like wxVScrolledWindow, this class is here to provide an easy way to implement
variable line sizes.  The difference is that wxVScrolledWindow only works with
vertical scrolling.  This class extends the behavior of wxVScrolledWindow to
the horizontal axis in addition to the vertical axis.

The scrolling is also "virtual" in the sense that row widths and column heights
only need to be known for the rows and columns that are currently visible.

Like \helpref{wxVScrolledWindow}{wxvscrolledwindow}, this is a generalization
of the \helpref{wxScrolledWindow}{wxscrolledwindow} class which can be only
used when all rows have a constant height and columns have a constant width. 
Like wxVScrolledWinow it lacks some of wxScrolledWindow features such as
scrolling another window or only scrolling a rectangle of the window and not
its entire client area.

If only vertical scrolling is needed, wxVScrolledWindow is recommended
because it is simpler to use.
   
There is no wxHScrolledWindow but horizontal-only scrolling is implemented
easily enough with this class.

To use this class, you need to derive from it and implement both the 
\helpref{OnGetRowHeight()}{wxhvscrolledwindowongetrowheight} and the 
\helpref{OnGetColumnWidth()}{wxhvscrolledwindowongetcolumnwidth} pure virtual
methods. You also must call 
\helpref{SetRowColumnCounts}{wxhvscrolledwindowsetrowcolumncounts} to let the
base class know how many rows and columns it should display. After these
requirements are met scrolling is handled entirely by wxHVScrolledWindow. You
only need to draw the visible part of contents in your {\tt OnPaint()} method
as usual. You should use 
\helpref{GetVisibleRowsBegin()}{wxhvscrolledwindowgetvisiblerowsbegin}, 
\helpref{GetVisibleColumnsBegin()}{wxhvscrolledwindowgetvisiblecolumnsbegin}, 
\helpref{GetVisibleRowsEnd()}{wxhvscrolledwindowgetvisiblerowsend}, and 
\helpref{GetVisibleColumnsEnd()}{wxhvscrolledwindowgetvisiblecolumnsend} to
determine which lines to to display. If physical scrolling is enabled the
device context origin is shifted by the scroll position (through
{\tt PrepareDC()}), child windows are moved as the window scrolls, and the
pixels on the screen are moved to minimize the region that requires painting.
Physical scrolling is enabled by default.

\wxheading{Derived from}

\helpref{wxPanel}{wxpanel}

\wxheading{Include files}

<wx/vscroll.h>


\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxHVScrolledWindow::wxHVScrolledWindow}\label{wxhvscrolledwindowctor}

\func{}{wxHVScrolledWindow}{\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} and {\tt wxHSCROLL} are always automatically added to
our style, there is no need to specify them explicitly.

\func{}{wxHVScrolledWindow}{\void}

Default constructor, you must call \helpref{Create()}{wxhvscrolledwindowcreate}
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{wxHVScrolledWindow::Create}\label{wxhvscrolledwindowcreate}

\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}{wxhvscrolledwindowctor} but returns
status code: {\tt true} if ok, {\tt false} if the window couldn't have been created.

Just as with the ctor above, both the {\tt wxVSCROLL} and the {\tt wxHSCROLL}
styles are always used. There is no need to specify either explicitly.

\membersection{wxHVScrolledWindow::EnablePhysicalScrolling}\label{wxhvscrolledwindowenablephysicalscrolling}

\func{\void}{EnablePhysicalScrolling}{\param{bool }{scrolling = true}}

With physical scrolling enabled the device origin is changed properly when a
wxDC is prepared using {\tt PrepareDC()}, children are actually moved and layed
out according to the current scroll position, and the contents of the window
(pixels) are actually moved to reduce the amount of redraw needed.

Physical scrolling is enabled by default but can be disable or re-enabled at
any time.  An example of when you'd want to disable it would be if you have
statically positioned graphic elements or children you do not want to move
while the window is being scrolled.  If you disable physical scrolling you must
manually adjust positioning for items within the scrolled window yourself.
Also note that an unprepared wxDC requires you to do the same, regardless of
the physical scrolling state.


\membersection{wxHVScrolledWindow::EstimateTotalHeight}\label{wxhvscrolledwindowestimatetotalheight}

\constfunc{virtual wxCoord}{EstimateTotalHeight}{\void}

This protected function is used internally by wxHVScrolledWindow to estimate the
total height of the window when 
\helpref{SetRowColumnCounts}{wxhvscrolledwindowsetrowcolumncounts}
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 row height using some rows in the beginning, middle and the end.

If it is undesirable to query all these rows (some of which might be never
shown) just for the total height calculation, you may override the function and
provide your own guess using a better and/or faster method.

Note that although returning a totally wrong value would still work, it risks
causing some very strange scrollbar behaviour so this function should really
try to make the best guess possible.


\membersection{wxHVScrolledWindow::EstimateTotalWidth}\label{wxhvscrolledwindowestimatetotalwidth}

\constfunc{virtual wxCoord}{EstimateTotalWidth}{\void}

This protected function is used internally by wxHVScrolledWindow to estimate the
total width of the window when 
\helpref{SetRowColumnCounts}{wxhvscrolledwindowsetrowcolumncounts}
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 column width using some columns in the beginning, middle and the end.

If it is undesirable to query all these columns (some of which might be never
shown) just for the total width calculation, you may override the function and
provide your own guess using a better and/or faster method.

Note that although returning a totally wrong value would still work, it risks
causing some very strange scrollbar behaviour so this function should really
try to make the best guess possible.


\membersection{wxHVScrolledWindow::GetColumnCount}\label{wxhvscrolledwindowgetcolumncount}

\constfunc{wxSize}{GetColumnCount}{\void}

Get the number of columns this window contains (previously set by 
\helpref{SetRowColumnCounts()}{wxhvscrolledwindowsetrowcolumncounts})


\membersection{wxHVScrolledWindow::GetRowCount}\label{wxhvscrolledwindowgetrowcount}

\constfunc{wxSize}{GetRowCount}{\void}

Get the number of rows this window contains (previously set by 
\helpref{SetRowColumnCounts()}{wxhvscrolledwindowsetrowcolumncounts})


\membersection{wxHVScrolledWindow::GetRowColumnCounts}\label{wxhvscrolledwindowgetrowcolumncounts}

\constfunc{wxSize}{GetRowColumnCounts}{\void}

Get the number of rows (X or width) and columns (Y or height) this window
contains (previously set
by \helpref{SetRowColumnCounts()}{wxhvscrolledwindowsetrowcolumncounts})


\membersection{wxHVScrolledWindow::GetVisibleBegin}\label{wxhvscrolledwindowgetvisiblebegin}

\constfunc{wxPoint}{GetVisibleBegin}{\void}

Returns the indicies of the first visible row (Y) and column (X).

\wxheading{See also}

\helpref{GetVisibleRowsBegin}{wxhvscrolledwindowgetvisiblerowsbegin}, \helpref{GetVisibleColumnsBegin}{wxhvscrolledwindowgetvisiblecolumnsbegin}


\membersection{wxHVScrolledWindow::GetVisibleColumnsBegin}\label{wxhvscrolledwindowgetvisiblecolumnsbegin}

\constfunc{size\_t}{GetVisibleColumnsBegin}{\void}

Returns the index of the first currently visible column.

\wxheading{See also}

\helpref{GetVisibleColumnsEnd}{wxhvscrolledwindowgetvisiblecolumnsend}


\membersection{wxHVScrolledWindow::GetVisibleColumnsEnd}\label{wxhvscrolledwindowgetvisiblecolumnsend}

\constfunc{size\_t}{GetVisibleColumnsEnd}{\void}

Returns the index of the first column after the currently visible page. If the
return value is $0$ it means that no columns 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{GetColumnCount}{wxhvscrolledwindowgetcolumncount}.

\wxheading{See also}

\helpref{GetVisibleColumnsBegin}{wxhvscrolledwindowgetvisiblecolumnsbegin}


\membersection{wxHVScrolledWindow::GetVisibleEnd}\label{wxhvscrolledwindowgetvisiblebegin}

\constfunc{wxPoint}{GetVisibleEnd}{\void}

Returns the indicies of the row and column after the last visible row (Y) and
last visible column (X), respectively.

\wxheading{See also}

\helpref{GetVisibleRowsEnd}{wxhvscrolledwindowgetvisiblerowsend}, \helpref{GetVisibleColumnsEnd}{wxhvscrolledwindowgetvisiblecolumnsend}


\membersection{wxHVScrolledWindow::GetVisibleRowsBegin}\label{wxhvscrolledwindowgetvisiblerowsbegin}

\constfunc{size\_t}{GetVisibleRowsBegin}{\void}

Returns the index of the first currently visible row.

\wxheading{See also}

\helpref{GetVisibleRowsEnd}{wxhvscrolledwindowgetvisiblerowsend}


\membersection{wxHVScrolledWindow::GetVisibleRowsEnd}\label{wxhvscrolledwindowgetvisiblerowsend}

\constfunc{size\_t}{GetVisibleRowsEnd}{\void}

Returns the index of the first row after the currently visible page. If the
return value is $0$ it means that no rows 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{GetRowCount}{wxhvscrolledwindowgetrowcount}.

\wxheading{See also}

\helpref{GetVisibleRowsBegin}{wxhvscrolledwindowgetvisiblerowsbegin}


\membersection{wxHVScrolledWindow::HitTest}\label{wxhvscrolledwindowhittest}

\constfunc{wxPoint}{HitTest}{\param{wxCoord }{x}, \param{wxCoord }{y}}

\constfunc{wxPoint}{HitTest}{\param{const wxPoint\& }{pt}}

Return the position (X as column, Y as row) of the cell occupying the specified
position (in physical coordinates). A value of {\tt wxNOT\_FOUND} in either X,
Y, or X and Y means it is outside the range availible rows and/or columns.


\membersection{wxHVScrolledWindow::IsColumnVisible}\label{wxhvscrolledwindowiscolumnvisible}

\constfunc{bool}{IsColumnVisible}{\param{size\_t}{column}}

Returns {\tt true} if the given column is at least partially visible or
{\tt false} otherwise.


\membersection{wxHVScrolledWindow::IsRowVisible}\label{wxhvscrolledwindowisrowvisible}

\constfunc{bool}{IsRowVisible}{\param{size\_t }{row}}

Returns {\tt true} if the given row is at least partially visible or {\tt false}
otherwise.


\membersection{wxHVScrolledWindow::IsVisible}\label{wxhvscrolledwindowisvisible}

\constfunc{bool}{IsVisible}{\param{size\_t }{row}, \param{size\_t}{column}}

Returns {\tt true} if the given row and column are both at least partially
visible or {\tt false} otherwise.


\membersection{wxHVScrolledWindow::OnGetColumnWidth}\label{wxhvscrolledwindowongetcolumnwidth}

\constfunc{wxCoord}{OnGetColumnWidth}{\param{size\_t }{n}}

This protected pure virtual function must be overridden in the derived class
and should return the width of the given column in pixels.

\wxheading{See also}

\helpref{OnGetColumnsWidthHint}{wxhvscrolledwindowongetcolumnswidthhint}


\membersection{wxHVScrolledWindow::OnGetColumnsWidthHint}\label{wxhvscrolledwindowongetcolumnswidthhint}

\constfunc{void}{OnGetColumnsWidthHint}{\param{size\_t }{columnMin}, \param{size\_t }{columnMax}}

This function doesn't have to be overridden but it may be useful to do
it if calculating the columns' heights is a relatively expensive operation
as it gives the user code a possibility to calculate several of them at
once.

{\tt OnGetColumnsWidthHint()} is normally called just before 
\helpref{OnGetColumnWidth()}{wxhvscrolledwindowongetcolumnwidth} but you
shouldn't rely on the latter being called for all columns in the interval
specified here. It is also possible that OnGetColumnWidth() will be
called for the columns outside of this interval, so this is really just a
hint, not a promise.

Finally note that {\it columnMin} is inclusive, while {\it columnMax} is exclusive,
as usual.


\membersection{wxHVScrolledWindow::OnGetRowHeight}\label{wxhvscrolledwindowongetrowheight}

\constfunc{wxCoord}{OnGetRowHeight}{\param{size\_t }{n}}

This protected pure virtual function must be overridden in the derived class
and should return the height of the given row in pixels.

\wxheading{See also}

\helpref{OnGetRowsHeightHint}{wxhvscrolledwindowongetrowsheighthint}


\membersection{wxHVScrolledWindow::OnGetRowsHeightHint}\label{wxhvscrolledwindowongetrowsheighthint}

\constfunc{void}{OnGetRowsHeightHint}{\param{size\_t }{rowMin}, \param{size\_t }{rowMax}}

This function doesn't have to be overridden but it may be useful to do
it if calculating the row's heights is a relatively expensive operation
as it gives the user code a possibility to calculate several of them at
once.

{\tt OnGetRowsHeightHint()} is normally called just before 
\helpref{OnGetRowHeight()}{wxhvscrolledwindowongetrowheight} but you
shouldn't rely on the latter being called for all rows in the interval
specified here. It is also possible that OnGetRowHeight() will be
called for the rows outside of this interval, so this is really just a
hint, not a promise.

Finally note that {\it rowMin} is inclusive, while {\it rowMax} is exclusive,
as usual.


\membersection{wxHVScrolledWindow::RefreshColumn}\label{wxhvscrolledwindowrefreshcolumn}

\func{void}{RefreshColumn}{\param{size\_t }{column}}

Refreshes the specified column -- it will be redrawn during the next main loop
iteration.


\membersection{wxHVScrolledWindow::RefreshRow}\label{wxhvscrolledwindowrefreshrow}

\func{void}{RefreshRow}{\param{size\_t }{row}}

Refreshes the specified row -- it will be redrawn during the next main loop
iteration.


\membersection{wxHVScrolledWindow::RefreshRowColumn}\label{wxhvscrolledwindowrefreshrowcolumn}

\func{void}{RefreshRowColumn}{\param{size\_t }{row}, \param{size\_t }{column}}

Refreshes the specified cell -- it will be redrawn during the next main loop
iteration.

\wxheading{See also}

\helpref{RefreshRowsColumns}{wxhvscrolledwindowrefreshrowscolumns}


\membersection{wxHVScrolledWindow::RefreshColumns}\label{wxhvscrolledwindowrefreshcolumns}

\func{void}{RefreshColumns}{\param{size\_ t}{fromColumn}, \param{size\_t }{toColumn}}

Refreshes the columns between {\it fromColumn} and {\it toColumn} (inclusive).
{\it fromColumn} should be less than or equal to {\it toColumn}.

\wxheading{See also}

\helpref{RefreshColumn}{wxhvscrolledwindowrefreshcolumn}


\membersection{wxHVScrolledWindow::RefreshRows}\label{wxhvscrolledwindowrefreshrows}

\func{void}{RefreshRows}{\param{size\_ t}{fromRow}, \param{size\_t }{toRow}}

Refreshes the rows between {\it fromRow} and {\it toRow} (inclusive).
{\it fromRow} should be less than or equal to {\it toRow}.

\wxheading{See also}

\helpref{RefreshRow}{wxhvscrolledwindowrefreshrow}


\membersection{wxHVScrolledWindow::RefreshRowsColumns}\label{wxhvscrolledwindowrefreshrowscolumns}

\func{void}{RefreshRowsColumns}{\param{size\_t }{fromRow}, \param{size\_t }{toRow}, \param{size\_ t}{fromColumn}, \param{size\_t }{toColumn}}

Refreshes the region of cells between {\it fromRow}, {\it fromColumn} and
{\it toRow}, {\it toColumn} (inclusive). {\it fromRow} and {\it fromColumn}
should be less than or equal to {\it toRow} and {\it toColumn}, respectively.

\wxheading{See also}

\helpref{RefreshRowColumn}{wxhvscrolledwindowrefreshrowcolumn}


\membersection{wxHVScrolledWindow::RefreshAll}\label{wxhvscrolledwindowrefreshall}

\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 either \helpref{OnGetRowHeight}{wxhvscrolledwindowongetrowheight} or 
\helpref{OnGetColumnWidth}{wxhvscrolledwindowongetcolumnwidth} change for some
reason and the window must be updated to reflect this.


\membersection{wxHVScrolledWindow::ScrollColumns}\label{wxhvscrolledwindowscrollcolumns}

\func{bool}{ScrollColumns}{\param{int }{columns}}

Scroll by the specified number of columns which may be positive (to scroll
right) or negative (to scroll left).

Returns {\tt true} if the window was scrolled, {\tt false} otherwise (for
example if we're trying to scroll right but we are already showing the last
column).


\membersection{wxHVScrolledWindow::ScrollRows}\label{wxhvscrolledwindowscrollrows}

\func{bool}{ScrollRows}{\param{int }{rows}}

Scroll by the specified number of rows 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
row).

\wxheading{See also}

\helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}


\membersection{wxHVScrolledWindow::ScrollRowsColumns}\label{wxhvscrolledwindowscrollrowscolumns}

\func{bool}{ScrollRowsColumns}{\param{int }{rows}, \param{int }{columns}}

Scroll by the specified number of rows and columns which may be positive (to
scroll down or right) or negative (to scroll up or left).

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
row).

\wxheading{See also}

\helpref{LineUp}{wxwindowlineup}, \helpref{LineDown}{wxwindowlinedown}


\membersection{wxHVScrolledWindow::ScrollColumnPages}\label{wxhvscrolledwindowscrollcolumnpages}

\func{bool}{ScrollColumnPages}{\param{int }{columnPages}}

Scroll by the specified number of column pages, which may be positive (to
scroll right) or negative (to scroll left).


\membersection{wxHVScrolledWindow::ScrollPages}\label{wxhvscrolledwindowscrollpages}

\func{bool}{ScrollPages}{\param{int }{rowPages}, \param{int }{columnPages}}

Scroll by the specified number of row pages and column pages, both of which may
be positive (to scroll down or right) or negative (to scroll up or left).

\wxheading{See also}

\helpref{ScrollRowsColumns}{wxhvscrolledwindowscrollrowscolumns},\\
\helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}


\membersection{wxHVScrolledWindow::ScrollRowPages}\label{wxhvscrolledwindowscrollrowpages}

\func{bool}{ScrollRowPages}{\param{int }{rowPages}}

Scroll by the specified number of row pages, which may be positive (to scroll
down) or negative (to scroll up).

\wxheading{See also}

\helpref{PageUp}{wxwindowpageup}, \helpref{PageDown}{wxwindowpagedown}


\membersection{wxHVScrolledWindow::ScrollToColumn}\label{wxhvscrolledwindowscrolltocolumn}

\func{bool}{ScrollToColumn}{\param{size\_t }{column}}

Scroll to the specified column. The specified column will be the first visible
column on the left side afterwards.

Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.


\membersection{wxHVScrolledWindow::ScrollToRow}\label{wxhvscrolledwindowscrolltorow}

\func{bool}{ScrollToRow}{\param{size\_t }{row}}

Scroll to the specified row. The specified column will be the first visible row
on the top afterwards.

Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.


\membersection{wxHVScrolledWindow::ScrollToRowColumn}\label{wxhvscrolledwindowscrolltorowcolumn}

\func{bool}{ScrollToRowColumn}{\param{size\_t }{row}, \param{size\_t }{column}}

Scroll to the specified row and column. The cell described will be the top left
visible cell afterwards.

Return {\tt true} if we scrolled the window, {\tt false} if nothing was done.


\membersection{wxHVScrolledWindow::SetRowColumnCounts}\label{wxhvscrolledwindowsetrowcolumncounts}

\func{void}{SetLineCount}{\param{size\_t }{row}, \param{size\_t }{column}}

Set the number of rows and columns the window contains. The derived class must
provide the heights for all rows and the widths for all columns with indices up
to the respective values given here in its 
\helpref{OnGetRowHeight()}{wxhvscrolledwindowongetrowheight} and 
\helpref{OnGetColumnWidth()}{wxhvscrolledwindowongetcolumnwidth}
implementations.