X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..68304caffec13015b139c1d567733f14862ae2bd:/docs/latex/wx/scrolwin.tex?ds=sidebyside diff --git a/docs/latex/wx/scrolwin.tex b/docs/latex/wx/scrolwin.tex index bed28301c1..0129bee043 100644 --- a/docs/latex/wx/scrolwin.tex +++ b/docs/latex/wx/scrolwin.tex @@ -6,7 +6,7 @@ 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}. -You have the option of handling the \helpref{OnPaint}{wxscrolledwindowonpaint} handler +You have the option of handling the OnPaint handler or overriding the \helpref{OnDraw}{wxscrolledwindowondraw} function, which is passed a pre-scrolled device context (prepared by \helpref{PrepareDC}{wxscrolledwindowpreparedc}). @@ -14,12 +14,31 @@ If you don't wish to calculate your own scrolling, you must call PrepareDC when within OnDraw, to set the device origin for the device context according to the current scroll position. +A wxScrolledWindow will normally scroll itself and therefore its child windows as well. It +might however be desired to scroll a different window than itself: e.g. when designing a +spreadsheet, you will normally only have to scroll the (usually white) cell area, whereas the +(usually grey) label area will scroll very differently. For this special purpose, you can +call \helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} which means that pressing +the scrollbars will scroll a different window. + +Note that the underlying system knows nothing about scrolling coordinates, so that all system +functions (mouse events, expose events, refresh calls etc) as well as the position of subwindows +are relative to the "physical" origin of the scrolled window. If the user insert a child window at +position (10,10) and scrolls the window down 100 pixels (moving the child window out of the visible +area), the child window will report a position of (10,-90). + + \wxheading{Derived from} +\helpref{wxPanel}{wxpanel}\\ \helpref{wxWindow}{wxwindow}\\ \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \wxheading{Window styles} \twocolwidtha{5cm} @@ -48,9 +67,9 @@ to build your own scroll behaviour. Default constructor. -\func{}{wxScrolledWindow}{\param{wxWindow*}{ parent}, \param{const wxWindowID }{id = -1},\rtfsp +\func{}{wxScrolledWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp -\param{const long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}} +\param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}} Constructor. @@ -82,11 +101,57 @@ specify how big the virtual window size should be. Destructor. +\membersection{wxScrolledWindow::CalcScrolledPosition}\label{wxscrolledwindowcalcscrolledposition} + +\constfunc{void}{CalcScrolledPosition}{ + \param{int }{x}, + \param{int }{y}, + \param{int *}{xx} + \param{int *}{yy}} + +Translates the logical coordinates to the device ones. For example, if a window is +scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) +(as always), but the logical coordinates are (0, 10) and so the call to +CalcScrolledPosition(0, 10, \&xx, \&yy) will return 0 in yy. + +\wxheading{See also} + +\helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition} + +\pythonnote{The wxPython version of this methods accepts only two +parameters and returns xx and yy as a tuple of values.} + +\perlnote{In wxPerl this method takes two parameters and returns a +2-element list {\tt ( xx, yy )}.} + +\membersection{wxScrolledWindow::CalcUnscrolledPosition}\label{wxscrolledwindowcalcunscrolledposition} + +\constfunc{void}{CalcUnscrolledPosition}{ + \param{int }{x}, + \param{int }{y}, + \param{int *}{xx} + \param{int *}{yy}} + +Translates the device coordinates to the logical ones. For example, if a window is +scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) +(as always), but the logical coordinates are (0, 10) and so the call to +CalcUnscrolledPosition(0, 0, \&xx, \&yy) will return 10 in yy. + +\wxheading{See also} + +\helpref{CalcScrolledPosition}{wxscrolledwindowcalcscrolledposition} + +\pythonnote{The wxPython version of this methods accepts only two +parameters and returns xx and yy as a tuple of values.} + +\perlnote{In wxPerl this method takes two parameters and returns a +2-element list {\tt ( xx, yy )}.} + \membersection{wxScrolledWindow::Create}\label{wxscrolledwindowcreate} -\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{const wxWindowID }{id = -1},\rtfsp +\func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp -\param{const long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}} +\param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}} Creates the window for two-step construction. Derived classes should call or replace this function. See \helpref{wxScrolledWindow::wxScrolledWindow}{wxscrolledwindowconstr}\rtfsp @@ -100,7 +165,9 @@ Enable or disable physical scrolling in the given direction. Physical scrolling is the physical transfer of bits up or down the screen when a scroll event occurs. If the application scrolls by a variable amount (e.g. if there are different font sizes) then physical -scrolling will not work, and you should switch it off. +scrolling will not work, and you should switch it off. Note that you +will have to reposition child windows yourself, if physical scrolling +is disabled. \wxheading{Parameters} @@ -130,8 +197,13 @@ scrolling in that direction. \wxheading{See also} \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp -\helpref{wxScrolledWindow::GetVirtualSize}{wxscrolledwindowgetvirtualsize},\rtfsp -\helpref{wxWindow::GetScrollPage}{wxwindowgetscrollpage} +\helpref{wxScrolledWindow::GetVirtualSize}{wxscrolledwindowgetvirtualsize} + +\pythonnote{The wxPython version of this methods accepts no +parameters and returns a tuple of values for xUnit and yUnit.} + +\perlnote{In wxPerl this method takes no parameters and returns a +2-element list {\tt ( xUnit, yUnit )}.} \membersection{wxScrolledWindow::GetVirtualSize}\label{wxscrolledwindowgetvirtualsize} @@ -155,14 +227,19 @@ to translate these units to logical units. \wxheading{See also} \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp -\helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit},\rtfsp -\helpref{wxWindow::GetScrollPage}{wxwindowgetscrollpage} +\helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit} + +\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::IsRetained}\label{wxscrolledwindowisretained} \constfunc{bool}{IsRetained}{\void} -TRUE if the window has a backing bitmap. +Motif only: TRUE if the window has a backing bitmap. \membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc} @@ -171,14 +248,14 @@ TRUE if the window has a backing bitmap. Call this function to prepare the device context for drawing a scrolled image. It sets the device origin according to the current scroll position. -PrepareDC is called automatically within the default \helpref{wxScrolledWindow::OnPaint}{wxscrolledwindowonpaint} event +PrepareDC is called automatically within the default wxScrolledWindow::OnPaint event handler, so your \helpref{wxScrolledWindow::OnDraw}{wxscrolledwindowondraw} override will be passed a 'pre-scrolled' device context. However, if you wish to draw from outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must call this function yourself. For example: \begin{verbatim} -void MyCanvas::OnEvent(wxMouseEvent& event) +void MyWindow::OnEvent(wxMouseEvent& event) { wxClientDC dc(this); PrepareDC(dc); @@ -199,45 +276,13 @@ void MyCanvas::OnEvent(wxMouseEvent& event) \func{virtual void}{OnDraw}{\param{wxDC\& }{dc}} -Called by the default \helpref{wxScrolledWindow::OnPaint}{wxscrolledwindowonpaint} implementation -to allow the application to define painting behaviour without having to worry about -calling \helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}. - -\membersection{wxScrolledWindow::OnPaint}\label{wxscrolledwindowonpaint} - -\func{void}{OnPaint}{\param{wxPaintEvent\& }{event}} - -Sent to the window when the window must be refreshed. - -For more details, see \helpref{wxWindow::OnPaint}{wxwindowonpaint}. - -The default implementation for wxScrolledWindow's OnPaint handler is simply: - -\begin{verbatim} -void wxScrolledWindow::OnPaint(wxPaintEvent& event) -{ - wxPaintDC dc(this); - PrepareDC(dc); - - OnDraw(dc); -} -\end{verbatim} - -\membersection{wxScrolledWindow::OnScroll}\label{wxscrolledwindowonscroll} - -\func{void}{OnScroll}{\param{wxScrollEvent\& }{event}} - -Override this function to intercept scroll events. This -member function implements the default scroll behaviour. If -you do not call the default function, you will have to manage -all scrolling behaviour including drawing the window contents -at an appropriate position relative to the scrollbars. - -For more details, see \helpref{wxWindow::OnScroll}{wxwindowonscroll}. - -\wxheading{See also} +Called by the default paint event handler to allow the application to define +painting behaviour without having to worry about calling +\helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}. -\helpref{wxScrollEvent}{wxscrollevent} +Instead of overriding this function you may also just process the paint event +in the derived class as usual, but then you will have to call PrepareDC() +yourself. \membersection{wxScrolledWindow::Scroll}\label{wxscrolledwindowscroll} @@ -267,7 +312,8 @@ that direction). \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}} +\param{int }{xPos = 0}, \param{int}{ yPos = 0},\rtfsp +\param{bool }{noRefresh = FALSE}} Sets up vertical and/or horizontal scrollbars. @@ -285,6 +331,8 @@ 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.} + \wxheading{Remarks} The first pair of parameters give the number of pixels per `scroll step', i.e. amount @@ -310,9 +358,16 @@ scroll steps may be variable according to the position in the document, it will necessary to derive a new class from wxWindow, overriding {\bf OnSize} and adjusting the scrollbars appropriately. -\membersection{wxScrolledWindow::ViewStart}\label{wxscrolledwindowviewstart} +\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). -\constfunc{void}{ViewStart}{\param{int* }{x}, \param{int* }{ y}} +\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. @@ -335,3 +390,9 @@ by the number of pixels per scroll increment. \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 )}.} +