[wxWidgets.git] / include / wx / htmllbox.h

///////////////////////////////////////////////////////////////////////////////
// Name:        wx/htmllbox.h
// Purpose:     wxHtmlListBox is a listbox whose items are wxHtmlCells
// Author:      Vadim Zeitlin
// Modified by:
// Created:     31.05.03
// RCS-ID:      $Id$
// Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

#ifndef _WX_HTMLLBOX_H_
#define _WX_HTMLLBOX_H_

#include "wx/vlbox.h"               // base class
#include "wx/html/htmlwin.h"

#if wxUSE_FILESYSTEM
    #include "wx/filesys.h"
#endif // wxUSE_FILESYSTEM

class WXDLLIMPEXP_HTML wxHtmlCell;
class WXDLLIMPEXP_HTML wxHtmlWinParser;
class WXDLLIMPEXP_HTML wxHtmlListBoxCache;
class WXDLLIMPEXP_HTML wxHtmlListBoxStyle;

// ----------------------------------------------------------------------------
// wxHtmlListBox
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_HTML wxHtmlListBox : public wxVListBox,
                                       public wxHtmlWindowInterface,
                                       private wxHtmlWindowMouseHelper
{
    DECLARE_ABSTRACT_CLASS(wxHtmlListBox)
public:
    // constructors and such
    // ---------------------

    // default constructor, you must call Create() later
    wxHtmlListBox();

    // normal constructor which calls Create() internally
    wxHtmlListBox(wxWindow *parent,
                  wxWindowID id = wxID_ANY,
                  const wxPoint& pos = wxDefaultPosition,
                  const wxSize& size = wxDefaultSize,
                  long style = 0,
                  const wxString& name = wxVListBoxNameStr);

    // really creates the control and sets the initial number of items in it
    // (which may be changed later with SetItemCount())
    //
    // the only special style which may be specified here is wxLB_MULTIPLE
    //
    // returns true on success or false if the control couldn't be created
    bool Create(wxWindow *parent,
                wxWindowID id = wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0,
                const wxString& name = wxVListBoxNameStr);

    // destructor cleans up whatever resources we use
    virtual ~wxHtmlListBox();

    // override some base class virtuals
    virtual void RefreshLine(size_t line);
    virtual void RefreshLines(size_t from, size_t to);
    virtual void RefreshAll();
    virtual void SetItemCount(size_t count);


#if wxUSE_FILESYSTEM
    // retrieve the file system used by the wxHtmlWinParser: if you use
    // relative paths in your HTML, you should use its ChangePathTo() method
    wxFileSystem& GetFileSystem() { return m_filesystem; }
    const wxFileSystem& GetFileSystem() const { return m_filesystem; }
#endif // wxUSE_FILESYSTEM

    virtual void OnInternalIdle();

protected:
    // this method must be implemented in the derived class and should return
    // the body (i.e. without <html>) of the HTML for the given item
    virtual wxString OnGetItem(size_t n) const = 0;

    // this function may be overridden to decorate HTML returned by OnGetItem()
    virtual wxString OnGetItemMarkup(size_t n) const;


    // this method allows to customize the selection appearance: it may be used
    // to specify the colour of the text which normally has the given colour
    // colFg when it is inside the selection
    //
    // by default, the original colour is not used at all and all text has the
    // same (default for this system) colour inside selection
    virtual wxColour GetSelectedTextColour(const wxColour& colFg) const;

    // this is the same as GetSelectedTextColour() but allows to customize the
    // background colour -- this is even more rarely used as you can change it
    // globally using SetSelectionBackground()
    virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const;


    // we implement both of these functions in terms of OnGetItem(), they are
    // not supposed to be overridden by our descendants
    virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const;
    virtual wxCoord OnMeasureItem(size_t n) const;

    // This method may be overriden to handle clicking on a link in
    // the listbox. By default, clicking links is ignored.
    virtual void OnLinkClicked(size_t WXUNUSED(n),
                               const wxHtmlLinkInfo& WXUNUSED(link)) {}

    // event handlers
    void OnSize(wxSizeEvent& event);
    void OnMouseMove(wxMouseEvent& event);
    void OnLeftDown(wxMouseEvent& event);


    // common part of all ctors
    void Init();

    // ensure that the given item is cached
    void CacheItem(size_t n) const;

private:
    // wxHtmlWindowInterface methods:
    virtual void SetHTMLWindowTitle(const wxString& title);
    virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link);
    virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
                                                 const wxString& url,
                                                 wxString *redirect) const;
    virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
                                       const wxPoint& pos) const;
    virtual wxWindow* GetHTMLWindow();
    virtual wxColour GetHTMLBackgroundColour() const;
    virtual void SetHTMLBackgroundColour(const wxColour& clr);
    virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg);
    virtual void SetHTMLStatusText(const wxString& text);

    // returns index of item that contains given HTML cell
    size_t GetItemForCell(const wxHtmlCell *cell) const;

    // return physical coordinates of root wxHtmlCell of n-th item
    wxPoint GetRootCellCoords(size_t n) const;

    // Converts physical coordinates stored in @a pos into coordinates
    // relative to the root cell of the item under mouse cursor, if any. If no
    // cell is found under the cursor, returns false.  Otherwise stores the new
    // coordinates back into @a pos and pointer to the cell under cursor into
    // @a cell and returns true.
    bool PhysicalCoordsToCell(wxPoint& pos, wxHtmlCell*& cell) const;

    // The opposite of PhysicalCoordsToCell: converts coordinates relative to
    // given cell to physical coordinates in the window
    wxPoint CellCoordsToPhysical(const wxPoint& pos, wxHtmlCell *cell) const;

