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         This function sets font sizes and faces.
  95
  96         @param normal_face
  97             This is face name for normal (i.e. non-fixed) font.
  98             It can be either empty string (then the default face is chosen) or
  99             platform-specific face name. Examples are "helvetica" under Unix or
 100             "Times New Roman" under Windows.
 101         @param fixed_face
 102             The same thing for fixed face ( \<TT\>..\</TT\> )
 103         @param sizes
 104             This is an array of 7 items of int type.
 105             The values represent size of font with HTML size from -2 to +4
 106             ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ).
 107             Default sizes are used if sizes is @NULL.
 108
 109         Default font sizes are defined by constants wxHTML_FONT_SIZE_1,
 110         wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7.
 111         Note that they differ among platforms. Default face names are empty strings.
 112
 113         @see SetSize()
 114     */
 115     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 116                   const int* sizes = NULL);
 117
 118     /**
 119         Sets font sizes to be relative to the given size or the system
 120         default size; use either specified or default font
 121
 122         @param size
 123             Point size of the default HTML text
 124         @param normal_face
 125             This is face name for normal (i.e. non-fixed) font. It can be
 126             either empty string (then the default face is chosen) or
 127             platform-specific face name. Examples are "helvetica" under
 128             Unix or "Times New Roman" under Windows.
 129         @param fixed_face
 130             The same thing for fixed face ( \<TT\>..\</TT\> )
 131
 132         @see SetSize()
 133     */
 134     void SetStandardFonts(int size = -1,
 135                           const wxString& normal_face = wxEmptyString,
 136                           const wxString& fixed_face = wxEmptyString);
 137
 138     /**
 139         Assign text to the renderer. Render() then draws the text onto DC.
 140
 141         @param html
 142             HTML text. This is not a filename.
 143         @param basepath
 144             base directory (html string would be stored there if it was in file).
 145             It is used to determine path for loading images, for example.
 146         @param isdir
 147             @false if basepath is filename, @true if it is directory name
 148             (see wxFileSystem for detailed explanation).
 149     */
 150     void SetHtmlText(const wxString& html,
 151                      const wxString& basepath = wxEmptyString,
 152                      bool isdir = true);
 153
 154     /**
 155         Set size of output rectangle, in pixels. Note that you @b can't change
 156         width of the rectangle between calls to Render() !
 157         (You can freely change height.)
 158     */
 159     void SetSize(int width, int height);
 160 };
 161
 162
 163
 164 /**
 165     @class wxHtmlEasyPrinting
 166
 167     This class provides very simple interface to printing architecture.
 168     It allows you to print HTML documents using only a few commands.
 169
 170     @note
 171     Do not create this class on the stack only. You should create an instance
 172     on app startup and use this instance for all printing operations.
 173     The reason is that this class stores various settings in it.
 174
 175     @library{wxhtml}
 176     @category{html,printing}
 177 */
 178 class wxHtmlEasyPrinting : public wxObject
 179 {
 180 public:
 181     /**
 182         Constructor.
 183
 184         @param name
 185             Name of the printing object. Used by preview frames and setup dialogs.
 186         @param parentWindow
 187             pointer to the window that will own the preview frame and setup dialogs.
 188             May be @NULL.
 189     */
 190     wxHtmlEasyPrinting(const wxString& name = "Printing",
 191                        wxWindow* parentWindow = NULL);
 192
 193     /**
 194         Returns a pointer to wxPageSetupDialogData instance used by this class.
 195         You can set its parameters (via SetXXXX methods).
 196     */
 197     wxPageSetupDialogData* GetPageSetupData();
 198
 199     /**
 200         Gets the parent window for dialogs.
 201     */
 202     wxWindow* GetParentWindow() const;
 203
 204     /**
 205         Returns pointer to wxPrintData instance used by this class.
 206         You can set its parameters (via SetXXXX methods).
 207     */
 208     wxPrintData* GetPrintData();
 209
 210     /**
 211         Display page setup dialog and allows the user to modify settings.
 212     */
 213     void PageSetup();
 214
 215     /**
 216         Preview HTML file.
 217
 218         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 219         information about the kind of the error.
 220     */
 221     bool PreviewFile(const wxString& htmlfile);
 222
 223     /**
 224         Preview HTML text (not file!).
 225
 226         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 227         information about the kind of the error.
 228
 229         @param htmltext
 230             HTML text.
 231         @param basepath
 232             base directory (html string would be stored there if it was in file).
 233             It is used to determine path for loading images, for example.
 234     */
 235     bool PreviewText(const wxString& htmltext,
 236                      const wxString& basepath = wxEmptyString);
 237
 238     /**
 239         Print HTML file.
 240
 241         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 242         information about the kind of the error.
 243     */
 244     bool PrintFile(const wxString& htmlfile);
 245
 246     /**
 247         Print HTML text (not file!).
 248
 249         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 250         information about the kind of the error.
 251
 252         @param htmltext
 253             HTML text.
 254         @param basepath
 255             base directory (html string would be stored there if it was in file).
 256             It is used to determine path for loading images, for example.
 257     */
 258     bool PrintText(const wxString& htmltext,
 259                    const wxString& basepath = wxEmptyString);
 260
 261     /**
 262         Sets fonts. See wxHtmlDCRenderer::SetFonts for detailed description.
 263     */
 264     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 265                   const int* sizes = NULL);
 266
 267     /**
 268         Sets default font sizes and/or default font size.
 269         See wxHtmlDCRenderer::SetStandardFonts for detailed description.
 270         @see SetFonts()
 271     */
 272     void SetStandardFonts(int size = -1,
 273                           const wxString& normal_face = wxEmptyString,
 274                           const wxString& fixed_face = wxEmptyString);
 275
 276     /**
 277         Set page footer. The following macros can be used inside it:
 278          @@DATE@ is replaced by the current date in default format
 279          @@PAGENUM@ is replaced by page number
 280          @@PAGESCNT@ is replaced by total number of pages
 281          @@TIME@ is replaced by the current time in default format
 282          @@TITLE@ is replaced with the title of the document
 283
 284         @param footer
 285             HTML text to be used as footer.
 286         @param pg
 287             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 288     */
 289     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 290
 291     /**
 292         Set page header. The following macros can be used inside it:
 293         - @@DATE@ is replaced by the current date in default format
 294         - @@PAGENUM@ is replaced by page number
 295         - @@PAGESCNT@ is replaced by total number of pages
 296         - @@TIME@ is replaced by the current time in default format
 297         - @@TITLE@ is replaced with the title of the document
 298
 299         @param header
 300             HTML text to be used as header.
 301         @param pg
 302             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 303     */
 304     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 305
 306     /**
 307         Sets the parent window for dialogs.
 308     */
 309     void SetParentWindow(wxWindow* window);
 310
 311 private:
 312     /**
 313         Check whether the document fits into the page area.
 314
 315         This function is called by the base class OnPreparePrinting()
 316         implementation and by default checks whether the document fits into
 317         @a pageArea horizontally and warns the user if it does not, giving him
 318         the possibility to cancel printing in this case (presumably in order to
 319         change some layout options and retry it again).
 320
 321         You may override it to either suppress this check if truncation of the
 322         HTML being printed is acceptable or, on the contrary, add more checks to
 323         it, e.g. for the fit in the vertical direction if the document should
 324         always appear on a single page.
 325
 326         @return
 327             @true if wxHtmlPrintout should continue or @false to cancel
 328             printing.
 329
 330         @since 2.9.0
 331      */
 332     virtual bool CheckFit(const wxSize& pageArea, const wxSize& docArea) const;
 333 };
 334
 335
 336
 337 /**
 338     @class wxHtmlPrintout
 339
 340     This class serves as printout class for HTML documents.
 341
 342     @library{wxhtml}
 343     @category{html,printing}
 344 */
 345 class wxHtmlPrintout : public wxPrintout
 346 {
 347 public:
 348     /**
 349         Constructor.
 350     */
 351     wxHtmlPrintout(const wxString& title = "Printout");
 352
 353     /**
 354         Adds a filter to the static list of filters for wxHtmlPrintout.
 355         See wxHtmlFilter for further information.
 356     */
 357     static void AddFilter(wxHtmlFilter* filter);
 358
 359     /**
 360         This function sets font sizes and faces. See wxHtmlWindow::SetFonts
 361         for detailed description.
 362     */
 363     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 364                   const int* sizes = NULL);
 365
 366     /**
 367         Set page footer. The following macros can be used inside it:
 368         - @@DATE@ is replaced by the current date in default format
 369         - @@PAGENUM@ is replaced by page number
 370         - @@PAGESCNT@ is replaced by total number of pages
 371         - @@TIME@ is replaced by the current time in default format
 372         - @@TITLE@ is replaced with the title of the document
 373
 374         @param footer
 375             HTML text to be used as footer.
 376         @param pg
 377             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 378     */
 379     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 380
 381     /**
 382         Set page header. The following macros can be used inside it:
 383         - @@DATE@ is replaced by the current date in default format
 384         - @@PAGENUM@ is replaced by page number
 385         - @@PAGESCNT@ is replaced by total number of pages
 386         - @@TIME@ is replaced by the current time in default format
 387         - @@TITLE@ is replaced with the title of the document
 388
 389         @param header
 390             HTML text to be used as header.
 391         @param pg
 392             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 393     */
 394     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 395
 396     /**
 397         Prepare the class for printing this HTML @b file.
 398         The file may be located on any virtual file system or it may be normal file.
 399     */
 400     void SetHtmlFile(const wxString& htmlfile);
 401
 402     /**
 403         Prepare the class for printing this HTML text.
 404
 405         @param html
 406             HTML text. (NOT file!)
 407         @param basepath
 408             base directory (html string would be stored there if it was in file).
 409             It is used to determine path for loading images, for example.
 410         @param isdir
 411             @false if basepath is filename, @true if it is directory name
 412             (see wxFileSystem for detailed explanation).
 413     */
 414     void SetHtmlText(const wxString& html,
 415                      const wxString& basepath = wxEmptyString,
 416                      bool isdir = true);
 417
 418     /**
 419         Sets margins in millimeters.
 420         Defaults to 1 inch for margins and 0.5cm for space between text and header
 421         and/or footer.
 422     */
 423     void SetMargins(float top = 25.2, float bottom = 25.2,
 424                     float left = 25.2,
 425                     float right = 25.2,
 426                     float spaces = 5);
 427 };
 428