document GetSizeAvailableForScrollTarget()

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56346 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -104,6 +104,11 @@ Changes in behaviour not resulting in compilation errors, please read this!
 
 - wxDocument::OnNewDocument() doesn't call OnCloseDocument() any more.
 
+- If you use wxScrolledWindow::SetTargetWindow() you must implement its
+  GetSizeAvailableForScrollTarget() method, please see its documentation for
+  more details.
+
+
 Changes in behaviour which may result in compilation errors
 -----------------------------------------------------------
 

docs/doxygen/overviews/changes_since28.h

@@ -153,5 +153,10 @@ Finally, a few structure fields, notable @c wxCmdLineEntryDesc::shortName,
 - wxTE_AUTO_SCROLL style is deprecated as it's always on by default anyhow in
   the ports which support it so you should simply remove any mentions of it
   from your code.
+
+- If you use wxScrolled<T>::SetTargetWindow() you must override
+  wxScrolled<T>::GetSizeAvailableForScrollTarget() method to compute the size
+  available for the scroll target as function of the main window size, please
+  see the documentation of this method for more details.
 */
 

interface/wx/scrolwin.h

@@ -387,10 +387,36 @@ public:
                        bool noRefresh = false);
 
     /**
-        Call this function to tell wxScrolled to perform the actual
+        Call this function to tell wxScrolled to perform the actual scrolling
-        scrolling on a different window (and not on itself).
+        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);
 };