interface/html/htmprint.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        html/htmprint.h
   3 // Purpose:     documentation for wxHtmlDCRenderer class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxHtmlDCRenderer
  11     @headerfile htmprint.h wx/html/htmprint.h
  12
  13     This class can render HTML document into a specified area of a DC. You can use
  14     it
  15     in your own printing code, although use of wxHtmlEasyPrinting
  16     or wxHtmlPrintout is strongly recommended.
  17
  18     @library{wxhtml}
  19     @category{FIXME}
  20 */
  21 class wxHtmlDCRenderer : public wxObject
  22 {
  23 public:
  24     /**
  25         Constructor.
  26     */
  27     wxHtmlDCRenderer();
  28
  29     /**
  30         Returns the height of the HTML text. This is important if area height (see
  31         wxHtmlDCRenderer::SetSize)
  32         is smaller that total height and thus the page cannot fit into it. In that case
  33         you're supposed to
  34         call Render() as long as its return value is smaller than GetTotalHeight's.
  35     */
  36     int GetTotalHeight();
  37
  38     /**
  39         Renders HTML text to the DC.
  40
  41         @param x,y
  42             position of upper-left corner of printing rectangle (see SetSize)
  43         @param from
  44             y-coordinate of the very first visible cell
  45         @param dont_render
  46             if @true then this method only returns y coordinate of the next page
  47             and does not output anything
  48     */
  49     int Render(int x, int y, int from = 0, int dont_render = false);
  50
  51     /**
  52         Assign DC instance to the renderer.
  53         @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer)
  54         to adjust size of pixel metrics.
  55         (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image
  56         would be only one
  57         inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.)
  58     */
  59     void SetDC(wxDC* dc, double pixel_scale = 1.0);
  60
  61     /**
  62         Sets fonts. See wxHtmlWindow::SetFonts for
  63         detailed description.
  64         See also SetSize().
  65     */
  66     void SetFonts(const wxString& normal_face,
  67                   const wxString& fixed_face,
  68                   const int sizes = NULL);
  69
  70     /**
  71         Assign text to the renderer. Render() then draws
  72         the text onto DC.
  73
  74         @param html
  75             HTML text. This is not a filename.
  76         @param basepath
  77             base directory (html string would be stored there if it was in
  78             file). It is used to determine path for loading images, for example.
  79         @param isdir
  80             @false if basepath is filename, @true if it is directory name
  81             (see wxFileSystem for detailed explanation)
  82     */
  83     void SetHtmlText(const wxString& html,
  84                      const wxString& basepath = wxEmptyString,
  85                      bool isdir = true);
  86
  87     /**
  88         Set size of output rectangle, in pixels. Note that you @b can't change
  89         width of the rectangle between calls to wxHtmlDCRenderer::Render!
  90         (You can freely change height.)
  91     */
  92     void SetSize(int width, int height);
  93 };
  94
  95
  96 /**
  97     @class wxHtmlEasyPrinting
  98     @headerfile htmprint.h wx/html/htmprint.h
  99
 100     This class provides very simple interface to printing
 101     architecture. It allows you to print HTML documents using
 102     only a few commands.
 103
 104     @library{wxhtml}
 105     @category{html}
 106 */
 107 class wxHtmlEasyPrinting : public wxObject
 108 {
 109 public:
 110     /**
 111         Constructor.
 112
 113         @param name
 114             Name of the printing object. Used by preview frames and setup dialogs.
 115         @param parentWindow
 116             pointer to the window that will own the preview frame and setup dialogs.
 117         May be @NULL.
 118     */
 119     wxHtmlEasyPrinting(const wxString& name = "Printing",
 120                        wxWindow* parentWindow = NULL);
 121
 122     /**
 123         Returns a pointer to wxPageSetupDialogData instance used by
 124         this class. You can set its parameters (via SetXXXX methods).
 125     */
 126     wxPageSetupDialogData* GetPageSetupData();
 127
 128     /**
 129         Gets the parent window for dialogs.
 130     */
 131     wxWindow* GetParentWindow() const;
 132
 133     /**
 134         Returns pointer to wxPrintData instance used by this class. You can
 135         set its parameters (via SetXXXX methods).
 136     */
 137     wxPrintData* GetPrintData();
 138
 139     /**
 140         Display page setup dialog and allows the user to modify settings.
 141     */
 142     void PageSetup();
 143
 144     /**
 145         Preview HTML file.
 146         Returns @false in case of error -- call
 147         wxPrinter::GetLastError to get detailed
 148         information about the kind of the error.
 149     */
 150     bool PreviewFile(const wxString& htmlfile);
 151
 152     /**
 153         Preview HTML text (not file!).
 154         Returns @false in case of error -- call
 155         wxPrinter::GetLastError to get detailed
 156         information about the kind of the error.
 157
 158         @param htmltext
 159             HTML text.
 160         @param basepath
 161             base directory (html string would be stored there if it was in
 162             file). It is used to determine path for loading images, for example.
 163     */
 164     bool PreviewText(const wxString& htmltext,
 165                      const wxString& basepath = wxEmptyString);
 166
 167     /**
 168         Print HTML file.
 169         Returns @false in case of error -- call
 170         wxPrinter::GetLastError to get detailed
 171         information about the kind of the error.
 172     */
 173     bool PrintFile(const wxString& htmlfile);
 174
 175     /**
 176         Print HTML text (not file!).
 177         Returns @false in case of error -- call
 178         wxPrinter::GetLastError to get detailed
 179         information about the kind of the error.
 180
 181         @param htmltext
 182             HTML text.
 183         @param basepath
 184             base directory (html string would be stored there if it was in
 185             file). It is used to determine path for loading images, for example.
 186     */
 187     bool PrintText(const wxString& htmltext,
 188                    const wxString& basepath = wxEmptyString);
 189
 190     /**
 191         Sets fonts. See wxHtmlWindow::SetFonts for
 192         detailed description.
 193     */
 194     void SetFonts(const wxString& normal_face,
 195                   const wxString& fixed_face,
 196                   const int sizes = NULL);
 197
 198     /**
 199         Set page footer. The following macros can be used inside it:
 200          @DATE@ is replaced by the current date in default format
 201          @PAGENUM@ is replaced by page number
 202          @PAGESCNT@ is replaced by total number of pages
 203          @TIME@ is replaced by the current time in default format
 204          @TITLE@ is replaced with the title of the document
 205
 206         @param footer
 207             HTML text to be used as footer.
 208         @param pg
 209             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 210     */
 211     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 212
 213     /**
 214         Set page header. The following macros can be used inside it:
 215          @DATE@ is replaced by the current date in default format
 216          @PAGENUM@ is replaced by page number
 217          @PAGESCNT@ is replaced by total number of pages
 218          @TIME@ is replaced by the current time in default format
 219          @TITLE@ is replaced with the title of the document
 220
 221         @param header
 222             HTML text to be used as header.
 223         @param pg
 224             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 225     */
 226     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 227
 228     /**
 229         Sets the parent window for dialogs.
 230     */
 231     void SetParentWindow(wxWindow* window);
 232 };
 233
 234
 235 /**
 236     @class wxHtmlPrintout
 237     @headerfile htmprint.h wx/html/htmprint.h
 238
 239     This class serves as printout class for HTML documents.
 240
 241     @library{wxhtml}
 242     @category{html}
 243 */
 244 class wxHtmlPrintout : public wxPrintout
 245 {
 246 public:
 247     /**
 248         Constructor.
 249     */
 250     wxHtmlPrintout(const wxString& title = "Printout");
 251
 252     /**
 253         Adds a filter to the static list of filters for wxHtmlPrintout. See
 254         wxHtmlFilter for
 255         further information.
 256     */
 257     static void AddFilter(wxHtmlFilter* filter);
 258
 259     /**
 260         Sets fonts. See wxHtmlWindow::SetFonts for
 261         detailed description.
 262     */
 263     void SetFonts(const wxString& normal_face,
 264                   const wxString& fixed_face,
 265                   const int sizes = NULL);
 266
 267     /**
 268         Set page footer. The following macros can be used inside it:
 269          @DATE@ is replaced by the current date in default format
 270          @PAGENUM@ is replaced by page number
 271          @PAGESCNT@ is replaced by total number of pages
 272          @TIME@ is replaced by the current time in default format
 273          @TITLE@ is replaced with the title of the document
 274
 275         @param footer
 276             HTML text to be used as footer.
 277         @param pg
 278             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 279     */
 280     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 281
 282     /**
 283         Set page header. The following macros can be used inside it:
 284          @DATE@ is replaced by the current date in default format
 285          @PAGENUM@ is replaced by page number
 286          @PAGESCNT@ is replaced by total number of pages
 287          @TIME@ is replaced by the current time in default format
 288          @TITLE@ is replaced with the title of the document
 289
 290         @param header
 291             HTML text to be used as header.
 292         @param pg
 293             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 294     */
 295     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 296
 297     /**
 298         Prepare the class for printing this HTML @b file. The file may be located on
 299         any virtual file system or it may be normal file.
 300     */
 301     void SetHtmlFile(const wxString& htmlfile);
 302
 303     /**
 304         Prepare the class for printing this HTML text.
 305
 306         @param html
 307             HTML text. (NOT file!)
 308         @param basepath
 309             base directory (html string would be stored there if it was in
 310             file). It is used to determine path for loading images, for example.
 311         @param isdir
 312             @false if basepath is filename, @true if it is directory name
 313             (see wxFileSystem for detailed explanation)
 314     */
 315     void SetHtmlText(const wxString& html,
 316                      const wxString& basepath = wxEmptyString,
 317                      bool isdir = true);
 318
 319     /**
 320         Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space
 321         between text and header and/or footer
 322     */
 323     void SetMargins(float top = 25.2, float bottom = 25.2,
 324                     float left = 25.2,
 325                     float right = 25.2,
 326                     float spaces = 5);
 327 };