// 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
- ::wxScrolledCanvas, aka wxScrolled<wxWindow>, 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
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".
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
@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.
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
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
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
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
}
@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
@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;
@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
@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;
@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().
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.
projects / wxWidgets.git / blobdiff