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

/////////////////////////////////////////////////////////////////////////////
// Name:        fs_mem.h
// Purpose:     interface of wxMemoryFSHandler
// Author:      wxWidgets team
// RCS-ID:      $Id$
// 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.

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