don't place NULL pointers in the GDK window array in GTKGetWindow()

[wxWidgets.git] / interface / wx / scrolwin.h

diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h
index b05bc233fcbed3a6b4150766de0cfb218330e3db..f5762e7e5e77a099873a7101d60d9aac256f89a4 100644 (file)
--- a/interface/wx/scrolwin.h
+++ b/interface/wx/scrolwin.h
@@ -7,7 +7,16 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @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
 
     The wxScrolled class manages scrolling for its client area, transforming
     the coordinates according to the scrollbar positions, and setting the


@@ -59,6 +68,9 @@
     wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or
     similar and remove it entirely in future.
 
     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".
 
     As with all windows, an application can draw onto a wxScrolled using a
     @ref overview_dc "device context".
 


@@ -123,10 +135,10 @@ public:
         @param id
             Window identifier. The value @c wxID_ANY indicates a default value.
         @param pos
         @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
             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.
             window is sized appropriately.
         @param style
             Window style. See wxScrolled.


@@ -182,11 +194,11 @@ public:
         image.
 
         It sets the device origin according to the current scroll position.
         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
         '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
 
         For example:
         @code


@@ -207,6 +219,12 @@ public:
         }
         @endcode
 
         }
         @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);
 
     */
     void DoPrepareDC(wxDC& dc);
 


@@ -229,6 +247,32 @@ public:
     */
     void EnableScrolling(bool xScrolling, bool yScrolling);
 
     */
     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
     /**
         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


@@ -251,19 +295,25 @@ public:
         @param y
             Receives the first visible y position in scroll units.
 
         @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;
 
     */
     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
     /**
         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


@@ -315,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
 
         @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);
 
 
         @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().
     /**
         Set the horizontal and vertical scrolling increment only. See the
         pixelsPerUnit parameter in SetScrollbars().


@@ -382,10 +437,36 @@ public:
                        bool noRefresh = false);
 
     /**
                        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);

 };
 
 
 };