#include <wx/html/htmlwin.h>

Inheritance diagram for wxHtmlWindow:

Detailed Description

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 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() 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, consider using wxWebView instead.

wxHtmlWindow uses the wxImage class for displaying images, so you need to initialize the handlers for any image formats you use before loading a page. See wxInitAllImageHandlers and wxImage::AddHandler.

Styles

This class supports the following styles:

wxHW_SCROLLBAR_NEVER:
Never display scrollbars, not even when the page is larger than the window.
wxHW_SCROLLBAR_AUTO:
Display scrollbars only if page's size exceeds window's size.
wxHW_NO_SELECTION:
Don't allow the user to select text.

Events emitted by this class

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxHtmlCellEvent& event) or void handlerFuncName( wxHtmlLinkEvent& event)

Event macros for events emitted by this class:

EVT_HTML_CELL_CLICKED(id, func):
A wxHtmlCell was clicked.
EVT_HTML_CELL_HOVER(id, func):
The mouse passed over a wxHtmlCell.
EVT_HTML_LINK_CLICKED(id, func):
A wxHtmlCell which contains an hyperlink was clicked.

Library: wxHTML

Category: HTML

See also: wxHtmlLinkEvent, wxHtmlCellEvent

Public Member Functions
	wxHtmlWindow ()
	Default ctor. More...

	wxHtmlWindow (wxWindow *parent, wxWindowID id=wxID_ANY, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxHW_DEFAULT_STYLE, const wxString &name="htmlWindow")
	Constructor. More...

bool	AppendToPage (const wxString &source)
	Appends HTML fragment to currently displayed text and refreshes the window. More...

wxHtmlContainerCell *	GetInternalRepresentation () const
	Returns pointer to the top-level container. More...

wxString	GetOpenedAnchor () const
	Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage). More...

wxString	GetOpenedPage () const
	Returns full location of the opened page. More...

wxString	GetOpenedPageTitle () const
	Returns title of the opened page or wxEmptyString if the current page does not contain <TITLE> tag. More...

wxFrame *	GetRelatedFrame () const
	Returns the related frame. More...

bool	HistoryBack ()
	Moves back to the previous page. More...

bool	HistoryCanBack ()
	Returns true if it is possible to go back in the history i.e. More...

bool	HistoryCanForward ()
	Returns true if it is possible to go forward in the history i.e. More...

void	HistoryClear ()
	Clears history. More...

bool	HistoryForward ()
	Moves to next page in history. More...

bool	LoadFile (const wxFileName &filename)
	Loads an HTML page from a file and displays it. More...

virtual bool	LoadPage (const wxString &location)
	Unlike SetPage() this function first loads the HTML page from location and then displays it. More...

virtual void	OnLinkClicked (const wxHtmlLinkInfo &link)
	Called when user clicks on hypertext link. More...

virtual wxHtmlOpeningStatus	OnOpeningURL (wxHtmlURLType type, const wxString &url, wxString *redirect) const
	Called when an URL is being opened (either when the user clicks on a link or an image is loaded). More...

virtual void	OnSetTitle (const wxString &title)
	Called on parsing <TITLE> tag. More...

virtual void	ReadCustomization (wxConfigBase *cfg, wxString path=wxEmptyString)
	This reads custom settings from wxConfig. More...

void	SelectAll ()
	Selects all text in the window. More...

void	SelectLine (const wxPoint &pos)
	Selects the line of text that pos points at. More...

void	SelectWord (const wxPoint &pos)
	Selects the word at position pos. More...

wxString	SelectionToText ()
	Returns the current selection as plain text. More...

void	SetBorders (int b)
	This function sets the space between border of window and HTML contents. More...

void	SetFonts (const wxString &normal_face, const wxString &fixed_face, const int *sizes=NULL)
	This function sets font sizes and faces. More...

void	SetStandardFonts (int size=-1, const wxString &normal_face=wxEmptyString, const wxString &fixed_face=wxEmptyString)
	Sets default font sizes and/or default font size. More...

virtual bool	SetPage (const wxString &source)
	Sets the source of a page and displays it, for example: More...

void	SetRelatedFrame (wxFrame *frame, const wxString &format)
	Sets the frame in which page title will be displayed. More...

void	SetRelatedStatusBar (int index)
	After calling SetRelatedFrame(), this sets statusbar slot where messages will be displayed. More...

void	SetRelatedStatusBar (wxStatusBar *statusbar, int index=0)
	Sets the associated statusbar where messages will be displayed. More...

