[wxWidgets.git] / interface / fs_mem.h

/////////////////////////////////////////////////////////////////////////////
// Name:        fs_mem.h
// Purpose:     interface of wxMemoryFSHandler
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxMemoryFSHandler
    @wxheader{fs_mem.h}

    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.

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

    Example:

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

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

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