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 the current name being used for preview frames and setup
 195         dialogs.
 196
 197         @since 2.8.11 / 2.9.1
 198     */
 199     const wxString& GetName() const;
 200
 201     /**
 202         Returns a pointer to wxPageSetupDialogData instance used by this class.
 203         You can set its parameters (via SetXXXX methods).
 204     */
 205     wxPageSetupDialogData* GetPageSetupData();
 206
 207     /**
 208         Gets the parent window for dialogs.
 209     */
 210     wxWindow* GetParentWindow() const;
 211
 212     /**
 213         Returns pointer to wxPrintData instance used by this class.
 214         You can set its parameters (via SetXXXX methods).
 215     */
 216     wxPrintData* GetPrintData();
 217
 218     /**
 219         Display page setup dialog and allows the user to modify settings.
 220     */
 221     void PageSetup();
 222
 223     /**
 224         Preview HTML 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     bool PreviewFile(const wxString& htmlfile);
 230
 231     /**
 232         Preview HTML text (not file!).
 233
 234         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 235         information about the kind of the error.
 236
 237         @param htmltext
 238             HTML text.
 239         @param basepath
 240             base directory (html string would be stored there if it was in file).
 241             It is used to determine path for loading images, for example.
 242     */
 243     bool PreviewText(const wxString& htmltext,
 244                      const wxString& basepath = wxEmptyString);
 245
 246     /**
 247         Print HTML 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     bool PrintFile(const wxString& htmlfile);
 253
 254     /**
 255         Print HTML text (not file!).
 256
 257         Returns @false in case of error -- call wxPrinter::GetLastError to get detailed
 258         information about the kind of the error.
 259
 260         @param htmltext
 261             HTML text.
 262         @param basepath
 263             base directory (html string would be stored there if it was in file).
 264             It is used to determine path for loading images, for example.
 265     */
 266     bool PrintText(const wxString& htmltext,
 267                    const wxString& basepath = wxEmptyString);
 268
 269     /**
 270         Sets fonts. See wxHtmlDCRenderer::SetFonts for detailed description.
 271     */
 272     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 273                   const int* sizes = NULL);
 274
 275     /**
 276         Sets the name used for preview frames and setup dialogs.
 277
 278         @since 2.8.11 / 2.9.1
 279     */
 280     void SetName(const wxString& name);
 281
 282     /**
 283         Sets default font sizes and/or default font size.
 284         See wxHtmlDCRenderer::SetStandardFonts for detailed description.
 285         @see SetFonts()
 286     */
 287     void SetStandardFonts(int size = -1,
 288                           const wxString& normal_face = wxEmptyString,
 289                           const wxString& fixed_face = wxEmptyString);
 290
 291     /**
 292         Set page footer. 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 footer
 300             HTML text to be used as footer.
 301         @param pg
 302             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 303     */
 304     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 305
 306     /**
 307         Set page header. The following macros can be used inside it:
 308         - @@DATE@ is replaced by the current date in default format
 309         - @@PAGENUM@ is replaced by page number
 310         - @@PAGESCNT@ is replaced by total number of pages
 311         - @@TIME@ is replaced by the current time in default format
 312         - @@TITLE@ is replaced with the title of the document
 313
 314         @param header
 315             HTML text to be used as header.
 316         @param pg
 317             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 318     */
 319     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 320
 321     /**
 322         Sets the parent window for dialogs.
 323     */
 324     void SetParentWindow(wxWindow* window);
 325
 326 private:
 327     /**
 328         Check whether the document fits into the page area.
 329
 330         This function is called by the base class OnPreparePrinting()
 331         implementation and by default checks whether the document fits into
 332         @a pageArea horizontally and warns the user if it does not, giving him
 333         the possibility to cancel printing in this case (presumably in order to
 334         change some layout options and retry it again).
 335
 336         You may override it to either suppress this check if truncation of the
 337         HTML being printed is acceptable or, on the contrary, add more checks to
 338         it, e.g. for the fit in the vertical direction if the document should
 339         always appear on a single page.
 340
 341         @return
 342             @true if wxHtmlPrintout should continue or @false to cancel
 343             printing.
 344
 345         @since 2.9.0
 346      */
 347     virtual bool CheckFit(const wxSize& pageArea, const wxSize& docArea) const;
 348 };
 349
 350
 351
 352 /**
 353     @class wxHtmlPrintout
 354
 355     This class serves as printout class for HTML documents.
 356
 357     @library{wxhtml}
 358     @category{html,printing}
 359 */
 360 class wxHtmlPrintout : public wxPrintout
 361 {
 362 public:
 363     /**
 364         Constructor.
 365     */
 366     wxHtmlPrintout(const wxString& title = "Printout");
 367
 368     /**
 369         Adds a filter to the static list of filters for wxHtmlPrintout.
 370         See wxHtmlFilter for further information.
 371     */
 372     static void AddFilter(wxHtmlFilter* filter);
 373
 374     /**
 375         This function sets font sizes and faces. See wxHtmlWindow::SetFonts
 376         for detailed description.
 377     */
 378     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 379                   const int* sizes = NULL);
 380
 381     /**
 382         Set page footer. 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 footer
 390             HTML text to be used as footer.
 391         @param pg
 392             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 393     */
 394     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 395
 396     /**
 397         Set page header. The following macros can be used inside it:
 398         - @@DATE@ is replaced by the current date in default format
 399         - @@PAGENUM@ is replaced by page number
 400         - @@PAGESCNT@ is replaced by total number of pages
 401         - @@TIME@ is replaced by the current time in default format
 402         - @@TITLE@ is replaced with the title of the document
 403
 404         @param header
 405             HTML text to be used as header.
 406         @param pg
 407             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 408     */
 409     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 410
 411     /**
 412         Prepare the class for printing this HTML @b file.
 413         The file may be located on any virtual file system or it may be normal file.
 414     */
 415     void SetHtmlFile(const wxString& htmlfile);
 416
 417     /**
 418         Prepare the class for printing this HTML text.
 419
 420         @param html
 421             HTML text. (NOT file!)
 422         @param basepath
 423             base directory (html string would be stored there if it was in file).
 424             It is used to determine path for loading images, for example.
 425         @param isdir
 426             @false if basepath is filename, @true if it is directory name
 427             (see wxFileSystem for detailed explanation).
 428     */
 429     void SetHtmlText(const wxString& html,
 430                      const wxString& basepath = wxEmptyString,
 431                      bool isdir = true);
 432
 433     /**
 434         Sets margins in millimeters.
 435         Defaults to 1 inch for margins and 0.5cm for space between text and header
 436         and/or footer.
 437     */
 438     void SetMargins(float top = 25.2, float bottom = 25.2,
 439                     float left = 25.2,
 440                     float right = 25.2,
 441                     float spaces = 5);
 442 };
 443