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