X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/60a14f1bf2e3c9a6101c1a23128f8a8b5d656803..591cc82deb5bc6dd0af6047ecfa7ce7cf4f8d859:/interface/wx/scrolwin.h diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h index 873a2182cc..8f8287d224 100644 --- a/interface/wx/scrolwin.h +++ b/interface/wx/scrolwin.h @@ -6,6 +6,16 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Possible values for the second argument of wxScrolled::ShowScrollbars(). + */ +enum wxScrollbarVisibility +{ + wxSHOW_SB_NEVER = -1, ///< Never show the scrollbar at all. + wxSHOW_SB_DEFAULT, ///< Show scrollbar only if it is needed. + wxSHOW_SB_ALWAYS ///< Always show scrollbar, even if not needed. +}; + /** The wxScrolled class manages scrolling for its client area, transforming @@ -58,6 +68,9 @@ wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or similar and remove it entirely in future. + @todo review docs for this class replacing SetVirtualSizeHints() with + SetMinClientSize(). + As with all windows, an application can draw onto a wxScrolled using a @ref overview_dc "device context". @@ -234,6 +247,32 @@ public: */ void EnableScrolling(bool xScrolling, bool yScrolling); + /** + Set the scrollbar visibility. + + By default the scrollbar in the corresponding direction is only shown + if it is needed, i.e. if the virtual size of the scrolled window in + this direction is greater than the current physical window size. Using + this function the scrollbar visibility can be changed to be: + - wxSHOW_SB_ALWAYS: To always show the scrollbar, even if it is + not needed currently (wxALWAYS_SHOW_SB style can be used during + the window creation to achieve the same effect but it applies + in both directions). + - wxSHOW_SB_NEVER: To never show the scrollbar at all. In this case + the program should presumably provide some other way for the + user to scroll the window. + - wxSHOW_SB_DEFAULT: To restore the default behaviour described + above. + + @param horz + The desired visibility for the horizontal scrollbar. + @param vert + The desired visibility for the vertical scrollbar. + + @since 2.9.0 + */ + void ShowScrollbars(wxScrollbarVisibility horz, wxScrollbarVisibility vert); + /** Get the number of pixels per scroll unit (line), in each direction, as set by SetScrollbars(). A value of zero indicates no scrolling in that @@ -256,19 +295,25 @@ public: @param y Receives the first visible y position in scroll units. - @remarks If either of the scrollbars is not at the home position, x - and/or y will be greater than zero. Combined with - wxWindow::GetClientSize(), 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. + @remarks + If either of the scrollbars is not at the home position, @a x + and/or @a y will be greater than zero. + Combined with wxWindow::GetClientSize(), 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. - @see SetScrollbars() + @see SetScrollbars(), Scroll() */ void GetViewStart(int* x, int* y) const; + /** + This is a simple overload of GetViewStart(int*,int*); see that function + for more info. + */ + wxPoint GetViewStart() const; + /** Gets the size in device units of the scrollable window area (as opposed to the client size, which is the area of the window currently @@ -320,14 +365,19 @@ public: @remarks The positions are in scroll units, not pixels, so to convert to pixels you will have to multiply by the number of - pixels per scroll increment. If either parameter is -1, - that position will be ignored (no change in that - direction). + pixels per scroll increment. If either parameter is + ::wxDefaultCoord (-1), that position will be ignored (no change + in that direction). @see SetScrollbars(), GetScrollPixelsPerUnit() */ void Scroll(int x, int y); + /** + This is an overload of Scroll(int,int); see that function for more info. + */ + void Scroll(const wxPoint& pt); + /** Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit parameter in SetScrollbars(). @@ -387,10 +437,36 @@ public: bool noRefresh = false); /** - Call this function to tell wxScrolled to perform the actual - scrolling on a different window (and not on itself). + Call this function to tell wxScrolled to perform the actual scrolling + on a different window (and not on itself). + + This method is useful when only a part of the window should be + scrolled. A typical example is a control consisting of a fixed header + and the scrollable contents window: the scrollbars are attached to the + main window itself, hence it, and not the contents window must be + derived from wxScrolled, but only the contents window scrolls when the + scrollbars are used. To implement such setup, you need to call this + method with the contents window as argument. + + Notice that if this method is used, GetSizeAvailableForScrollTarget() + method must be overridden. */ - void SetTargetWindow(wxWindow* window); + void SetTargetWindow(wxWindow *window); + +protected: + /** + Function which must be overridden to implement the size available for + the scroll target for the given size of the main window. + + This method must be overridden if SetTargetWindow() is used (it is + never called otherwise). The implementation should decrease the @a size + to account for the size of the non-scrollable parts of the main window + and return only the size available for the scrollable window itself. + E.g. in the example given in SetTargetWindow() documentation the + function would subtract the height of the header window from the + vertical component of @a size. + */ + virtual wxSize GetSizeAvailableForScrollTarget(const wxSize& size); };