Merge branch 'html-print-cleanup'

Simplify wxHTML pagination code and make it easier to reuse from
applications.

See https://github.com/wxWidgets/wxWidgets/pull/817

interface/wx/html/htmlcell.h

@@ -187,34 +187,31 @@ public:
     wxHtmlCell();
 
     /**
-        This method is used to adjust pagebreak position.
-        The first parameter is a variable that contains the y-coordinate of the page break
-        (= horizontal line that should not be crossed by words, images etc.).
-        If this cell cannot be divided into two pieces (each one on another page)
-        then it either moves the pagebreak a few pixels up, if possible, or, if
-        the cell cannot fit on the page at all, then the cell is forced to
-        split unconditionally.
+        This method is called when paginating HTML, e.g.\ when printing.
 
-        Returns @true if pagebreak was modified, @false otherwise.
+        User code should never call this function, but may need to override it
+        in custom HTML cell classes with any specific page breaking
+        requirements.
+
+        On input, @a pagebreak contains y-coordinate of page break (i.e. the
+        horizontal line that should not be crossed by words, images etc.)
+        relative to the parent cell on entry and may be modified to request a
+        page break at a position before it if this cell cannot be divided into
+        two pieces (each one on its own page).
+
+        Note that page break must still happen on the current page, i.e. the
+        returned value must be strictly greater than @code *pagebreak -
+        pageHeight @endcode and less or equal to @c *pagebreak for the value of
+        @a pagebreak on input.
 
         @param pagebreak
-            position in pixel of the pagebreak.
-
-        @param known_pagebreaks
-            the list of the previous pagebreaks
-
+            position in pixels of the pagebreak.
         @param pageHeight
-            the height in pixel of the page drawable area
-
-        Usage:
-        @code
-        while (container->AdjustPagebreak(&p, kp, ph)) {}
-        @endcode
+            the height in pixels of the page drawable area
 
+        @return @true if pagebreak was modified, @false otherwise.
     */
-    virtual bool AdjustPagebreak(int* pagebreak,
-                                 const wxArrayInt& known_pagebreaks,
-                                 int pageHeight) const;
+    virtual bool AdjustPagebreak(int* pagebreak, int pageHeight) const;
 
     /**
         Renders the cell.

interface/wx/html/htmprint.h

@@ -38,33 +38,54 @@ public:
     /**
         Returns the height of the HTML text in pixels.
 
-        This is important if area height (see wxHtmlDCRenderer::SetSize) is
-        smaller that total height and thus the page cannot fit into it. In that
-        case you're supposed to call Render() as long as its return value is
-        smaller than GetTotalHeight()'s.
+        If the height of the area used with this renderer (see
+        wxHtmlDCRenderer::SetSize) is smaller that total height, the renderer
+        will produce more than one page of output.
 
         @see GetTotalWidth()
     */
     int GetTotalHeight() const;
 
+    /**
+        Finds the next page break after the specified (vertical) position.
+
+        An example of using this method:
+
+        @code
+        std::vector<int> pages;
+        for ( int pos = 0; pos != wxNOT_FOUND; pos = renderer.FindNextPageBreak(pos) )
+        {
+            pages.push_back(pos);
+        }
+
+        // "pages" vector now contains all page break positions and, in
+        // particular, its size() returns the number of pages
+        @endcode
+
+        @param pos Absolute position of the last page break. For the initial
+            call of this function, it should be 0 and for the subsequent ones
+            it should be the previous return value.
+        @return Position of the next page break or @c wxNOT_FOUND if there are
+            no more of them.
+
+        @since 3.1.2
+    */
+    int FindNextPageBreak(int pos) const;
+
     /**
         Renders HTML text to the DC.
 
+        When using multi-page documents, FindNextPageBreak() can be used to
+        find the values for @a from and @a to, which should be the consecutive
+        page breaks returned by that function.
+
         @param x,y
             position of upper-left corner of printing rectangle (see SetSize()).
-        @param known_pagebreaks
-            @todo docme
         @param from
             y-coordinate of the very first visible cell.
-        @param dont_render
-            if @true then this method only returns y coordinate of the next page
-            and does not output anything.
         @param to
-            y-coordinate of the last visible cell.
-
-        Returned value is y coordinate of first cell than didn't fit onto page.
-        Use this value as from in next call to Render() in order to print
-        multipages document.
+            y-coordinate of the last visible cell or @c INT_MAX to use the full
+            page height.
 
         @note
         The following three methods @b must always be called before any call to
@@ -72,11 +93,8 @@ public:
         - SetDC()
         - SetSize()
         - SetHtmlText()
-
-        @note Render() changes the DC's user scale and does NOT restore it.
     */
-    int Render(int x, int y, wxArrayInt& known_pagebreaks, int from = 0,
-               int dont_render = false, int to = INT_MAX);
+    void Render(int x, int y, int from = 0, int to = INT_MAX);
 
     /**
         Assign DC instance to the renderer.