document wxFont(wxString) ctor

[wxWidgets.git] / interface / wx / html / htmprint.h

diff --git a/interface/wx/html/htmprint.h b/interface/wx/html/htmprint.h
index 7e5cb99a0664a170573c07789e456b41eb6aa972..a7dd53b286b9546a86b4e348ac7d83633597eb32 100644 (file)
--- a/interface/wx/html/htmprint.h
+++ b/interface/wx/html/htmprint.h
@@ -8,15 +8,13 @@
 
 /**
     @class wxHtmlDCRenderer
 
 /**
     @class wxHtmlDCRenderer

-    @headerfile htmprint.h wx/html/htmprint.h

 
 

-    This class can render HTML document into a specified area of a DC. You can use
-    it
-    in your own printing code, although use of wxHtmlEasyPrinting
+    This class can render HTML document into a specified area of a DC.
+    You can use it in your own printing code, although use of wxHtmlEasyPrinting

     or wxHtmlPrintout is strongly recommended.
 
     @library{wxhtml}
     or wxHtmlPrintout is strongly recommended.
 
     @library{wxhtml}

-    @category{FIXME}
+    @category{html}

 */
 class wxHtmlDCRenderer : public wxObject
 {
 */
 class wxHtmlDCRenderer : public wxObject
 {


@@ -27,58 +25,90 @@ public:
     wxHtmlDCRenderer();
 
     /**
     wxHtmlDCRenderer();
 
     /**

-        Returns the height of the HTML text. 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.
+        Returns the width of the HTML text in pixels.
+
+        This can be compared with the width parameter of SetSize() to check if
+        the document being printed fits into the page boundary.
+
+        @see GetTotalHeight()
+
+        @since 2.9.0
+     */
+    int GetTotalWidth() const;
+
+    /**
+        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.
+
+        @see GetTotalWidth()

     */
     */

-    int GetTotalHeight();
+    int GetTotalHeight() const;

 
     /**
         Renders HTML text to the DC.
 
     /**
         Renders HTML text to the DC.

-        
+

         @param x,y
         @param x,y

-            position of upper-left corner of printing rectangle (see SetSize)
+            position of upper-left corner of printing rectangle (see SetSize()).
+        @param known_pagebreaks
+            @todo docme

         @param from
         @param from

-            y-coordinate of the very first visible cell
+            y-coordinate of the very first visible cell.

         @param dont_render
             if @true then this method only returns y coordinate of the next page
         @param dont_render
             if @true then this method only returns y coordinate of the next page

-            and does not output anything
+            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.
+
+        @note
+        The following three methods @b must always be called before any call to
+        Render(), in this order:
+        - SetDC()
+        - SetSize()
+        - SetHtmlText()
+
+        @note Render() changes the DC's user scale and does NOT restore it.

     */
     */

-    int Render(int x, int y, int from = 0, int dont_render = false);
+    int Render(int x, int y, wxArrayInt& known_pagebreaks, int from = 0,
+               int dont_render = false, int to = INT_MAX);

 
     /**
         Assign DC instance to the renderer.
 
     /**
         Assign DC instance to the renderer.

+

         @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer)
         to adjust size of pixel metrics.
         @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer)
         to adjust size of pixel metrics.

-        (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image
-        would be only one
-        inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.)
+        (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300
+        image would be only one inch wide on typical printer. With pixel_scale = 3.0
+        it would be 3 inches.)

     */
     void SetDC(wxDC* dc, double pixel_scale = 1.0);
 
     /**
     */
     void SetDC(wxDC* dc, double pixel_scale = 1.0);
 
     /**

-        Sets fonts. See wxHtmlWindow::SetFonts for
-        detailed description.
-        See also SetSize().
+        Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
+
+        @see SetSize()

     */
     */

-    void SetFonts(const wxString& normal_face,
-                  const wxString& fixed_face,
-                  const int sizes = NULL);
+    void SetFonts(const wxString& normal_face, const wxString& fixed_face,
+                  const int* sizes = NULL);

 
     /**
 
     /**

-        Assign text to the renderer. Render() then draws
-        the text onto DC.
-        
+        Assign text to the renderer. Render() then draws the text onto DC.
+

         @param html
             HTML text. This is not a filename.
         @param basepath
         @param html
             HTML text. This is not a filename.
         @param basepath

-            base directory (html string would be stored there if it was in
-            file). It is used to determine path for loading images, for example.
+            base directory (html string would be stored there if it was in file).
+            It is used to determine path for loading images, for example.

         @param isdir
             @false if basepath is filename, @true if it is directory name
         @param isdir
             @false if basepath is filename, @true if it is directory name

-            (see wxFileSystem for detailed explanation)
+            (see wxFileSystem for detailed explanation).

     */
     void SetHtmlText(const wxString& html,
                      const wxString& basepath = wxEmptyString,
     */
     void SetHtmlText(const wxString& html,
                      const wxString& basepath = wxEmptyString,


@@ -96,33 +126,36 @@ public:
 
 /**
     @class wxHtmlEasyPrinting
 
 /**
     @class wxHtmlEasyPrinting

-    @headerfile htmprint.h wx/html/htmprint.h

 
 

-    This class provides very simple interface to printing
-    architecture. It allows you to print HTML documents using
-    only a few commands.
+    This class provides very simple interface to printing architecture.
+    It allows you to print HTML documents using only a few commands.
+
+    @note
+    Do not create this class on the stack only. You should create an instance
+    on app startup and use this instance for all printing operations.
+    The reason is that this class stores various settings in it.

 
     @library{wxhtml}
 
     @library{wxhtml}

-    @category{html}
+    @category{html,printing}

 */
 class wxHtmlEasyPrinting : public wxObject
 {
 public:
     /**
         Constructor.
 */
 class wxHtmlEasyPrinting : public wxObject
 {
 public:
     /**
         Constructor.

-        
+

         @param name
             Name of the printing object. Used by preview frames and setup dialogs.
         @param parentWindow
             pointer to the window that will own the preview frame and setup dialogs.
         @param name
             Name of the printing object. Used by preview frames and setup dialogs.
         @param parentWindow
             pointer to the window that will own the preview frame and setup dialogs.

-        May be @NULL.
+            May be @NULL.

     */
     wxHtmlEasyPrinting(const wxString& name = "Printing",
                        wxWindow* parentWindow = NULL);
 
     /**
     */
     wxHtmlEasyPrinting(const wxString& name = "Printing",
                        wxWindow* parentWindow = NULL);
 
     /**

-        Returns a pointer to wxPageSetupDialogData instance used by
-        this class. You can set its parameters (via SetXXXX methods).
+        Returns a pointer to wxPageSetupDialogData instance used by this class.
+        You can set its parameters (via SetXXXX methods).

     */
     wxPageSetupDialogData* GetPageSetupData();
 
     */
     wxPageSetupDialogData* GetPageSetupData();
 


@@ -132,8 +165,8 @@ public:
     wxWindow* GetParentWindow() const;
 
     /**
     wxWindow* GetParentWindow() const;
 
     /**

-        Returns pointer to wxPrintData instance used by this class. You can
-        set its parameters (via SetXXXX methods).
+        Returns pointer to wxPrintData instance used by this class.
+        You can set its parameters (via SetXXXX methods).

     */
     wxPrintData* GetPrintData();
 
     */
     wxPrintData* GetPrintData();
 


@@ -144,66 +177,64 @@ public:
 
     /**
         Preview HTML file.
 
     /**
         Preview HTML file.

-        Returns @false in case of error -- call
-        wxPrinter::GetLastError to get detailed
+
+        Returns @false in case of error -- call wxPrinter::GetLastError to get detailed

         information about the kind of the error.
     */
     bool PreviewFile(const wxString& htmlfile);
 
     /**
         Preview HTML text (not file!).
         information about the kind of the error.
     */
     bool PreviewFile(const wxString& htmlfile);
 
     /**
         Preview HTML text (not file!).

-        Returns @false in case of error -- call
-        wxPrinter::GetLastError to get detailed
+
+        Returns @false in case of error -- call wxPrinter::GetLastError to get detailed

         information about the kind of the error.
         information about the kind of the error.

-        
+

         @param htmltext
             HTML text.
         @param basepath
         @param htmltext
             HTML text.
         @param basepath

-            base directory (html string would be stored there if it was in
-            file). It is used to determine path for loading images, for example.
+            base directory (html string would be stored there if it was in file).
+            It is used to determine path for loading images, for example.

     */
     bool PreviewText(const wxString& htmltext,
                      const wxString& basepath = wxEmptyString);
 
     /**
         Print HTML file.
     */
     bool PreviewText(const wxString& htmltext,
                      const wxString& basepath = wxEmptyString);
 
     /**
         Print HTML file.

-        Returns @false in case of error -- call
-        wxPrinter::GetLastError to get detailed
+
+        Returns @false in case of error -- call wxPrinter::GetLastError to get detailed

         information about the kind of the error.
     */
     bool PrintFile(const wxString& htmlfile);
 
     /**
         Print HTML text (not file!).
         information about the kind of the error.
     */
     bool PrintFile(const wxString& htmlfile);
 
     /**
         Print HTML text (not file!).

-        Returns @false in case of error -- call
-        wxPrinter::GetLastError to get detailed
+
+        Returns @false in case of error -- call wxPrinter::GetLastError to get detailed

         information about the kind of the error.
         information about the kind of the error.

-        
+

         @param htmltext
             HTML text.
         @param basepath
         @param htmltext
             HTML text.
         @param basepath

-            base directory (html string would be stored there if it was in
-            file). It is used to determine path for loading images, for example.
+            base directory (html string would be stored there if it was in file).
+            It is used to determine path for loading images, for example.

     */
     bool PrintText(const wxString& htmltext,
                    const wxString& basepath = wxEmptyString);
 
     /**
     */
     bool PrintText(const wxString& htmltext,
                    const wxString& basepath = wxEmptyString);
 
     /**

-        Sets fonts. See wxHtmlWindow::SetFonts for
-        detailed description.
+        Sets fonts. See wxHtmlWindow::SetFonts for detailed description.

     */
     */

-    void SetFonts(const wxString& normal_face,
-                  const wxString& fixed_face,
-                  const int sizes = NULL);
+    void SetFonts(const wxString& normal_face, const wxString& fixed_face,
+                  const int* sizes = NULL);

 
     /**
         Set page footer. The following macros can be used inside it:
 
     /**
         Set page footer. The following macros can be used inside it:

-         @DATE@ is replaced by the current date in default format
-         @PAGENUM@ is replaced by page number
-         @PAGESCNT@ is replaced by total number of pages
-         @TIME@ is replaced by the current time in default format
-         @TITLE@ is replaced with the title of the document
-        
+         @@DATE@ is replaced by the current date in default format
+         @@PAGENUM@ is replaced by page number
+         @@PAGESCNT@ is replaced by total number of pages
+         @@TIME@ is replaced by the current time in default format
+         @@TITLE@ is replaced with the title of the document
+

         @param footer
             HTML text to be used as footer.
         @param pg
         @param footer
             HTML text to be used as footer.
         @param pg


@@ -213,12 +244,12 @@ public:
 
     /**
         Set page header. The following macros can be used inside it:
 
     /**
         Set page header. The following macros can be used inside it:

-         @DATE@ is replaced by the current date in default format
-         @PAGENUM@ is replaced by page number
-         @PAGESCNT@ is replaced by total number of pages
-         @TIME@ is replaced by the current time in default format
-         @TITLE@ is replaced with the title of the document
-        
+        - @@DATE@ is replaced by the current date in default format
+        - @@PAGENUM@ is replaced by page number
+        - @@PAGESCNT@ is replaced by total number of pages
+        - @@TIME@ is replaced by the current time in default format
+        - @@TITLE@ is replaced with the title of the document
+

         @param header
             HTML text to be used as header.
         @param pg
         @param header
             HTML text to be used as header.
         @param pg


@@ -230,18 +261,40 @@ public:
         Sets the parent window for dialogs.
     */
     void SetParentWindow(wxWindow* window);
         Sets the parent window for dialogs.
     */
     void SetParentWindow(wxWindow* window);

+
+private:
+    /**
+        Check whether the document fits into the page area.
+
+        This function is called by the base class OnPreparePrinting()
+        implementation and by default checks whether the document fits into
+        @a pageArea horizontally and warns the user if it does not, giving him
+        the possibility to cancel printing in this case (presumably in order to
+        change some layout options and retry it again).
+
+        You may override it to either suppress this check if truncation of the
+        HTML being printed is acceptable or, on the contrary, add more checks to
+        it, e.g. for the fit in the vertical direction if the document should
+        always appear on a single page.
+
+        @return
+            @true if wxHtmlPrintout should continue or @false to cancel
+            printing.
+
+        @since 2.9.0
+     */
+    virtual bool CheckFit(const wxSize& pageArea, const wxSize& docArea) const;

 };
 
 
 
 /**
     @class wxHtmlPrintout
 };
 
 
 
 /**
     @class wxHtmlPrintout

-    @headerfile htmprint.h wx/html/htmprint.h

 
     This class serves as printout class for HTML documents.
 
     @library{wxhtml}
 
     This class serves as printout class for HTML documents.
 
     @library{wxhtml}

-    @category{html}
+    @category{html,printing}

 */
 class wxHtmlPrintout : public wxPrintout
 {
 */
 class wxHtmlPrintout : public wxPrintout
 {


@@ -252,28 +305,25 @@ public:
     wxHtmlPrintout(const wxString& title = "Printout");
 
     /**
     wxHtmlPrintout(const wxString& title = "Printout");
 
     /**

-        Adds a filter to the static list of filters for wxHtmlPrintout. See
-        wxHtmlFilter for
-        further information.
+        Adds a filter to the static list of filters for wxHtmlPrintout.
+        See wxHtmlFilter for further information.

     */
     static void AddFilter(wxHtmlFilter* filter);
 
     /**
     */
     static void AddFilter(wxHtmlFilter* filter);
 
     /**

-        Sets fonts. See wxHtmlWindow::SetFonts for
-        detailed description.
+        Sets fonts. See wxHtmlWindow::SetFonts for detailed description.

     */
     */

-    void SetFonts(const wxString& normal_face,
-                  const wxString& fixed_face,
-                  const int sizes = NULL);
+    void SetFonts(const wxString& normal_face, const wxString& fixed_face,
+                  const int* sizes = NULL);

 
     /**
         Set page footer. The following macros can be used inside it:
 
     /**
         Set page footer. The following macros can be used inside it:

-         @DATE@ is replaced by the current date in default format
-         @PAGENUM@ is replaced by page number
-         @PAGESCNT@ is replaced by total number of pages
-         @TIME@ is replaced by the current time in default format
-         @TITLE@ is replaced with the title of the document
-        
+        - @@DATE@ is replaced by the current date in default format
+        - @@PAGENUM@ is replaced by page number
+        - @@PAGESCNT@ is replaced by total number of pages
+        - @@TIME@ is replaced by the current time in default format
+        - @@TITLE@ is replaced with the title of the document
+

         @param footer
             HTML text to be used as footer.
         @param pg
         @param footer
             HTML text to be used as footer.
         @param pg


@@ -283,12 +333,12 @@ public:
 
     /**
         Set page header. The following macros can be used inside it:
 
     /**
         Set page header. The following macros can be used inside it:

-         @DATE@ is replaced by the current date in default format
-         @PAGENUM@ is replaced by page number
-         @PAGESCNT@ is replaced by total number of pages
-         @TIME@ is replaced by the current time in default format
-         @TITLE@ is replaced with the title of the document
-        
+        - @@DATE@ is replaced by the current date in default format
+        - @@PAGENUM@ is replaced by page number
+        - @@PAGESCNT@ is replaced by total number of pages
+        - @@TIME@ is replaced by the current time in default format
+        - @@TITLE@ is replaced with the title of the document
+

         @param header
             HTML text to be used as header.
         @param pg
         @param header
             HTML text to be used as header.
         @param pg


@@ -297,30 +347,31 @@ public:
     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 
     /**
     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 
     /**

-        Prepare the class for printing this HTML @b file. The file may be located on
-        any virtual file system or it may be normal file.
+        Prepare the class for printing this HTML @b file.
+        The file may be located on any virtual file system or it may be normal file.

     */
     void SetHtmlFile(const wxString& htmlfile);
 
     /**
         Prepare the class for printing this HTML text.
     */
     void SetHtmlFile(const wxString& htmlfile);
 
     /**
         Prepare the class for printing this HTML text.

-        
+

         @param html
             HTML text. (NOT file!)
         @param basepath
         @param html
             HTML text. (NOT file!)
         @param basepath

-            base directory (html string would be stored there if it was in
-            file). It is used to determine path for loading images, for example.
+            base directory (html string would be stored there if it was in file).
+            It is used to determine path for loading images, for example.

         @param isdir
             @false if basepath is filename, @true if it is directory name
         @param isdir
             @false if basepath is filename, @true if it is directory name

-            (see wxFileSystem for detailed explanation)
+            (see wxFileSystem for detailed explanation).

     */
     void SetHtmlText(const wxString& html,
                      const wxString& basepath = wxEmptyString,
                      bool isdir = true);
 
     /**
     */
     void SetHtmlText(const wxString& html,
                      const wxString& basepath = wxEmptyString,
                      bool isdir = true);
 
     /**

-        Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space
-        between text and header and/or footer
+        Sets margins in millimeters.
+        Defaults to 1 inch for margins and 0.5cm for space between text and header
+        and/or footer.

     */
     void SetMargins(float top = 25.2, float bottom = 25.2,
                     float left = 25.2,
     */
     void SetMargins(float top = 25.2, float bottom = 25.2,
                     float left = 25.2,