private:
    // this class caches the pre-parsed HTML to speed up display
    wxHtmlListBoxCache *m_cache;

    // HTML parser we use
    wxHtmlWinParser *m_htmlParser;

#if wxUSE_FILESYSTEM
    // file system used by m_htmlParser
    wxFileSystem m_filesystem;
#endif // wxUSE_FILESYSTEM

    // rendering style for the parser which allows us to customize our colours
    wxHtmlListBoxStyle *m_htmlRendStyle;


    // it calls our GetSelectedTextColour() and GetSelectedTextBgColour()
    friend class wxHtmlListBoxStyle;
    friend class wxHtmlListBoxWinInterface;


    DECLARE_EVENT_TABLE()
    DECLARE_NO_COPY_CLASS(wxHtmlListBox)
};

#endif // _WX_HTMLLBOX_H_
Commit	Line	Data
e0c6027b VZ	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/htmllbox.h
	3	// Purpose: wxHtmlListBox is a listbox whose items are wxHtmlCells
	4	// Author: Vadim Zeitlin
	5	// Modified by:
	6	// Created: 31.05.03
	7	// RCS-ID: $Id$
77ffb593	8	// Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwidgets.org>
65571936	9	// Licence: wxWindows licence
e0c6027b VZ	10	///////////////////////////////////////////////////////////////////////////////
	11
	12	#ifndef _WX_HTMLLBOX_H_
	13	#define _WX_HTMLLBOX_H_
	14
	15	#include "wx/vlbox.h" // base class
bc55e31b	16	#include "wx/html/htmlwin.h"
e0c6027b	17
2d814c19 VZ	18	#if wxUSE_FILESYSTEM
	19	#include "wx/filesys.h"
	20	#endif // wxUSE_FILESYSTEM
	21
6acba9a7 VS	22	class WXDLLIMPEXP_HTML wxHtmlCell;
	23	class WXDLLIMPEXP_HTML wxHtmlWinParser;
	24	class WXDLLIMPEXP_HTML wxHtmlListBoxCache;
	25	class WXDLLIMPEXP_HTML wxHtmlListBoxStyle;
e0c6027b VZ	26
	27	// ----------------------------------------------------------------------------
	28	// wxHtmlListBox
	29	// ----------------------------------------------------------------------------
	30
bc55e31b VS	31	class WXDLLIMPEXP_HTML wxHtmlListBox : public wxVListBox,
	32	public wxHtmlWindowInterface,
	33	private wxHtmlWindowMouseHelper
