[wxWidgets.git] / interface / wx / fs_mem.h

/////////////////////////////////////////////////////////////////////////////
// Name:        fs_mem.h
// Purpose:     interface of wxMemoryFSHandler
// Author:      wxWidgets team
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxMemoryFSHandler

    This wxFileSystem handler can store arbitrary data in memory stream and make
    them accessible via an URL.

    It is particularly suitable for storing bitmaps from resources or included XPM
    files so that they can be used with wxHTML or wxWebView.

    Filenames are prefixed with @c "memory:", e.g. @c "memory:myfile.html".

    Example:

    @code
    #ifndef __WXMSW__
    #include "logo.xpm"
    #endif

    void MyFrame::OnAbout(wxCommandEvent&)
    {
        wxFileSystem::AddHandler(new wxMemoryFSHandler);
        wxMemoryFSHandler::AddFile("logo.png", wxBITMAP(logo), wxBITMAP_TYPE_PNG);
        wxMemoryFSHandler::AddFile("about.htm",
                                "<html><body>About: "
                                "<img src=\"memory:logo.png\"></body></html>");

        wxDialog dlg(this, -1, wxString(_("About")));
        wxBoxSizer *topsizer;
        topsizer = new wxBoxSizer(wxVERTICAL);
    #ifdef USE_WEBVIEW
        wxWebView* browser = wxWebView::New(&dlg, wxID_ANY, wxWebViewDefaultURLStr,
                                 wxDefaultPosition, wxSize(380, 160));
        browser->RegisterHandler(wxSharedPtr<wxWebViewHandler>(new wxWebViewFSHandler("memory")));
        browser->LoadURL("memory:about.htm");
    #else // Use wxHtml
        wxHtmlWindow *browser;
        browser = new wxHtmlWindow(&dlg, -1, wxDefaultPosition,
                                   wxSize(380, 160), wxHW_SCROLLBAR_NEVER);
        browser->SetBorders(0);
        browser->LoadPage("memory:about.htm");
        browser->SetSize(browser->GetInternalRepresentation()->GetWidth(),
                    browser->GetInternalRepresentation()->GetHeight());
    #endif
        topsizer->Add(browser, 1, wxALL, 10);
        topsizer->Add(new wxStaticLine(&dlg, -1), 0, wxEXPAND | wxLEFT | wxRIGHT, 10);
        topsizer->Add(new wxButton(&dlg, wxID_OK, "Ok"),
                    0, wxALL | wxALIGN_RIGHT, 15);
        dlg.SetAutoLayout(true);
        dlg.SetSizer(topsizer);
        topsizer->Fit(&dlg);
        dlg.Centre();
        dlg.ShowModal();

        wxMemoryFSHandler::RemoveFile("logo.png");
        wxMemoryFSHandler::RemoveFile("about.htm");
    }
    @endcode

    @library{wxbase}
    @category{vfs}

    @see wxMemoryFSHandler::AddFileWithMimeType
*/
class wxMemoryFSHandler : public wxFileSystemHandler
{
public:
    /**
        Constructor.
    */
    wxMemoryFSHandler();

    //@{
    /**
        Adds a file to the list of the files stored in memory.

        Stored data (bitmap, text or raw data) will be copied into private memory
        stream and available under name @c "memory:" + @e filename.

        @note you must use a @a type value (aka image format) that wxWidgets
              can save (e.g. JPG, PNG, see wxImage documentation)!

        @see AddFileWithMimeType()
    */
    static void AddFile(const wxString& filename, wxImage& image, wxBitmapType type);
    static void AddFile(const wxString& filename, const wxBitmap& bitmap, wxBitmapType type);
    //@}

    //@{
    /**
        Like AddFile(), but lets you explicitly specify added file's MIME type.

        This version should be used whenever you know the MIME type, because it
        makes accessing the files faster.

        @since 2.8.5

        @see AddFile()
    */
    static void AddFileWithMimeType(const wxString& filename,
                                    const wxString& textdata,
                                    const wxString& mimetype);
    static void AddFileWithMimeType(const wxString& filename,
                                    const void* binarydata,
                                    size_t size,
                                    const wxString& mimetype);
    //@}

