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