interface/wx/html/htmprint.h

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