    /**
        Removes a file from memory FS and frees the occupied memory.
    */
    static void RemoveFile(const wxString& filename);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: fs_mem.h
e54c96f1	3	// Purpose: interface of wxMemoryFSHandler
23324ae1	4	// Author: wxWidgets team
526954c5	5	// Licence: wxWindows licence
23324ae1 FM	6	/////////////////////////////////////////////////////////////////////////////
	7
	8	/**
	9	@class wxMemoryFSHandler
7c913512	10
ea6a2ccb FM	11	This wxFileSystem handler can store arbitrary data in memory stream and make
ea6a2ccb FM	12	them accessible via an URL.
7c913512	13
ea6a2ccb	14	It is particularly suitable for storing bitmaps from resources or included XPM
0bfd90b3	15	files so that they can be used with wxHTML or wxWebView.
ea6a2ccb FM	16
ea6a2ccb FM	17	Filenames are prefixed with @c "memory:", e.g. @c "memory:myfile.html".
7c913512	18
23324ae1	19	Example:
7c913512	20
23324ae1 FM	21	@code
	22	#ifndef __WXMSW__
	23	#include "logo.xpm"
	24	#endif
7c913512	25
23324ae1 FM	26	void MyFrame::OnAbout(wxCommandEvent&)
23324ae1 FM	27	{
23324ae1	28	wxFileSystem::AddHandler(new wxMemoryFSHandler);
0bfd90b3	29	wxMemoryFSHandler::AddFile("logo.png", wxBITMAP(logo), wxBITMAP_TYPE_PNG);
7c913512	30	wxMemoryFSHandler::AddFile("about.htm",
ea6a2ccb	31	"<html><body>About: "
0bfd90b3	32	"<img src=\"memory:logo.png\"></body></html>");
7c913512	33
23324ae1 FM	34	wxDialog dlg(this, -1, wxString(_("About")));
23324ae1 FM	35	wxBoxSizer *topsizer;
23324ae1	36	topsizer = new wxBoxSizer(wxVERTICAL);
0bfd90b3 SL	37	#ifdef USE_WEBVIEW
	38	wxWebView* browser = wxWebView::New(&dlg, wxID_ANY, wxWebViewDefaultURLStr,
	39	wxDefaultPosition, wxSize(380, 160));
	40	browser->RegisterHandler(wxSharedPtr<wxWebViewHandler>(new wxWebViewFSHandler("memory")));
	41	browser->LoadURL("memory:about.htm");
	42	#else // Use wxHtml
	43	wxHtmlWindow *browser;
	44	browser = new wxHtmlWindow(&dlg, -1, wxDefaultPosition,
	45	wxSize(380, 160), wxHW_SCROLLBAR_NEVER);
	46	browser->SetBorders(0);
	47	browser->LoadPage("memory:about.htm");
	48	browser->SetSize(browser->GetInternalRepresentation()->GetWidth(),
	49	browser->GetInternalRepresentation()->GetHeight());
	50	#endif
	51	topsizer->Add(browser, 1, wxALL, 10);
ea6a2ccb FM	52	topsizer->Add(new wxStaticLine(&dlg, -1), 0, wxEXPAND \| wxLEFT \| wxRIGHT, 10);
	53	topsizer->Add(new wxButton(&dlg, wxID_OK, "Ok"),
	54	0, wxALL \| wxALIGN_RIGHT, 15);
	55	dlg.SetAutoLayout(true);
23324ae1	56	dlg.SetSizer(topsizer);
ea6a2ccb	57	topsizer->Fit(&dlg);
23324ae1 FM	58	dlg.Centre();
23324ae1 FM	59	dlg.ShowModal();
7c913512	60
0bfd90b3	61	wxMemoryFSHandler::RemoveFile("logo.png");
23324ae1 FM	62	wxMemoryFSHandler::RemoveFile("about.htm");
	63	}
	64	@endcode
7c913512	65
23324ae1	66	@library{wxbase}
ea6a2ccb	67	@category{vfs}
7c913512	68
e54c96f1	69	@see wxMemoryFSHandler::AddFileWithMimeType
23324ae1 FM	70	*/
	71	class wxMemoryFSHandler : public wxFileSystemHandler
	72	{
	73	public:
	74	/**
	75	Constructor.
	76	*/
	77	wxMemoryFSHandler();
	78
	79	//@{
	80	/**
ea6a2ccb FM	81	Adds a file to the list of the files stored in memory.
	82
	83	Stored data (bitmap, text or raw data) will be copied into private memory
	84	stream and available under name @c "memory:" + @e filename.
	85
	86	@note you must use a @a type value (aka image format) that wxWidgets
	87	can save (e.g. JPG, PNG, see wxImage documentation)!
3c4f71cc	88
4cc4bfaf	89	@see AddFileWithMimeType()
23324ae1	90	*/
ea6a2ccb FM	91	static void AddFile(const wxString& filename, wxImage& image, wxBitmapType type);
ea6a2ccb FM	92	static void AddFile(const wxString& filename, const wxBitmap& bitmap, wxBitmapType type);
23324ae1 FM	93	//@}
	94
	95	//@{
	96	/**
ea6a2ccb FM	97	Like AddFile(), but lets you explicitly specify added file's MIME type.
	98
	99	This version should be used whenever you know the MIME type, because it
	100	makes accessing the files faster.
3c4f71cc	101
1e24c2af	102	@since 2.8.5
3c4f71cc	103
4cc4bfaf	104	@see AddFile()
23324ae1 FM	105	*/
	106	static void AddFileWithMimeType(const wxString& filename,
	107	const wxString& textdata,
	108	const wxString& mimetype);
7c913512 FM	109	static void AddFileWithMimeType(const wxString& filename,
	110	const void* binarydata,
	111	size_t size,
	112	const wxString& mimetype);
23324ae1 FM	113	//@}
	114
	115	/**
ea6a2ccb	116	Removes a file from memory FS and frees the occupied memory.
23324ae1 FM	117	*/
	118	static void RemoveFile(const wxString& filename);
	119	};
e54c96f1	120