X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/scrolwin.h?ds=inline diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h index b05bc233fc..e1ecdc44a4 100644 --- a/interface/wx/scrolwin.h +++ b/interface/wx/scrolwin.h @@ -2,12 +2,20 @@ // Name: scrolwin.h // Purpose: interface of wxScrolled template // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** - @wxheader{scrolwin.h} + 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 the coordinates according to the scrollbar positions, and setting the @@ -23,7 +31,7 @@ - ::wxScrolledCanvas, aka wxScrolled, derives from wxWindow and so doesn't handle children specially. This is suitable e.g. for - implementating scrollable controls such as tree or list controls. + implementing scrollable controls such as tree or list controls. Starting from version 2.4 of wxWidgets, there are several ways to use a ::wxScrolledWindow (and now wxScrolled). In particular, there are @@ -59,6 +67,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". @@ -87,10 +98,51 @@ of (10,-90). @beginStyleTable + @style{wxHSCROLL} + If this style is specified and ::wxVSCROLL isn't, the window will be + scrollable only in horizontal direction (by default, i.e. if neither + this style nor ::wxVSCROLL is specified, it scrolls in both + directions). + @style{wxVSCROLL} + If this style is specified and ::wxHSCROLL isn't, the window will be + scrollable only in vertical direction (by default, i.e. if neither + this style nor ::wxHSCROLL is specified, it scrolls in both + directions). + @style{wxALWAYS_SHOW_SB} + Since wxWidgets 2.9.5, specifying this style makes the window always + show its scrollbars, even if they are not used. See ShowScrollbars(). @style{wxRETAINED} Uses a backing pixmap to speed refreshes. Motif only. @endStyleTable + + @beginEventEmissionTable{wxScrollWinEvent} + @event{EVT_SCROLLWIN(func)} + Process all scroll events. + @event{EVT_SCROLLWIN_TOP(func)} + Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events. + @event{EVT_SCROLLWIN_BOTTOM(func)} + Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. + @event{EVT_SCROLLWIN_LINEUP(func)} + Process @c wxEVT_SCROLLWIN_LINEUP line up events. + @event{EVT_SCROLLWIN_LINEDOWN(func)} + Process @c wxEVT_SCROLLWIN_LINEDOWN line down events. + @event{EVT_SCROLLWIN_PAGEUP(func)} + Process @c wxEVT_SCROLLWIN_PAGEUP page up events. + @event{EVT_SCROLLWIN_PAGEDOWN(func)} + Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events. + @event{EVT_SCROLLWIN_THUMBTRACK(func)} + Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events + (frequent events sent as the user drags the thumbtrack). + @event{EVT_SCROLLWIN_THUMBRELEASE(func)} + Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. + @endEventTable + + @note + Don't confuse wxScrollWinEvents generated by this class with + wxScrollEvent objects generated by wxScrollBar and wxSlider. + + @remarks Use wxScrolled for applications where the user scrolls by a fixed amount, and where a 'page' can be interpreted to be the current visible portion of @@ -123,10 +175,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. @@ -143,7 +195,6 @@ public: long style = wxHSCROLL | wxVSCROLL, const wxString& name = "scrolledWindow"); - /** Translates the logical coordinates to the device ones. For example, if a window is scrolled 10 pixels to the bottom, the device coordinates of @@ -151,9 +202,15 @@ 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; + wxPoint CalcScrolledPosition(const wxPoint& pt) const; /** Translates the device coordinates to the logical ones. For example, if @@ -162,9 +219,15 @@ 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; + wxPoint CalcUnscrolledPosition(const wxPoint& pt) const; /** Creates the window for two-step construction. Derived classes @@ -177,16 +240,32 @@ 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. It sets the device origin according to the current scroll position. - DoPrepareDC() is called automatically within the default OnPaint() - event handler, so your OnDraw() override will be passed a + DoPrepareDC() is called automatically within the default @c wxEVT_PAINT + event handler, so your OnDraw() override will be passed an already '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. + outside of OnDraw() (e.g. from your own @c wxEVT_PAINT handler), you + must call this function yourself. For example: @code @@ -207,28 +286,61 @@ public: } @endcode + Notice that the function sets the origin by moving it relatively to the + current origin position, so you shouldn't change the origin before + calling DoPrepareDC() or, if you do, reset it to (0, 0) later. If you + call DoPrepareDC() immediately after device context creation, as in the + example above, this problem doesn't arise, of course, so it is + customary to do it like this. */ void DoPrepareDC(wxDC& dc); /** - 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. Note that you - will have to reposition child windows yourself, if physical scrolling - is disabled. + Enable or disable use of wxWindow::ScrollWindow() for scrolling. + + By default, when a scrolled window is logically scrolled, + wxWindow::ScrollWindow() is called on the underlying window which + scrolls the window contents and only invalidates the part of the window + newly brought into view. If @false is passed as an argument, then this + "physical scrolling" is disabled and the window is entirely invalidated + whenever it is scrolled by calling wxWindow::Refresh(). + + It should be rarely necessary to disable physical scrolling, so this + method shouldn't be called in normal circumstances. @param xScrolling If @true, enables physical scrolling in the x direction. @param yScrolling If @true, enables physical scrolling in the y direction. - - @remarks Physical scrolling may not be available on all platforms. Where - it is available, it is enabled by default. */ 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 @@ -239,6 +351,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; @@ -251,19 +368,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 @@ -277,6 +405,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; @@ -315,14 +448,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(). @@ -382,20 +520,82 @@ 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); + wxWindow *GetTargetWindow() const; + + + void SetTargetRect(const wxRect& rect); + wxRect GetTargetRect() const; + + int GetScrollPageSize(int orient) const; + void SetScrollPageSize(int orient, int pageSize); + int GetScrollLines( int orient ) const; + void SetScale(double xs, double ys); + double GetScaleX() const; + double GetScaleY() const; + + virtual void AdjustScrollbars(); + + /** + Are we generating the autoscroll events? + */ + bool IsAutoScrolling() const; + + /** + Stop generating the scroll events when mouse is held outside the + window. + */ + void StopAutoScrolling(); + + /** + This method can be overridden in a derived class to forbid sending the + auto scroll events - note that unlike StopAutoScrolling() it doesn't + stop the timer, so it will be called repeatedly and will typically + return different values depending on the current mouse position + + The base class version just returns true. */ - void SetTargetWindow(wxWindow* window); + virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const; + + +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); }; /** Scrolled window derived from wxPanel. - See wxScrolled for detailed description. + See wxScrolled for a detailed description. @note Note that because this class derives from wxPanel, it shares its - behavior with regard to TAB traversal and focus handling (in + behaviour with regard to TAB traversal and focus handling (in particular, it forwards focus to its children). If you don't want this behaviour, use ::wxScrolledCanvas instead.