don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / scrolwin.h
index 454af1e4ee7d0cebe289478caa4d81340b9dbd83..f5762e7e5e77a099873a7101d60d9aac256f89a4 100644 (file)
@@ -6,6 +6,16 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    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 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.
 
     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".
 
@@ -122,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.
@@ -234,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
@@ -256,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
@@ -320,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().