wxString	ToText ()
	Returns content of currently displayed page as plain text. More...

virtual void	WriteCustomization (wxConfigBase *cfg, wxString path=wxEmptyString)
	Saves custom settings into wxConfig. More...

Public Member Functions inherited from wxScrolled< T >
	wxScrolled ()
	Default constructor. More...

	wxScrolled (wxWindow *parent, wxWindowID id=-1, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxHSCROLL\|wxVSCROLL, const wxString &name="scrolledWindow")
	Constructor. More...

void	CalcScrolledPosition (int x, int y, int xx, int yy) const
	Translates the logical coordinates to the device ones. More...

wxPoint	CalcScrolledPosition (const wxPoint &pt) const

void	CalcUnscrolledPosition (int x, int y, int xx, int yy) const
	Translates the device coordinates to the logical ones. More...

wxPoint	CalcUnscrolledPosition (const wxPoint &pt) const

bool	Create (wxWindow *parent, wxWindowID id=-1, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxHSCROLL\|wxVSCROLL, const wxString &name="scrolledWindow")
	Creates the window for two-step construction. More...

void	DisableKeyboardScrolling ()
	Disable use of keyboard keys for scrolling. More...

void	DoPrepareDC (wxDC &dc)
	Call this function to prepare the device context for drawing a scrolled image. More...

void	EnableScrolling (bool xScrolling, bool yScrolling)
	Enable or disable use of wxWindow::ScrollWindow() for scrolling. More...

void	ShowScrollbars (wxScrollbarVisibility horz, wxScrollbarVisibility vert)
	Set the scrollbar visibility. More...

void	GetScrollPixelsPerUnit (int xUnit, int yUnit) const
	Get the number of pixels per scroll unit (line), in each direction, as set by SetScrollbars(). More...

void	GetViewStart (int x, int y) const
	Get the position at which the visible portion of the window starts. More...

wxPoint	GetViewStart () const
	This is a simple overload of GetViewStart(int,int); see that function for more info. More...

void	GetVirtualSize (int x, int y) const
	Gets the size in device units of the scrollable window area (as opposed to the client size, which is the area of the window currently visible). More...

bool	IsRetained () const
	Motif only: true if the window has a backing bitmap. More...

virtual void	OnDraw (wxDC &dc)
	Called by the default paint event handler to allow the application to define painting behaviour without having to worry about calling DoPrepareDC(). More...

void	PrepareDC (wxDC &dc)
	This function is for backwards compatibility only and simply calls DoPrepareDC() now. More...

void	Scroll (int x, int y)
	Scrolls a window so the view start is at the given point. More...

void	Scroll (const wxPoint &pt)
	This is an overload of Scroll(int,int); see that function for more info. More...

void	SetScrollRate (int xstep, int ystep)
	Set the horizontal and vertical scrolling increment only. More...

void	SetScrollbars (int pixelsPerUnitX, int pixelsPerUnitY, int noUnitsX, int noUnitsY, int xPos=0, int yPos=0, bool noRefresh=false)
	Sets up vertical and/or horizontal scrollbars. More...

void	SetTargetWindow (wxWindow *window)
	Call this function to tell wxScrolled to perform the actual scrolling on a different window (and not on itself). More...

wxWindow *	GetTargetWindow () const

void	SetTargetRect (const wxRect &rect)

wxRect	GetTargetRect () const

int	GetScrollPageSize (int orient) const

void	SetScrollPageSize (int orient, int pageSize)

int	GetScrollLines (int orient) const

void	SetScale (double xs, double ys)

double	GetScaleX () const

double	GetScaleY () const

virtual void	AdjustScrollbars ()

bool	IsAutoScrolling () const
	Are we generating the autoscroll events? More...

void	StopAutoScrolling ()
	Stop generating the scroll events when mouse is held outside the window. More...

virtual bool	SendAutoScrollEvents (wxScrollWinEvent &event) const
	This method can be overridden in a derived class to forbid sending the auto scroll events - note that unlike StopAutoScrolling() it doesn't stop the timer, so it will be called repeatedly and will typically return different values depending on the current mouse position. More...

Public Member Functions inherited from wxHtmlWindowInterface
	wxHtmlWindowInterface ()
	Ctor. More...

virtual	~wxHtmlWindowInterface ()

virtual void	SetHTMLWindowTitle (const wxString &title)=0
	Called by the parser to set window's title to given text. More...