e0c6027b	34	{
0c8392ca	35	DECLARE_ABSTRACT_CLASS(wxHtmlListBox)
e0c6027b VZ	36	public:
	37	// constructors and such
	38	// ---------------------
	39
	40	// default constructor, you must call Create() later
bc55e31b	41	wxHtmlListBox();
e0c6027b VZ	42
	43	// normal constructor which calls Create() internally
	44	wxHtmlListBox(wxWindow *parent,
	45	wxWindowID id = wxID_ANY,
	46	const wxPoint& pos = wxDefaultPosition,
	47	const wxSize& size = wxDefaultSize,
e0c6027b	48	long style = 0,
bc55e31b	49	const wxString& name = wxVListBoxNameStr);
e0c6027b VZ	50
	51	// really creates the control and sets the initial number of items in it
	52	// (which may be changed later with SetItemCount())
	53	//
43e319a3	54	// the only special style which may be specified here is wxLB_MULTIPLE
e0c6027b VZ	55	//
	56	// returns true on success or false if the control couldn't be created
	57	bool Create(wxWindow *parent,
	58	wxWindowID id = wxID_ANY,
	59	const wxPoint& pos = wxDefaultPosition,
	60	const wxSize& size = wxDefaultSize,
e0c6027b VZ	61	long style = 0,
	62	const wxString& name = wxVListBoxNameStr);
	63
	64	// destructor cleans up whatever resources we use
	65	virtual ~wxHtmlListBox();
	66
03495767	67	// override some base class virtuals
5c2a509f VZ	68	virtual void RefreshLine(size_t line);
5c2a509f VZ	69	virtual void RefreshLines(size_t from, size_t to);
5ecdc7ab	70	virtual void RefreshAll();
03495767	71	virtual void SetItemCount(size_t count);
5ecdc7ab	72
2d814c19 VZ	73
	74	#if wxUSE_FILESYSTEM
	75	// retrieve the file system used by the wxHtmlWinParser: if you use
	76	// relative paths in your HTML, you should use its ChangePathTo() method
	77	wxFileSystem& GetFileSystem() { return m_filesystem; }
	78	const wxFileSystem& GetFileSystem() const { return m_filesystem; }
	79	#endif // wxUSE_FILESYSTEM
	80
bc55e31b VS	81	virtual void OnInternalIdle();
bc55e31b VS	82
e0c6027b VZ	83	protected:
	84	// this method must be implemented in the derived class and should return
	85	// the body (i.e. without <html>) of the HTML for the given item
	86	virtual wxString OnGetItem(size_t n) const = 0;
	87
	88	// this function may be overridden to decorate HTML returned by OnGetItem()
	89	virtual wxString OnGetItemMarkup(size_t n) const;
	90
	91
9a9b4940 VZ	92	// this method allows to customize the selection appearance: it may be used
	93	// to specify the colour of the text which normally has the given colour
	94	// colFg when it is inside the selection
	95	//
	96	// by default, the original colour is not used at all and all text has the
	97	// same (default for this system) colour inside selection
	98	virtual wxColour GetSelectedTextColour(const wxColour& colFg) const;
	99
	100	// this is the same as GetSelectedTextColour() but allows to customize the
	101	// background colour -- this is even more rarely used as you can change it
	102	// globally using SetSelectionBackground()
	103	virtual wxColour GetSelectedTextBgColour(const wxColour& colBg) const;
	104
	105
e0c6027b VZ	106	// we implement both of these functions in terms of OnGetItem(), they are
	107	// not supposed to be overridden by our descendants
	108	virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const;
	109	virtual wxCoord OnMeasureItem(size_t n) const;
	110
bc55e31b VS	111	// This method may be overriden to handle clicking on a link in
	112	// the listbox. By default, clicking links is ignored.
	113	virtual void OnLinkClicked(size_t WXUNUSED(n),
	114	const wxHtmlLinkInfo& WXUNUSED(link)) {}
e0c6027b	115
5ecdc7ab VZ	116	// event handlers
5ecdc7ab VZ	117	void OnSize(wxSizeEvent& event);
bc55e31b VS	118	void OnMouseMove(wxMouseEvent& event);
bc55e31b VS	119	void OnLeftDown(wxMouseEvent& event);
5ecdc7ab VZ	120
5ecdc7ab VZ	121
e0c6027b VZ	122	// common part of all ctors
	123	void Init();
	124
	125	// ensure that the given item is cached
	126	void CacheItem(size_t n) const;
	127
bc55e31b VS	128	private:
	129	// wxHtmlWindowInterface methods:
	130	virtual void SetHTMLWindowTitle(const wxString& title);
	131	virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link);
	132	virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
	133	const wxString& url,
	134	wxString *redirect) const;
	135	virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
	136	const wxPoint& pos) const;
	137	virtual wxWindow* GetHTMLWindow();
	138	virtual wxColour GetHTMLBackgroundColour() const;
	139	virtual void SetHTMLBackgroundColour(const wxColour& clr);
	140	virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg);
	141	virtual void SetHTMLStatusText(const wxString& text);
	142
	143	// returns index of item that contains given HTML cell
	144	size_t GetItemForCell(const wxHtmlCell *cell) const;
	145
	146	// return physical coordinates of root wxHtmlCell of n-th item
	147	wxPoint GetRootCellCoords(size_t n) const;
	148
	149	// Converts physical coordinates stored in @a pos into coordinates
	150	// relative to the root cell of the item under mouse cursor, if any. If no
	151	// cell is found under the cursor, returns false. Otherwise stores the new
	152	// coordinates back into @a pos and pointer to the cell under cursor into
	153	// @a cell and returns true.
	154	bool PhysicalCoordsToCell(wxPoint& pos, wxHtmlCell*& cell) const;
	155
	156	// The opposite of PhysicalCoordsToCell: converts coordinates relative to
	157	// given cell to physical coordinates in the window
	158	wxPoint CellCoordsToPhysical(const wxPoint& pos, wxHtmlCell *cell) const;
	159
e0c6027b	160	private:
9a9b4940	161	// this class caches the pre-parsed HTML to speed up display
e0c6027b VZ	162	wxHtmlListBoxCache *m_cache;
	163
	164	// HTML parser we use
	165	wxHtmlWinParser *m_htmlParser;
5ecdc7ab	166
2d814c19 VZ	167	#if wxUSE_FILESYSTEM
	168	// file system used by m_htmlParser
	169	wxFileSystem m_filesystem;
	170	#endif // wxUSE_FILESYSTEM
	171
9a9b4940 VZ	172	// rendering style for the parser which allows us to customize our colours
	173	wxHtmlListBoxStyle *m_htmlRendStyle;
	174
	175
	176	// it calls our GetSelectedTextColour() and GetSelectedTextBgColour()
	177	friend class wxHtmlListBoxStyle;
bc55e31b	178	friend class wxHtmlListBoxWinInterface;
9a9b4940	179
5ecdc7ab VZ	180
5ecdc7ab VZ	181	DECLARE_EVENT_TABLE()
27d0dcd0	182	DECLARE_NO_COPY_CLASS(wxHtmlListBox)
e0c6027b VZ	183	};
	184
	185	#endif // _WX_HTMLLBOX_H_
	186