X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..a2e50fc2abd2d544ca2d2a884067bcd2e3b4b35b:/interface/wx/scrolwin.h

diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h
index b73f8464b4..aff424c547 100644
--- a/interface/wx/scrolwin.h
+++ b/interface/wx/scrolwin.h
@@ -58,6 +58,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".
 
@@ -181,11 +184,11 @@ public:
         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
@@ -206,6 +209,12 @@ 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);
 
@@ -381,10 +390,36 @@ 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);
+    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);
 };