X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1058f652031c9b99daa7c701f09f16c3af7159c1..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/scrolwin.h diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h index 9749ef7e8c..6234faf54c 100644 --- a/interface/wx/scrolwin.h +++ b/interface/wx/scrolwin.h @@ -3,7 +3,7 @@ // Purpose: interface of wxScrolled template // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -32,7 +32,7 @@ enum wxScrollbarVisibility - ::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 @@ -99,10 +99,51 @@ enum wxScrollbarVisibility 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 @@ -155,7 +196,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 @@ -171,6 +211,7 @@ public: @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 @@ -187,6 +228,7 @@ public: @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 @@ -199,6 +241,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. @@ -239,21 +297,22 @@ public: 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); @@ -477,6 +536,42 @@ public: 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. + */ + virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const; + protected: /** @@ -498,10 +593,10 @@ protected: /** 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.