virtual void	OnHTMLLinkClicked (const wxHtmlLinkInfo &link)=0
	Called when a link is clicked. More...

virtual wxHtmlOpeningStatus	OnHTMLOpeningURL (wxHtmlURLType type, const wxString &url, wxString *redirect) const =0
	Called when the parser needs to open another URL (e.g. More...

virtual wxPoint	HTMLCoordsToWindow (wxHtmlCell *cell, const wxPoint &pos) const =0
	Converts coordinates pos relative to given cell to physical coordinates in the window. More...

virtual wxWindow *	GetHTMLWindow ()=0
	Returns the window used for rendering (may be NULL). More...

virtual wxColour	GetHTMLBackgroundColour () const =0
	Returns background colour to use by default. More...

virtual void	SetHTMLBackgroundColour (const wxColour &clr)=0
	Sets window's background to colour clr. More...

virtual void	SetHTMLBackgroundImage (const wxBitmap &bmpBg)=0
	Sets window's background to given bitmap. More...

virtual void	SetHTMLStatusText (const wxString &text)=0
	Sets status bar text. More...

virtual wxCursor	GetHTMLCursor (wxHtmlWindowInterface::HTMLCursor type) const =0
	Returns mouse cursor of given type. More...

Static Public Member Functions
static void	AddFilter (wxHtmlFilter *filter)
	Adds an input filter to the static list of available filters. More...

static wxCursor	GetDefaultHTMLCursor (HTMLCursor type)
	Retrieves the default cursor for a given HTMLCursor type. More...

static void	SetDefaultHTMLCursor (HTMLCursor type, const wxCursor &cursor)
	Sets the default cursor for a given HTMLCursor type. More...

Protected Member Functions
virtual bool	OnCellClicked (wxHtmlCell *cell, wxCoord x, wxCoord y, const wxMouseEvent &event)
	This method is called when a mouse button is clicked inside wxHtmlWindow. More...

virtual void	OnCellMouseHover (wxHtmlCell *cell, wxCoord x, wxCoord y)
	This method is called when a mouse moves over an HTML cell. More...

Protected Member Functions inherited from wxScrolled< T >
virtual wxSize	GetSizeAvailableForScrollTarget (const wxSize &size)
	Function which must be overridden to implement the size available for the scroll target for the given size of the main window. More...

Additional Inherited Members
Public Types inherited from wxHtmlWindowInterface
enum	HTMLCursor { HTMLCursor_Default, HTMLCursor_Link, HTMLCursor_Text }
	Type of mouse cursor. More...

Constructor & Destructor Documentation

wxHtmlWindow::wxHtmlWindow ( )

Default ctor.

wxHtmlWindow::wxHtmlWindow	(	wxWindow *	parent,
		wxWindowID	id = `wxID_ANY`,
		const wxPoint &	pos = `wxDefaultPosition`,
		const wxSize &	size = `wxDefaultSize`,
		long	style = `wxHW_DEFAULT_STYLE`,
		const wxString &	name = `"htmlWindow"`
	)

Constructor.

The parameters are the same as wxScrolled::wxScrolled() constructor.

Member Function Documentation

static void wxHtmlWindow::AddFilter ( wxHtmlFilter * filter )

static

Adds an input filter to the static list of available filters.

These filters are present by default:

text/html
text/plain
image/*

The plain text filter will be used if no other filter matches.

bool wxHtmlWindow::AppendToPage ( const wxString & source )

Appends HTML fragment to currently displayed text and refreshes the window.

Parameters

source HTML code fragment

Returns: false if an error occurred, true otherwise.

static wxCursor wxHtmlWindow::GetDefaultHTMLCursor ( HTMLCursor type )

static

Retrieves the default cursor for a given HTMLCursor type.

Parameters

type	HTMLCursor type to retrieve.

Since: 3.1.0

wxHtmlContainerCell* wxHtmlWindow::GetInternalRepresentation ( ) const

Returns pointer to the top-level container.

See also: Cells and Containers, Printing Framework Overview

wxString wxHtmlWindow::GetOpenedAnchor ( ) const

Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage).

If no page is opened or if the displayed page wasn't produced by call to LoadPage(), empty string is returned.

wxString wxHtmlWindow::GetOpenedPage ( ) const

Returns full location of the opened page.

If no page is opened or if the displayed page wasn't produced by call to LoadPage(), empty string is returned.

wxString wxHtmlWindow::GetOpenedPageTitle ( ) const

Returns title of the opened page or wxEmptyString if the current page does not contain <TITLE> tag.

wxFrame* wxHtmlWindow::GetRelatedFrame ( ) const

Returns the related frame.

bool wxHtmlWindow::HistoryBack ( )

Moves back to the previous page.

Only pages displayed using LoadPage() are stored in history list.

bool wxHtmlWindow::HistoryCanBack ( )

Returns true if it is possible to go back in the history i.e.

HistoryBack() won't fail.

bool wxHtmlWindow::HistoryCanForward ( )

Returns true if it is possible to go forward in the history i.e.

HistoryForward() won't fail.

void wxHtmlWindow::HistoryClear ( )

Clears history.

bool wxHtmlWindow::HistoryForward ( )

Moves to next page in history.

Only pages displayed using LoadPage() are stored in history list.

bool wxHtmlWindow::LoadFile ( const wxFileName & filename )

Loads an HTML page from a file and displays it.

Returns: false if an error occurred, true otherwise

See also: LoadPage()

virtual bool wxHtmlWindow::LoadPage ( const wxString & location )

virtual

Unlike SetPage() this function first loads the HTML page from location and then displays it.

Parameters

location The address of the document. See the wxFileSystem Overview for details on the address format and wxFileSystem for a description of how the file is opened.

Returns: false if an error occurred, true otherwise

See also: LoadFile()

virtual bool wxHtmlWindow::OnCellClicked	(	wxHtmlCell *	cell,
		wxCoord	x,
		wxCoord	y,
		const wxMouseEvent &	event
	)

protectedvirtual

This method is called when a mouse button is clicked inside wxHtmlWindow.

The default behaviour is to emit a wxHtmlCellEvent and, if the event was not processed or skipped, call OnLinkClicked() if the cell contains an hypertext link.

Overloading this method is deprecated; intercept the event instead.

Parameters

cell	The cell inside which the mouse was clicked, always a simple (i.e. non-container) cell
x	The logical x coordinate of the click point
y	The logical y coordinate of the click point
event	The mouse event containing other information about the click

Returns: true if a link was clicked, false otherwise.

virtual void wxHtmlWindow::OnCellMouseHover	(	wxHtmlCell *	cell,
		wxCoord	x,
		wxCoord	y
	)

protectedvirtual

This method is called when a mouse moves over an HTML cell.

Default behaviour is to emit a wxHtmlCellEvent.

Overloading this method is deprecated; intercept the event instead.

Parameters

cell	The cell inside which the mouse is currently, always a simple (i.e. non-container) cell
x	The logical x coordinate of the click point
y	The logical y coordinate of the click point

virtual void wxHtmlWindow::OnLinkClicked ( const wxHtmlLinkInfo & link )

virtual

Called when user clicks on hypertext link.

Default behaviour is to emit a wxHtmlLinkEvent and, if the event was not processed or skipped, call LoadPage() and do nothing else.

Overloading this method is deprecated; intercept the event instead.

Also see wxHtmlLinkInfo.

virtual wxHtmlOpeningStatus wxHtmlWindow::OnOpeningURL	(	wxHtmlURLType	type,
		const wxString &	url,
		wxString *	redirect
	)		const

virtual

Called when an URL is being opened (either when the user clicks on a link or an image is loaded).

The URL will be opened only if OnOpeningURL() returns wxHTML_OPEN. This method is called by wxHtmlParser::OpenURL.

You can override OnOpeningURL() to selectively block some URLs (e.g. for security reasons) or to redirect them elsewhere. Default behaviour is to always return wxHTML_OPEN.

Parameters

type	Indicates type of the resource. Is one of wxHTML_URL_PAGE: Opening a HTML page. wxHTML_URL_IMAGE: Opening an image. wxHTML_URL_OTHER: Opening a resource that doesn't fall into any other category.
url	URL being opened.
redirect	Pointer to wxString variable that must be filled with an URL if OnOpeningURL() returns `wxHTML_REDIRECT`.

The return value is:

wxHTML_OPEN: Open the URL.
wxHTML_BLOCK: Deny access to the URL, wxHtmlParser::OpenURL will return NULL.
wxHTML_REDIRECT: Don't open url, redirect to another URL. OnOpeningURL() must fill *redirect with the new URL. OnOpeningURL() will be called again on returned URL.

virtual void wxHtmlWindow::OnSetTitle ( const wxString & title )

virtual

Called on parsing <TITLE> tag.

virtual void wxHtmlWindow::ReadCustomization	(	wxConfigBase *	cfg,
		wxString	path = `wxEmptyString`
	)

virtual

This reads custom settings from wxConfig.

It uses the path 'path' if given, otherwise it saves info into currently selected path. The values are stored in sub-path wxHtmlWindow. Read values: all things set by SetFonts(), SetBorders().

Parameters

cfg	wxConfig from which you want to read the configuration.
path	Optional path in config tree. If not given current path is used.

void wxHtmlWindow::SelectAll ( )

Selects all text in the window.

See also: SelectLine(), SelectWord()

wxString wxHtmlWindow::SelectionToText ( )

Returns the current selection as plain text.

Returns an empty string if no text is currently selected.

void wxHtmlWindow::SelectLine ( const wxPoint & pos )

Selects the line of text that pos points at.

Note that pos is relative to the top of displayed page, not to window's origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate.

See also: SelectAll(), SelectWord()

void wxHtmlWindow::SelectWord ( const wxPoint & pos )

Selects the word at position pos.

Note that pos is relative to the top of displayed page, not to window's origin, use wxScrolled::CalcUnscrolledPosition() to convert physical coordinate.

See also: SelectAll(), SelectLine()

void wxHtmlWindow::SetBorders ( int b )

This function sets the space between border of window and HTML contents.

See image:

Parameters

b	indentation from borders in pixels

static void wxHtmlWindow::SetDefaultHTMLCursor	(	HTMLCursor	type,
		const wxCursor &	cursor
	)

static

Sets the default cursor for a given HTMLCursor type.

These cursors are used for all wxHtmlWindow objects by default, but can be overridden on a per-window basis.

Parameters

type	HTMLCursor type to retrieve.
cursor	The default cursor for the specified cursor type.

Since: 3.1.0

void wxHtmlWindow::SetFonts	(	const wxString &	normal_face,
		const wxString &	fixed_face,
		const int *	sizes = `NULL`
	)

This function sets font sizes and faces.

See wxHtmlDCRenderer::SetFonts for detailed description.

See also: SetSize()

virtual bool wxHtmlWindow::SetPage ( const wxString & source )

virtual

Sets the source of a page and displays it, for example:

htmlwin -> SetPage("<html><body>Hello, world!</body></html>");

If you want to load a document from some location use LoadPage() instead.

Parameters

source The HTML to be displayed.

Returns: false if an error occurred, true otherwise.

void wxHtmlWindow::SetRelatedFrame	(	wxFrame *	frame,
		const wxString &	format
	)

Sets the frame in which page title will be displayed.

format is the format of the frame title, e.g. "HtmlHelp : %s". It must contain exactly one s. This s is substituted with HTML page title.

void wxHtmlWindow::SetRelatedStatusBar ( int index )

After calling SetRelatedFrame(), this sets statusbar slot where messages will be displayed.

(Default is -1 = no messages.)

Parameters

index Statusbar slot number (0..n)

void wxHtmlWindow::SetRelatedStatusBar	(	wxStatusBar *	statusbar,
		int	index = `0`
	)

Sets the associated statusbar where messages will be displayed.

Call this instead of SetRelatedFrame() if you want statusbar updates only, no changing of the frame title.

Parameters

statusbar	Statusbar pointer
index	Statusbar slot number (0..n)

Since: 2.9.0

void wxHtmlWindow::SetStandardFonts	(	int	size = `-1`,
		const wxString &	normal_face = `wxEmptyString`,
		const wxString &	fixed_face = `wxEmptyString`
	)

Sets default font sizes and/or default font size.

See wxHtmlDCRenderer::SetStandardFonts for detailed description.

See also: SetFonts()

wxString wxHtmlWindow::ToText ( )

Returns content of currently displayed page as plain text.

virtual void wxHtmlWindow::WriteCustomization	(	wxConfigBase *	cfg,
		wxString	path = `wxEmptyString`
	)

virtual

Saves custom settings into wxConfig.

It uses the path 'path' if given, otherwise it saves info into currently selected path. Regardless of whether the path is given or not, the function creates sub-path wxHtmlWindow.

Saved values: all things set by SetFonts(), SetBorders().

Parameters

cfg	wxConfig to which you want to save the configuration.
path	Optional path in config tree. If not given, the current path is used.

Detailed Description

Styles

Events emitted by this class

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation