the coordinates according to the scrollbar positions, and setting the
scroll positions, thumb sizes and ranges according to the area in view.
-As with all windows, an application can draw onto a wxScrolledWindow using a \helpref{device context}{dcoverview}.
+Starting from version 2.4 of wxWindows, there are several ways to use a
+wxScrolledWindow. In particular, there are now three ways to set the
+size of the scrolling area:
+
+One way is to set the scrollbars directly using a call to
+\helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}.
+This is the way it used to be in any previous version of wxWindows
+and it will be kept for backwards compatibility.
+
+An additional method of manual control, which requires a little less
+computation of your own, is to set the total size of the scrolling area by
+calling either \helpref{wxWindow::SetVirtualSize}{wxwindowsetvirtualsize},
+or \helpref{wxWindow::FitInside}{wxwindowfitinside}, and setting the
+scrolling increments for it by calling
+\helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
+Scrolling in some orientation is enabled by setting a non zero increment
+for it.
+
+The most automatic and newest way is to simply let sizers determine the
+scrolling area. This is now the default when you set an interior sizer
+into a wxScrolledWindow with \helpref{wxWindow::SetSizer}{wxwindowsetsizer}.
+The scrolling area will be set to the size requested by the sizer and
+the scrollbars will be assigned for each orientation according to the need
+for them and the scrolling increment set by
+\helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
+As above, scrolling is only enabled in orientations with a non-zero
+increment. You can influence the minimum size of the scrolled area
+controlled by a sizer by calling
+\helpref{wxWindow::SetVirtualSizeHints}{wxwindowsetvirtualsizehints}.
+(calling \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
+ has analogous effects in wxWindows 2.4 -- in later versions it may not continue
+ to override the sizer)
+
+Note: if Maximum size hints are still supported by SetVirtualSizeHints, use
+them at your own dire risk. They may or may not have been removed for 2.4,
+but it really only makes sense to set minimum size hints here. We should
+probably replace SetVirtualSizeHints with SetMinVirtualSize or similar
+and remove it entirely in future.
+
+As with all windows, an application can draw onto a wxScrolledWindow using
+a \helpref{device context}{dcoverview}.
You have the option of handling the OnPaint handler
or overriding the \helpref{OnDraw}{wxscrolledwindowondraw} function, which is passed
\wxheading{See also}
-\helpref{wxScrollBar}{wxscrollbar}, \helpref{wxClientDC}{wxclientdc}, \helpref{wxPaintDC}{wxpaintdc}
+\helpref{wxScrollBar}{wxscrollbar}, \helpref{wxClientDC}{wxclientdc},\\
+\helpref{wxPaintDC}{wxpaintdc}, \helpref{wxVScrolledWindow}{wxvscrolledwindow}
\latexignore{\rtfignore{\wxheading{Members}}}
\wxheading{Parameters}
-\docparam{xScrolling}{If TRUE, enables physical scrolling in the x direction.}
+\docparam{xScrolling}{If true, enables physical scrolling in the x direction.}
-\docparam{yScrolling}{If TRUE, enables physical scrolling in the y direction.}
+\docparam{yScrolling}{If true, enables physical scrolling in the y direction.}
\wxheading{Remarks}
\perlnote{In wxPerl this method takes no parameters and returns a
2-element list {\tt ( xUnit, yUnit )}.}
+\membersection{wxScrolledWindow::GetViewStart}\label{wxscrolledwindowgetviewstart}
+
+\constfunc{void}{GetViewStart}{\param{int* }{x}, \param{int* }{ y}}
+
+Get the position at which the visible portion of the window starts.
+
+\wxheading{Parameters}
+
+\docparam{x}{Receives the first visible x position in scroll units.}
+
+\docparam{y}{Receives the first visible y position in scroll units.}
+
+\wxheading{Remarks}
+
+If either of the scrollbars is not at the home position, {\it x} and/or
+\rtfsp{\it y} will be greater than zero. Combined with \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize},
+the application can use this function to efficiently redraw only the
+visible portion of the window. The positions are in logical scroll
+units, not pixels, so to convert to pixels you will have to multiply
+by the number of pixels per scroll increment.
+
+\wxheading{See also}
+
+\helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
+
+\pythonnote{The wxPython version of this methods accepts no
+parameters and returns a tuple of values for x and y.}
+
+\perlnote{In wxPerl this method takes no parameters and returns a
+2-element list {\tt ( x, y )}.}
+
\membersection{wxScrolledWindow::GetVirtualSize}\label{wxscrolledwindowgetvirtualsize}
\constfunc{void}{GetVirtualSize}{\param{int* }{x}, \param{int* }{y}}
\constfunc{bool}{IsRetained}{\void}
-Motif only: TRUE if the window has a backing bitmap.
+Motif only: true if the window has a backing bitmap.
\membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc}
\func{void}{SetScrollbars}{\param{int}{ pixelsPerUnitX}, \param{int}{ pixelsPerUnitY},\rtfsp
\param{int}{ noUnitsX}, \param{int}{ noUnitsY},\rtfsp
\param{int }{xPos = 0}, \param{int}{ yPos = 0},\rtfsp
-\param{bool }{noRefresh = FALSE}}
+\param{bool }{noRefresh = false}}
Sets up vertical and/or horizontal scrollbars.
\docparam{yPos}{Position to initialize the scrollbars in the vertical direction, in scroll units.}
-\docparam{noRefresh}{Will not refresh window if TRUE.}
+\docparam{noRefresh}{Will not refresh window if true.}
\wxheading{Remarks}
necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
adjusting the scrollbars appropriately.
-\membersection{wxScrolledWindow::SetTargetWindow}\label{wxscrolledwindowsettargetwindow}
-
-\func{void}{SetTargetWindow}{\param{wxWindow* }{window}}
-
-Call this function to tell wxScrolledWindow to perform the actually scrolling on
-a different window (not on itself).
-
-\membersection{wxScrolledWindow::GetViewStart}\label{wxscrolledwindowgetviewstart}
-
-\constfunc{void}{GetViewStart}{\param{int* }{x}, \param{int* }{ y}}
-
-Get the position at which the visible portion of the window starts.
+\wxheading{See also}
-\wxheading{Parameters}
+\helpref{wxWindow::SetVirtualSize}{wxwindowsetvirtualsize}
-\docparam{x}{Receives the first visible x position in scroll units.}
+\membersection{wxScrolledWindow::SetScrollRate}\label{wxscrolledwindowsetscrollrate}
-\docparam{y}{Receives the first visible y position in scroll units.}
+\func{void}{SetScrollRate}{\param{int}{ xstep}, \param{int}{ ystep}}
-\wxheading{Remarks}
+Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit
+parameter in SetScrollbars.
-If either of the scrollbars is not at the home position, {\it x} and/or
-\rtfsp{\it y} will be greater than zero. Combined with \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize},
-the application can use this function to efficiently redraw only the
-visible portion of the window. The positions are in logical scroll
-units, not pixels, so to convert to pixels you will have to multiply
-by the number of pixels per scroll increment.
-
-\wxheading{See also}
-
-\helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
+\membersection{wxScrolledWindow::SetTargetWindow}\label{wxscrolledwindowsettargetwindow}
-\pythonnote{The wxPython version of this methods accepts no
-parameters and returns a tuple of values for x and y.}
+\func{void}{SetTargetWindow}{\param{wxWindow* }{window}}
-\perlnote{In wxPerl this method takes no parameters and returns a
-2-element list {\tt ( x, y )}.}
+Call this function to tell wxScrolledWindow to perform the actual scrolling on
+a different window (and not on itself).
projects / wxWidgets.git / blobdiff