[wxWidgets.git] / interface / wx / html / htmprint.h

/////////////////////////////////////////////////////////////////////////////
// Name:        html/htmprint.h
// Purpose:     interface of wxHtmlDCRenderer
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxHtmlDCRenderer

    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}
*/
class wxHtmlDCRenderer : public wxObject
{
public:
    /**
        Constructor.
    */
    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.
    */
    int GetTotalHeight();

    /**
        Renders HTML text to the DC.
        
        @param x,y
            position of upper-left corner of printing rectangle (see SetSize)
        @param from
            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
    */
    int Render(int x, int y, int from = 0, int dont_render = false);

    /**
        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.)
    */
    void SetDC(wxDC* dc, double pixel_scale = 1.0);

    /**
        Sets fonts. See wxHtmlWindow::SetFonts for
        detailed description.
        See also SetSize().
    */
    void SetFonts(const wxString& normal_face,
                  const wxString& fixed_face,
                  const int sizes = NULL);

    /**
        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.
        @param isdir
            @false if basepath is filename, @true if it is directory name
            (see wxFileSystem for detailed explanation)
    */
    void SetHtmlText(const wxString& html,
                     const wxString& basepath = wxEmptyString,
                     bool isdir = true);

    /**
        Set size of output rectangle, in pixels. Note that you @b can't change
        width of the rectangle between calls to wxHtmlDCRenderer::Render!
        (You can freely change height.)
    */
    void SetSize(int width, int height);
};


/**
    @class wxHtmlEasyPrinting

    This class provides very simple interface to printing
    architecture. It allows you to print HTML documents using
    only a few commands.

    @library{wxhtml}
    @category{html}
*/
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.
    */
    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).
    */
    wxPageSetupDialogData* GetPageSetupData();

    /**
        Gets the parent window for dialogs.
    */
    wxWindow* GetParentWindow() const;

    /**
        Returns pointer to wxPrintData instance used by this class. You can
        set its parameters (via SetXXXX methods).
    */
    wxPrintData* GetPrintData();

    /**
        Display page setup dialog and allows the user to modify settings.
    */
    void PageSetup();

    /**
        Preview HTML file.
        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
        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.
    */
    bool PreviewText(const wxString& htmltext,
                     const wxString& basepath = wxEmptyString);

    /**
        Print HTML file.
        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
        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.
    */
    bool PrintText(const wxString& htmltext,
                   const wxString& basepath = wxEmptyString);

    /**
        Sets fonts. See wxHtmlWindow::SetFonts for
        detailed description.
    */
    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
        
        @param footer
            HTML text to be used as footer.
        @param pg
            one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
    */
    void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);

    /**
        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
        
        @param header
            HTML text to be used as header.
        @param pg
            one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
    */
    void SetHeader(const wxString& header, int pg = wxPAGE_ALL);

    /**
        Sets the parent window for dialogs.
    */
    void SetParentWindow(wxWindow* window);
};


/**
    @class wxHtmlPrintout

    This class serves as printout class for HTML documents.

    @library{wxhtml}
    @category{html}
*/
class wxHtmlPrintout : public wxPrintout
{
public:
    /**
        Constructor.
    */
    wxHtmlPrintout(const wxString& title = "Printout");

    /**
        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.
    */
    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
        
        @param footer
            HTML text to be used as footer.
        @param pg
            one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants.
    */
    void SetFooter(const wxString& footer, int pg = wxPAGE_ALL);

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