X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1d7b600d633f7942fc43baa5fbfb88aead1631c0..9ceed261f809dacf8f64c2287c5de9e45d22e5cb:/interface/wx/scrolwin.h diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h index 454af1e4ee..d601b47f86 100644 --- a/interface/wx/scrolwin.h +++ b/interface/wx/scrolwin.h @@ -3,9 +3,19 @@ // Purpose: interface of wxScrolled template // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + 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". @@ -122,10 +135,10 @@ public: @param id Window identifier. The value @c wxID_ANY indicates a default value. @param pos - Window position. If a position of @c wxDefaultPosition is specified + Window position. If a position of ::wxDefaultPosition is specified then a default position is chosen. @param size - Window size. If a size of @c wxDefaultSize is specified then the + Window size. If a size of ::wxDefaultSize is specified then the window is sized appropriately. @param style Window style. See wxScrolled. @@ -150,6 +163,11 @@ public: 10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return 0 in yy. + @beginWxPerlOnly + In wxPerl this method takes two parameters and returns a + 2-element list (xx, yy). + @endWxPerlOnly + @see CalcUnscrolledPosition() */ void CalcScrolledPosition(int x, int y, int* xx, int* yy) const; @@ -161,6 +179,11 @@ public: 10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return 10 in yy. + @beginWxPerlOnly + In wxPerl this method takes two parameters and returns a + 2-element list (xx, yy). + @endWxPerlOnly + @see CalcScrolledPosition() */ void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const; @@ -176,6 +199,22 @@ public: long style = wxHSCROLL | wxVSCROLL, const wxString& name = "scrolledWindow"); + /** + Disable use of keyboard keys for scrolling. + + By default cursor movement keys (including Home, End, Page Up and Down) + are used to scroll the window appropriately. If the derived class uses + these keys for something else, e.g. changing the currently selected + item, this function can be used to disable this behaviour as it's not + only not necessary then but can actually be actively harmful if another + object forwards a keyboard event corresponding to one of the above keys + to us using ProcessWindowEvent() because the event will always be + processed which can be undesirable. + + @since 2.9.1 + */ + void DisableKeyboardScrolling(); + /** Call this function to prepare the device context for drawing a scrolled image. @@ -234,6 +273,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 @@ -244,6 +309,11 @@ public: @param yUnit Receives the number of pixels per vertical unit. + @beginWxPerlOnly + In wxPerl this method takes no parameters and returns a + 2-element list (xUnit, yUnit). + @endWxPerlOnly + @see SetScrollbars(), GetVirtualSize() */ void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const; @@ -256,19 +326,30 @@ 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. - - @see SetScrollbars() + @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. + + @beginWxPerlOnly + In wxPerl this method takes no parameters and returns a + 2-element list (x, y). + @endWxPerlOnly + + @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 @@ -282,6 +363,11 @@ public: @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to translate these units to logical units. + @beginWxPerlOnly + In wxPerl this method takes no parameters and returns a + 2-element list (xUnit, yUnit). + @endWxPerlOnly + @see SetScrollbars(), GetScrollPixelsPerUnit() */ void GetVirtualSize(int* x, int* y) const; @@ -320,14 +406,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().