interface/html/htmprint.h

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