X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/html/htmprint.h diff --git a/interface/wx/html/htmprint.h b/interface/wx/html/htmprint.h index 7e5cb99a06..62b011d369 100644 --- a/interface/wx/html/htmprint.h +++ b/interface/wx/html/htmprint.h @@ -2,21 +2,18 @@ // Name: html/htmprint.h // Purpose: interface of wxHtmlDCRenderer // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @class wxHtmlDCRenderer - @headerfile htmprint.h wx/html/htmprint.h - This class can render HTML document into a specified area of a DC. You can use - it - in your own printing code, although use of wxHtmlEasyPrinting + This class can render HTML document into a specified area of a DC. + You can use it in your own printing code, although use of wxHtmlEasyPrinting or wxHtmlPrintout is strongly recommended. @library{wxhtml} - @category{FIXME} + @category{html} */ class wxHtmlDCRenderer : public wxObject { @@ -27,58 +24,127 @@ public: wxHtmlDCRenderer(); /** - Returns the height of the HTML text. This is important if area height (see - wxHtmlDCRenderer::SetSize) - is smaller that total height and thus the page cannot fit into it. In that case - you're supposed to - call Render() as long as its return value is smaller than GetTotalHeight's. + Returns the width of the HTML text in pixels. + + This can be compared with the width parameter of SetSize() to check if + the document being printed fits into the page boundary. + + @see GetTotalHeight() + + @since 2.9.0 + */ + int GetTotalWidth() const; + + /** + Returns the height of the HTML text in pixels. + + This is important if area height (see wxHtmlDCRenderer::SetSize) is + smaller that total height and thus the page cannot fit into it. In that + case you're supposed to call Render() as long as its return value is + smaller than GetTotalHeight()'s. + + @see GetTotalWidth() */ - int GetTotalHeight(); + int GetTotalHeight() const; /** Renders HTML text to the DC. - + @param x,y - position of upper-left corner of printing rectangle (see SetSize) + position of upper-left corner of printing rectangle (see SetSize()). + @param known_pagebreaks + @todo docme @param from - y-coordinate of the very first visible cell + y-coordinate of the very first visible cell. @param dont_render if @true then this method only returns y coordinate of the next page - and does not output anything + and does not output anything. + @param to + y-coordinate of the last visible cell. + + Returned value is y coordinate of first cell than didn't fit onto page. + Use this value as from in next call to Render() in order to print + multipages document. + + @note + The following three methods @b must always be called before any call to + Render(), in this order: + - SetDC() + - SetSize() + - SetHtmlText() + + @note Render() changes the DC's user scale and does NOT restore it. */ - int Render(int x, int y, int from = 0, int dont_render = false); + int Render(int x, int y, wxArrayInt& known_pagebreaks, int from = 0, + int dont_render = false, int to = INT_MAX); /** Assign DC instance to the renderer. + @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) to adjust size of pixel metrics. - (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image - would be only one - inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) + (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 + image would be only one inch wide on typical printer. With pixel_scale = 3.0 + it would be 3 inches.) */ void SetDC(wxDC* dc, double pixel_scale = 1.0); /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - See also SetSize(). + This function sets font sizes and faces. + + @param normal_face + This is face name for normal (i.e. non-fixed) font. + It can be either empty string (then the default face is chosen) or + platform-specific face name. Examples are "helvetica" under Unix or + "Times New Roman" under Windows. + @param fixed_face + The same thing for fixed face ( \..\ ) + @param sizes + This is an array of 7 items of int type. + The values represent size of font with HTML size from -2 to +4 + ( \ to \ ). + Default sizes are used if sizes is @NULL. + + Default font sizes are defined by constants wxHTML_FONT_SIZE_1, + wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7. + Note that they differ among platforms. Default face names are empty strings. + + @see SetSize() + */ + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = NULL); + + /** + Sets font sizes to be relative to the given size or the system + default size; use either specified or default font + + @param size + Point size of the default HTML text + @param normal_face + This is face name for normal (i.e. non-fixed) font. It can be + either empty string (then the default face is chosen) or + platform-specific face name. Examples are "helvetica" under + Unix or "Times New Roman" under Windows. + @param fixed_face + The same thing for fixed face ( \..\ ) + + @see SetSize() */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetStandardFonts(int size = -1, + const wxString& normal_face = wxEmptyString, + const wxString& fixed_face = wxEmptyString); /** - Assign text to the renderer. Render() then draws - the text onto DC. - + Assign text to the renderer. Render() then draws the text onto DC. + @param html HTML text. This is not a filename. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. @param isdir @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + (see wxFileSystem for detailed explanation). */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, @@ -86,7 +152,7 @@ public: /** Set size of output rectangle, in pixels. Note that you @b can't change - width of the rectangle between calls to wxHtmlDCRenderer::Render! + width of the rectangle between calls to Render() ! (You can freely change height.) */ void SetSize(int width, int height); @@ -96,33 +162,44 @@ public: /** @class wxHtmlEasyPrinting - @headerfile htmprint.h wx/html/htmprint.h - This class provides very simple interface to printing - architecture. It allows you to print HTML documents using - only a few commands. + This class provides very simple interface to printing architecture. + It allows you to print HTML documents using only a few commands. + + @note + Do not create this class on the stack only. You should create an instance + on app startup and use this instance for all printing operations. + The reason is that this class stores various settings in it. @library{wxhtml} - @category{html} + @category{html,printing} */ class wxHtmlEasyPrinting : public wxObject { public: /** Constructor. - + @param name Name of the printing object. Used by preview frames and setup dialogs. @param parentWindow pointer to the window that will own the preview frame and setup dialogs. - May be @NULL. + May be @NULL. */ wxHtmlEasyPrinting(const wxString& name = "Printing", wxWindow* parentWindow = NULL); /** - Returns a pointer to wxPageSetupDialogData instance used by - this class. You can set its parameters (via SetXXXX methods). + Returns the current name being used for preview frames and setup + dialogs. + + @since 2.8.11 / 2.9.1 + */ + const wxString& GetName() const; + + /** + Returns a pointer to wxPageSetupDialogData instance used by this class. + You can set its parameters (via SetXXXX methods). */ wxPageSetupDialogData* GetPageSetupData(); @@ -132,8 +209,8 @@ public: wxWindow* GetParentWindow() const; /** - Returns pointer to wxPrintData instance used by this class. You can - set its parameters (via SetXXXX methods). + Returns pointer to wxPrintData instance used by this class. + You can set its parameters (via SetXXXX methods). */ wxPrintData* GetPrintData(); @@ -144,66 +221,80 @@ public: /** Preview HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. */ bool PreviewFile(const wxString& htmlfile); /** Preview HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. - + @param htmltext HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. */ bool PreviewText(const wxString& htmltext, const wxString& basepath = wxEmptyString); /** Print HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. */ bool PrintFile(const wxString& htmlfile); /** Print HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed + + Returns @false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error. - + @param htmltext HTML text. @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. */ bool PrintText(const wxString& htmltext, const wxString& basepath = wxEmptyString); /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. + Sets fonts. See wxHtmlDCRenderer::SetFonts for detailed description. + */ + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = NULL); + + /** + Sets the name used for preview frames and setup dialogs. + + @since 2.8.11 / 2.9.1 + */ + void SetName(const wxString& name); + + /** + Sets default font sizes and/or default font size. + See wxHtmlDCRenderer::SetStandardFonts for detailed description. + @see SetFonts() */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetStandardFonts(int size = -1, + const wxString& normal_face = wxEmptyString, + const wxString& fixed_face = wxEmptyString); /** Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - + @@DATE@ is replaced by the current date in default format + @@PAGENUM@ is replaced by page number + @@PAGESCNT@ is replaced by total number of pages + @@TIME@ is replaced by the current time in default format + @@TITLE@ is replaced with the title of the document + @param footer HTML text to be used as footer. @param pg @@ -213,12 +304,12 @@ public: /** Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param header HTML text to be used as header. @param pg @@ -230,18 +321,46 @@ public: Sets the parent window for dialogs. */ void SetParentWindow(wxWindow* window); + +private: + /** + Check whether the document fits into the page area. + + This function is called by the base class OnPreparePrinting() + implementation and by default checks whether the document fits into + @a pageArea horizontally and warns the user if it does not, giving him + the possibility to cancel printing in this case (presumably in order to + change some layout options and retry it again). + + You may override it to either suppress this check if truncation of the + HTML being printed is acceptable or, on the contrary, add more checks to + it, e.g. for the fit in the vertical direction if the document should + always appear on a single page. + + @return + @true if wxHtmlPrintout should continue or @false to cancel + printing. + + @since 2.9.0 + */ + virtual bool CheckFit(const wxSize& pageArea, const wxSize& docArea) const; }; +enum { + wxPAGE_ODD, + wxPAGE_EVEN, + wxPAGE_ALL +}; + /** @class wxHtmlPrintout - @headerfile htmprint.h wx/html/htmprint.h This class serves as printout class for HTML documents. @library{wxhtml} - @category{html} + @category{html,printing} */ class wxHtmlPrintout : public wxPrintout { @@ -252,28 +371,26 @@ public: wxHtmlPrintout(const wxString& title = "Printout"); /** - Adds a filter to the static list of filters for wxHtmlPrintout. See - wxHtmlFilter for - further information. + Adds a filter to the static list of filters for wxHtmlPrintout. + See wxHtmlFilter for further information. */ static void AddFilter(wxHtmlFilter* filter); /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. + This function sets font sizes and faces. See wxHtmlWindow::SetFonts + for detailed description. */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); + void SetFonts(const wxString& normal_face, const wxString& fixed_face, + const int* sizes = NULL); /** Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param footer HTML text to be used as footer. @param pg @@ -283,12 +400,12 @@ public: /** Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - + - @@DATE@ is replaced by the current date in default format + - @@PAGENUM@ is replaced by page number + - @@PAGESCNT@ is replaced by total number of pages + - @@TIME@ is replaced by the current time in default format + - @@TITLE@ is replaced with the title of the document + @param header HTML text to be used as header. @param pg @@ -297,30 +414,31 @@ public: void SetHeader(const wxString& header, int pg = wxPAGE_ALL); /** - Prepare the class for printing this HTML @b file. The file may be located on - any virtual file system or it may be normal file. + Prepare the class for printing this HTML @b file. + The file may be located on any virtual file system or it may be normal file. */ void SetHtmlFile(const wxString& htmlfile); /** Prepare the class for printing this HTML text. - + @param html HTML text. (NOT file!) @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. + base directory (html string would be stored there if it was in file). + It is used to determine path for loading images, for example. @param isdir @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) + (see wxFileSystem for detailed explanation). */ void SetHtmlText(const wxString& html, const wxString& basepath = wxEmptyString, bool isdir = true); /** - Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space - between text and header and/or footer + Sets margins in millimeters. + Defaults to 1 inch for margins and 0.5cm for space between text and header + and/or footer. */ void SetMargins(float top = 25.2, float bottom = 25.2, float left = 25.2,