interface/wx/html/htmprint.h

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