1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: html/htmprint.h 3 // Purpose: interface of wxHtmlDCRenderer 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 /** 9 @class wxHtmlDCRenderer 10 11 This class can render HTML document into a specified area of a DC. 12 You can use it in your own printing code, although use of wxHtmlEasyPrinting 13 or wxHtmlPrintout is strongly recommended. 14 15 @library{wxhtml} 16 @category{html} 17 */ 18 class wxHtmlDCRenderer : public wxObject 19 { 20 public: 21 /** 22 Constructor. 23 */ 24 wxHtmlDCRenderer(); 25 26 /** 27 Returns the width of the HTML text in pixels. 28 29 This can be compared with the width parameter of SetSize() to check if 30 the document being printed fits into the page boundary. 31 32 @see GetTotalHeight() 33 34 @since 2.9.0 35 */ 36 int GetTotalWidth() const; 37 38 /** 39 Returns the height of the HTML text in pixels. 40 41 This is important if area height (see wxHtmlDCRenderer::SetSize) is 42 smaller that total height and thus the page cannot fit into it. In that 43 case you're supposed to call Render() as long as its return value is 44 smaller than GetTotalHeight()'s. 45 46 @see GetTotalWidth() 47 */ 48 int GetTotalHeight() const; 49 50 /** 51 Renders HTML text to the DC. 52 53 @param x,y 54 position of upper-left corner of printing rectangle (see SetSize()). 55 @param known_pagebreaks 56 @todo docme 57 @param from 58 y-coordinate of the very first visible cell. 59 @param dont_render 60 if @true then this method only returns y coordinate of the next page 61 and does not output anything. 62 @param to 63 y-coordinate of the last visible cell. 64 65 Returned value is y coordinate of first cell than didn't fit onto page. 66 Use this value as from in next call to Render() in order to print 67 multipages document. 68 69 @note 70 The following three methods @b must always be called before any call to 71 Render(), in this order: 72 - SetDC() 73 - SetSize() 74 - SetHtmlText() 75 76 @note Render() changes the DC's user scale and does NOT restore it. 77 */ 78 int Render(int x, int y, wxArrayInt& known_pagebreaks, int from = 0, 79 int dont_render = false, int to = INT_MAX); 80 81 /** 82 Assign DC instance to the renderer. 83 84 @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) 85 to adjust size of pixel metrics. 86 (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 87 image would be only one inch wide on typical printer. With pixel_scale = 3.0 88 it would be 3 inches.) 89 */ 90 void SetDC(wxDC* dc, double pixel_scale = 1.0); 91 92 /** 93 This function sets font sizes and faces. 94 95 @param normal_face 96 This is face name for normal (i.e. non-fixed) font. 97 It can be either empty string (then the default face is chosen) or 98 platform-specific face name. Examples are "helvetica" under Unix or 99 "Times New Roman" under Windows. 100 @param fixed_face 101 The same thing for fixed face ( \<TT\>..\</TT\> ) 102 @param sizes 103 This is an array of 7 items of int type. 104 The values represent size of font with HTML size from -2 to +4 105 ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ). 106 Default sizes are used if sizes is @NULL. 107 108 Default font sizes are defined by constants wxHTML_FONT_SIZE_1, 109 wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7. 110 Note that they differ among platforms. Default face names are empty strings. 111 112 @see SetSize() 113 */ 114 void SetFonts(const wxString& normal_face, const wxString& fixed_face, 115 const int* sizes = NULL); 116 117 /** 118 Sets font sizes to be relative to the given size or the system 119 default size; use either specified or default font 120 121 @param size 122 Point size of the default HTML text 123 @param normal_face 124 This is face name for normal (i.e. non-fixed) font. It can be 125 either empty string (then the default face is chosen) or 126 platform-specific face name. Examples are "helvetica" under 127 Unix or "Times New Roman" under Windows. 128 @param fixed_face 129 The same thing for fixed face ( \<TT\>..\</TT\> ) 130 131 @see SetSize() 132 */ 133 void SetStandardFonts(int size = -1, 134 const wxString& normal_face = wxEmptyString, 135 const wxString& fixed_face = wxEmptyString); 136 137 /** 138 Assign text to the renderer. Render() then draws the text onto DC. 139 140 @param html 141 HTML text. This is not a filename. 142 @param basepath 143 base directory (html string would be stored there if it was in file). 144 It is used to determine path for loading images, for example. 145 @param isdir 146 @false if basepath is filename, @true if it is directory name 147 (see wxFileSystem for detailed explanation). 148 */ 149 void SetHtmlText(const wxString& html, 150 const wxString& basepath = wxEmptyString, 151 bool isdir = true); 152 153 /** 154 Set size of output rectangle, in pixels. Note that you @b can't change 155 width of the rectangle between calls to Render() ! 156 (You can freely change height.) 157 */ 158 void SetSize(int width, int height); 159 }; 160 161 162 163 /** 164 @class wxHtmlEasyPrinting 165 166 This class provides very simple interface to printing architecture. 167 It allows you to print HTML documents using only a few commands. 168 169 @note 170 Do not create this class on the stack only. You should create an instance 171 on app startup and use this instance for all printing operations. 172 The reason is that this class stores various settings in it. 173 174 @library{wxhtml} 175 @category{html,printing} 176 */ 177 class wxHtmlEasyPrinting : public wxObject 178 { 179 public: 180 /** 181 Constructor. 182 183 @param name 184 Name of the printing object. Used by preview frames and setup dialogs. 185 @param parentWindow 186 pointer to the window that will own the preview frame and setup dialogs. 187 May be @NULL. 188 */ 189 wxHtmlEasyPrinting(const wxString& name = "Printing", 190 wxWindow* parentWindow = NULL); 191 192 /** 193 Returns the current name being used for preview frames and setup 194 dialogs. 195 196 @since 2.8.11 / 2.9.1 197 */ 198 const wxString& GetName() const; 199 200 /** 201 Returns a pointer to wxPageSetupDialogData instance used by this class. 202 You can set its parameters (via SetXXXX methods). 203 */ 204 wxPageSetupDialogData* GetPageSetupData(); 205 206 /** 207 Gets the parent window for dialogs. 208 */ 209 wxWindow* GetParentWindow() const; 210 211 /** 212 Returns pointer to wxPrintData instance used by this class. 213 You can set its parameters (via SetXXXX methods). 214 */ 215 wxPrintData* GetPrintData(); 216 217 /** 218 Display page setup dialog and allows the user to modify settings. 219 */ 220 void PageSetup(); 221 222 /** 223 Preview HTML file. 224 225 Returns @false in case of error -- call wxPrinter::GetLastError to get detailed 226 information about the kind of the error. 227 */ 228 bool PreviewFile(const wxString& htmlfile); 229 230 /** 231 Preview HTML text (not file!). 232 233 Returns @false in case of error -- call wxPrinter::GetLastError to get detailed 234 information about the kind of the error. 235 236 @param htmltext 237 HTML text. 238 @param basepath 239 base directory (html string would be stored there if it was in file). 240 It is used to determine path for loading images, for example. 241 */ 242 bool PreviewText(const wxString& htmltext, 243 const wxString& basepath = wxEmptyString); 244 245 /** 246 Print HTML file. 247 248 Returns @false in case of error -- call wxPrinter::GetLastError to get detailed 249 information about the kind of the error. 250 */ 251 bool PrintFile(const wxString& htmlfile); 252 253 /** 254 Print HTML text (not file!). 255 256 Returns @false in case of error -- call wxPrinter::GetLastError to get detailed 257 information about the kind of the error. 258 259 @param htmltext 260 HTML text. 261 @param basepath 262 base directory (html string would be stored there if it was in file). 263 It is used to determine path for loading images, for example. 264 */ 265 bool PrintText(const wxString& htmltext, 266 const wxString& basepath = wxEmptyString); 267 268 /** 269 Sets fonts. See wxHtmlDCRenderer::SetFonts for detailed description. 270 */ 271 void SetFonts(const wxString& normal_face, const wxString& fixed_face, 272 const int* sizes = NULL); 273 274 /** 275 Sets the name used for preview frames and setup dialogs. 276 277 @since 2.8.11 / 2.9.1 278 */ 279 void SetName(const wxString& name); 280 281 /** 282 Sets default font sizes and/or default font size. 283 See wxHtmlDCRenderer::SetStandardFonts for detailed description. 284 @see SetFonts() 285 */ 286 void SetStandardFonts(int size = -1, 287 const wxString& normal_face = wxEmptyString, 288 const wxString& fixed_face = wxEmptyString); 289 290 /** 291 Set page footer. The following macros can be used inside it: 292 @@DATE@ is replaced by the current date in default format 293 @@PAGENUM@ is replaced by page number 294 @@PAGESCNT@ is replaced by total number of pages 295 @@TIME@ is replaced by the current time in default format 296 @@TITLE@ is replaced with the title of the document 297 298 @param footer 299 HTML text to be used as footer. 300 @param pg 301 one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. 302 */ 303 void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); 304 305 /** 306 Set page header. The following macros can be used inside it: 307 - @@DATE@ is replaced by the current date in default format 308 - @@PAGENUM@ is replaced by page number 309 - @@PAGESCNT@ is replaced by total number of pages 310 - @@TIME@ is replaced by the current time in default format 311 - @@TITLE@ is replaced with the title of the document 312 313 @param header 314 HTML text to be used as header. 315 @param pg 316 one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. 317 */ 318 void SetHeader(const wxString& header, int pg = wxPAGE_ALL); 319 320 /** 321 Sets the parent window for dialogs. 322 */ 323 void SetParentWindow(wxWindow* window); 324 325 private: 326 /** 327 Check whether the document fits into the page area. 328 329 This function is called by the base class OnPreparePrinting() 330 implementation and by default checks whether the document fits into 331 @a pageArea horizontally and warns the user if it does not, giving him 332 the possibility to cancel printing in this case (presumably in order to 333 change some layout options and retry it again). 334 335 You may override it to either suppress this check if truncation of the 336 HTML being printed is acceptable or, on the contrary, add more checks to 337 it, e.g. for the fit in the vertical direction if the document should 338 always appear on a single page. 339 340 @return 341 @true if wxHtmlPrintout should continue or @false to cancel 342 printing. 343 344 @since 2.9.0 345 */ 346 virtual bool CheckFit(const wxSize& pageArea, const wxSize& docArea) const; 347 }; 348 349 350 enum { 351 wxPAGE_ODD, 352 wxPAGE_EVEN, 353 wxPAGE_ALL 354 }; 355 356 357 /** 358 @class wxHtmlPrintout 359 360 This class serves as printout class for HTML documents. 361 362 @library{wxhtml} 363 @category{html,printing} 364 */ 365 class wxHtmlPrintout : public wxPrintout 366 { 367 public: 368 /** 369 Constructor. 370 */ 371 wxHtmlPrintout(const wxString& title = "Printout"); 372 373 /** 374 Adds a filter to the static list of filters for wxHtmlPrintout. 375 See wxHtmlFilter for further information. 376 */ 377 static void AddFilter(wxHtmlFilter* filter); 378 379 /** 380 This function sets font sizes and faces. See wxHtmlWindow::SetFonts 381 for detailed description. 382 */ 383 void SetFonts(const wxString& normal_face, const wxString& fixed_face, 384 const int* sizes = NULL); 385 386 /** 387 Set page footer. The following macros can be used inside it: 388 - @@DATE@ is replaced by the current date in default format 389 - @@PAGENUM@ is replaced by page number 390 - @@PAGESCNT@ is replaced by total number of pages 391 - @@TIME@ is replaced by the current time in default format 392 - @@TITLE@ is replaced with the title of the document 393 394 @param footer 395 HTML text to be used as footer. 396 @param pg 397 one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. 398 */ 399 void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); 400 401 /** 402 Set page header. The following macros can be used inside it: 403 - @@DATE@ is replaced by the current date in default format 404 - @@PAGENUM@ is replaced by page number 405 - @@PAGESCNT@ is replaced by total number of pages 406 - @@TIME@ is replaced by the current time in default format 407 - @@TITLE@ is replaced with the title of the document 408 409 @param header 410 HTML text to be used as header. 411 @param pg 412 one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. 413 */ 414 void SetHeader(const wxString& header, int pg = wxPAGE_ALL); 415 416 /** 417 Prepare the class for printing this HTML @b file. 418 The file may be located on any virtual file system or it may be normal file. 419 */ 420 void SetHtmlFile(const wxString& htmlfile); 421 422 /** 423 Prepare the class for printing this HTML text. 424 425 @param html 426 HTML text. (NOT file!) 427 @param basepath 428 base directory (html string would be stored there if it was in file). 429 It is used to determine path for loading images, for example. 430 @param isdir 431 @false if basepath is filename, @true if it is directory name 432 (see wxFileSystem for detailed explanation). 433 */ 434 void SetHtmlText(const wxString& html, 435 const wxString& basepath = wxEmptyString, 436 bool isdir = true); 437 438 /** 439 Sets margins in millimeters. 440 Defaults to 1 inch for margins and 0.5cm for space between text and header 441 and/or footer. 442 */ 443 void SetMargins(float top = 25.2, float bottom = 25.2, 444 float left = 25.2, 445 float right = 25.2, 446 float spaces = 5); 447 }; 448 449