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