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, wxArrayInt& known_pagebreaks, int from = 0,
  58                int dont_render = 0, int to = INT_MAX);
  59
  60     /**
  61         Assign DC instance to the renderer.
  62
  63         @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer)
  64         to adjust size of pixel metrics.
  65         (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300
  66         image would be only one inch wide on typical printer. With pixel_scale = 3.0
  67         it would be 3 inches.)
  68     */
  69     void SetDC(wxDC* dc, double pixel_scale = 1.0);
  70
  71     /**
  72         Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
  73
  74         @see SetSize()
  75     */
  76     void SetFonts(const wxString& normal_face, 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, const wxString& fixed_face,
 206                   const int* sizes = NULL);
 207
 208     /**
 209         Set page footer. The following macros can be used inside it:
 210          @@DATE@ is replaced by the current date in default format
 211          @@PAGENUM@ is replaced by page number
 212          @@PAGESCNT@ is replaced by total number of pages
 213          @@TIME@ is replaced by the current time in default format
 214          @@TITLE@ is replaced with the title of the document
 215
 216         @param footer
 217             HTML text to be used as footer.
 218         @param pg
 219             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 220     */
 221     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 222
 223     /**
 224         Set page header. The following macros can be used inside it:
 225         - @@DATE@ is replaced by the current date in default format
 226         - @@PAGENUM@ is replaced by page number
 227         - @@PAGESCNT@ is replaced by total number of pages
 228         - @@TIME@ is replaced by the current time in default format
 229         - @@TITLE@ is replaced with the title of the document
 230
 231         @param header
 232             HTML text to be used as header.
 233         @param pg
 234             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 235     */
 236     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 237
 238     /**
 239         Sets the parent window for dialogs.
 240     */
 241     void SetParentWindow(wxWindow* window);
 242 };
 243
 244
 245
 246 /**
 247     @class wxHtmlPrintout
 248
 249     This class serves as printout class for HTML documents.
 250
 251     @library{wxhtml}
 252     @category{html,printing}
 253 */
 254 class wxHtmlPrintout : public wxPrintout
 255 {
 256 public:
 257     /**
 258         Constructor.
 259     */
 260     wxHtmlPrintout(const wxString& title = "Printout");
 261
 262     /**
 263         Adds a filter to the static list of filters for wxHtmlPrintout.
 264         See wxHtmlFilter for further information.
 265     */
 266     static void AddFilter(wxHtmlFilter* filter);
 267
 268     /**
 269         Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
 270     */
 271     void SetFonts(const wxString& normal_face, const wxString& fixed_face,
 272                   const int* sizes = NULL);
 273
 274     /**
 275         Set page footer. The following macros can be used inside it:
 276         - @@DATE@ is replaced by the current date in default format
 277         - @@PAGENUM@ is replaced by page number
 278         - @@PAGESCNT@ is replaced by total number of pages
 279         - @@TIME@ is replaced by the current time in default format
 280         - @@TITLE@ is replaced with the title of the document
 281
 282         @param footer
 283             HTML text to be used as footer.
 284         @param pg
 285             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 286     */
 287     void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);
 288
 289     /**
 290         Set page header. The following macros can be used inside it:
 291         - @@DATE@ is replaced by the current date in default format
 292         - @@PAGENUM@ is replaced by page number
 293         - @@PAGESCNT@ is replaced by total number of pages
 294         - @@TIME@ is replaced by the current time in default format
 295         - @@TITLE@ is replaced with the title of the document
 296
 297         @param header
 298             HTML text to be used as header.
 299         @param pg
 300             one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
 301     */
 302     void SetHeader(const wxString& header, int pg = wxPAGE_ALL);
 303
 304     /**
 305         Prepare the class for printing this HTML @b file.
 306         The file may be located on any virtual file system or it may be normal file.
 307     */
 308     void SetHtmlFile(const wxString& htmlfile);
 309
 310     /**
 311         Prepare the class for printing this HTML text.
 312
 313         @param html
 314             HTML text. (NOT file!)
 315         @param basepath
 316             base directory (html string would be stored there if it was in file).
 317             It is used to determine path for loading images, for example.
 318         @param isdir
 319             @false if basepath is filename, @true if it is directory name
 320             (see wxFileSystem for detailed explanation).
 321     */
 322     void SetHtmlText(const wxString& html,
 323                      const wxString& basepath = wxEmptyString,
 324                      bool isdir = true);
 325
 326     /**
 327         Sets margins in millimeters.
 328         Defaults to 1 inch for margins and 0.5cm for space between text and header
 329         and/or footer.
 330     */
 331     void SetMargins(float top = 25.2, float bottom = 25.2,
 332                     float left = 25.2,
 333                     float right = 25.2,
 334                     float spaces = 5);
 335 };
 336