// Name: html/htmlwin.h
// Purpose: interface of wxHtmlWindow
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+// wxHtmlWindow flags:
+#define wxHW_SCROLLBAR_NEVER 0x0002
+#define wxHW_SCROLLBAR_AUTO 0x0004
+#define wxHW_NO_SELECTION 0x0008
+
+#define wxHW_DEFAULT_STYLE wxHW_SCROLLBAR_AUTO
+
+
+/// Enum for wxHtmlWindow::OnOpeningURL and wxHtmlWindowInterface::OnOpeningURL
+enum wxHtmlOpeningStatus
+{
+ /// Open the requested URL
+ wxHTML_OPEN,
+ /// Do not open the URL
+ wxHTML_BLOCK,
+ /// Redirect to another URL (returned from OnOpeningURL)
+ wxHTML_REDIRECT
+};
+
+
+/**
+ @class wxHtmlWindowInterface
+
+ Abstract interface to a HTML rendering window (such as wxHtmlWindow or
+ wxHtmlListBox) that is passed to wxHtmlWinParser. It encapsulates all
+ communication from the parser to the window.
+ */
+class wxHtmlWindowInterface
+{
+public:
+ /// Ctor
+ wxHtmlWindowInterface();
+ virtual ~wxHtmlWindowInterface();
+
+ /**
+ Called by the parser to set window's title to given text.
+ */
+ virtual void SetHTMLWindowTitle(const wxString& title) = 0;
+
+ /**
+ Called when a link is clicked.
+
+ @param link information about the clicked link
+ */
+ virtual void OnHTMLLinkClicked(const wxHtmlLinkInfo& link) = 0;
+
+ /**
+ Called when the parser needs to open another URL (e.g. an image).
+
+ @param type Type of the URL request (e.g. image)
+ @param url URL the parser wants to open
+ @param redirect If the return value is wxHTML_REDIRECT, then the
+ URL to redirect to will be stored in this variable
+ (the pointer must never be NULL)
+
+ @return indicator of how to treat the request
+ */
+ virtual wxHtmlOpeningStatus OnHTMLOpeningURL(wxHtmlURLType type,
+ const wxString& url,
+ wxString *redirect) const = 0;
+
+ /**
+ Converts coordinates @a pos relative to given @a cell to
+ physical coordinates in the window.
+ */
+ virtual wxPoint HTMLCoordsToWindow(wxHtmlCell *cell,
+ const wxPoint& pos) const = 0;
+
+ /// Returns the window used for rendering (may be NULL).
+ virtual wxWindow* GetHTMLWindow() = 0;
+
+ /// Returns background colour to use by default.
+ virtual wxColour GetHTMLBackgroundColour() const = 0;
+
+ /// Sets window's background to colour @a clr.
+ virtual void SetHTMLBackgroundColour(const wxColour& clr) = 0;
+
+ /// Sets window's background to given bitmap.
+ virtual void SetHTMLBackgroundImage(const wxBitmap& bmpBg) = 0;
+
+ /// Sets status bar text.
+ virtual void SetHTMLStatusText(const wxString& text) = 0;
+
+ /// Type of mouse cursor
+ enum HTMLCursor
+ {
+ /// Standard mouse cursor (typically an arrow)
+ HTMLCursor_Default,
+ /// Cursor shown over links
+ HTMLCursor_Link,
+ /// Cursor shown over selectable text
+ HTMLCursor_Text
+ };
+
+ /**
+ Returns mouse cursor of given @a type.
+ */
+ virtual wxCursor GetHTMLCursor(wxHtmlWindowInterface::HTMLCursor type) const = 0;
+};
+
+
+
/**
@class wxHtmlWindow
wxHtmlWindow is probably the only class you will directly use unless you want
to do something special (like adding new tag handlers or MIME filters).
- The purpose of this class is to display HTML pages (either local file or
- downloaded via HTTP protocol) in a window.
+ The purpose of this class is to display rich content pages (either local file or
+ downloaded via HTTP protocol) in a window based on a subset of the HTML standard.
The width of the window is constant - given in the constructor - and virtual height
is changed dynamically depending on page size.
- Once the window is created you can set its content by calling SetPage(text),
- LoadPage(filename) or wxHtmlWindow::LoadFile.
+ Once the window is created you can set its content by calling SetPage() with raw HTML,
+ LoadPage() with a wxFileSystem location or LoadFile() with a filename.
+
+ @note
+ If you want complete HTML/CSS support as well as a Javascript engine, see instead
+ wxWebView.
@note
- wxHtmlWindow uses the wxImage class for displaying images.
- Don't forget to initialize all image formats you need before loading any page!
- (See ::wxInitAllImageHandlers and wxImage::AddHandler.)
+ wxHtmlWindow uses the wxImage class for displaying images, as such you need to
+ initialize the handlers for any image formats you use before loading a page.
+ See ::wxInitAllImageHandlers and wxImage::AddHandler.
@beginStyleTable
@style{wxHW_SCROLLBAR_NEVER}
@endStyleTable
- @beginEventTable{wxHtmlCellEvent, wxHtmlLinkEvent}
+ @beginEventEmissionTable{wxHtmlCellEvent, wxHtmlLinkEvent}
@event{EVT_HTML_CELL_CLICKED(id, func)}
A wxHtmlCell was clicked.
@event{EVT_HTML_CELL_HOVER(id, func)}
@see wxHtmlLinkEvent, wxHtmlCellEvent
*/
-class wxHtmlWindow : public wxScrolledWindow
+class wxHtmlWindow : public wxScrolledWindow, public wxHtmlWindowInterface
{
public:
/**
- @c image/* MIME types
- Plain Text filter (this filter is used if no other filter matches)
*/
- static void AddFilter(wxHtmlFilter filter);
+ static void AddFilter(wxHtmlFilter* filter);
/**
Appends HTML fragment to currently displayed text and refreshes the window.
wxString GetOpenedPage() const;
/**
- Returns title of the opened page or wxEmptyString if current page does not
+ Returns title of the opened page or wxEmptyString if the current page does not
contain \<TITLE\> tag.
*/
wxString GetOpenedPageTitle() const;
wxFrame* GetRelatedFrame() const;
/**
- Moves back to the previous page.
- (each page displayed using LoadPage() is stored in history list.)
+ Moves back to the previous page. Only pages displayed using LoadPage()
+ are stored in history list.
*/
bool HistoryBack();
/**
Returns @true if it is possible to go back in the history
- (i.e. HistoryBack() won't fail).
+ i.e. HistoryBack() won't fail.
*/
bool HistoryCanBack();
/**
Returns @true if it is possible to go forward in the history
- (i.e. HistoryBack() won't fail).
+ i.e. HistoryForward() won't fail.
*/
bool HistoryCanForward();
void HistoryClear();
/**
- Moves to next page in history.
+ Moves to next page in history. Only pages displayed using LoadPage()
+ are stored in history list.
*/
bool HistoryForward();
/**
- Loads HTML page from file and displays it.
+ Loads an HTML page from a file and displays it.
@return @false if an error occurred, @true otherwise
bool LoadFile(const wxFileName& filename);
/**
- Unlike SetPage() this function first loads HTML page from @a location
- and then displays it. See example:
+ Unlike SetPage() this function first loads the HTML page from @a location
+ and then displays it.
@param location
- The address of document.
- See wxFileSystem for details on address format and behaviour of "opener".
+ The address of the document.
+ See the @ref overview_fs for details on the address format
+ and wxFileSystem for a description of how the file is opened.
@return @false if an error occurred, @true otherwise
void SelectWord(const wxPoint& pos);
/**
- Returns current selection as plain text.
- Returns empty string if no text is currently selected.
+ Returns the current selection as plain text.
+ Returns an empty string if no text is currently selected.
*/
wxString SelectionToText();
/**
This function sets the space between border of window and HTML contents.
See image:
- @image html border.png
+ @image html htmlwin_border.png
@param b
indentation from borders in pixels
void SetBorders(int b);
/**
- This function sets font sizes and faces.
+ This function sets font sizes and faces. See wxHtmlDCRenderer::SetFonts
+ for detailed description.
- @param normal_face
- This is face name for normal (i.e. non-fixed) font.
- It can be either empty string (then the default face is chosen) or
- platform-specific face name. Examples are "helvetica" under Unix or
- "Times New Roman" under Windows.
- @param fixed_face
- The same thing for fixed face ( \<TT\>..\</TT\> )
- @param sizes
- This is an array of 7 items of int type.
- The values represent size of font with HTML size from -2 to +4
- ( \<FONT SIZE=-2\> to \<FONT SIZE=+4\> ).
- Default sizes are used if sizes is @NULL.
-
- Default font sizes are defined by constants wxHTML_FONT_SIZE_1,
- wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7.
- Note that they differ among platforms. Default face names are empty strings.
+ @see SetSize()
*/
void SetFonts(const wxString& normal_face, const wxString& fixed_face,
const int* sizes = NULL);
/**
- Sets HTML page and display it. This won't @b load the page!!
- It will display the @e source. See example:
+ Sets default font sizes and/or default font size.
+ See wxHtmlDCRenderer::SetStandardFonts for detailed description.
+ @see SetFonts()
+ */
+ void SetStandardFonts(int size = -1,
+ const wxString& normal_face = wxEmptyString,
+ const wxString& fixed_face = wxEmptyString);
+
+ /**
+ Sets the source of a page and displays it, for example:
@code
htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
@endcode
If you want to load a document from some location use LoadPage() instead.
@param source
- The HTML document source to be displayed.
+ The HTML to be displayed.
@return @false if an error occurred, @true otherwise.
*/
*/
virtual void WriteCustomization(wxConfigBase* cfg,
wxString path = wxEmptyString);
-
+
protected:
/**
+wxEventType wxEVT_HTML_CELL_CLICKED;
+wxEventType wxEVT_HTML_CELL_HOVER;
+wxEventType wxEVT_HTML_LINK_CLICKED;
+
+
/**
@class wxHtmlLinkEvent
projects / wxWidgets.git / blobdiff