# wxHtmlWindow Class Reference
[HTML]

`#include </home/work/projects/wx/2.9/wx/interface/wx/html/htmlwin.h>`

Inheritance diagram for wxHtmlWindow:
[legend]

## 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 HTML pages (either local file or downloaded via HTTP protocol) in a window. 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:
  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.

## 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.
| 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.
bool | AppendToPage (const wxString &source)
| Appends HTML fragment to currently displayed text and refreshes the window.
wxHtmlContainerCell * | GetInternalRepresentation () const
| Returns pointer to the top-level container.
wxString | GetOpenedAnchor () const
| Returns anchor within currently opened page (see wxHtmlWindow::GetOpenedPage).
wxString | GetOpenedPage () const
| Returns full location of the opened page.
wxString | GetOpenedPageTitle () const
| Returns title of the opened page or wxEmptyString if the current page does not contain <TITLE> tag.
wxFrame * | GetRelatedFrame () const
| Returns the related frame.
bool | HistoryBack ()
| Moves back to the previous page.
bool | HistoryCanBack ()
| Returns true if it is possible to go back in the history i.e.
bool | HistoryCanForward ()
| Returns true if it is possible to go forward in the history i.e.
void | HistoryClear ()
| Clears history.
bool | HistoryForward ()
| Moves to next page in history.
bool | LoadFile (const wxFileName &filename)
| Loads an HTML page from a file and displays it.
virtual bool | LoadPage (const wxString &location)
| Unlike SetPage() this function first loads the HTML page from location and then displays it.
virtual void | OnLinkClicked (const wxHtmlLinkInfo &link)
| Called when user clicks on hypertext link.
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).
virtual void | OnSetTitle (const wxString &title)
| Called on parsing <TITLE> tag.
virtual void | ReadCustomization (wxConfigBase *cfg, wxString path=wxEmptyString)
| This reads custom settings from wxConfig.
void | SelectAll ()
| Selects all text in the window.
void | SelectLine (const wxPoint &pos)
| Selects the line of text that pos points at.
void | SelectWord (const wxPoint &pos)
| Selects the word at position pos.
wxString | SelectionToText ()
| Returns the current selection as plain text.
void | SetBorders (int b)
| This function sets the space between border of window and HTML contents.
void | SetFonts (const wxString &normal_face, const wxString &fixed_face, const int *sizes=NULL)
| This function sets font sizes and faces.
void | SetStandardFonts (int size=-1, const wxString &normal_face=wxEmptyString, const wxString &fixed_face=wxEmptyString)
| Sets default font sizes and/or default font size.
virtual bool | SetPage (const wxString &source)
| Sets the source of a page and displays it, for example:
void | SetRelatedFrame (wxFrame *frame, const wxString &format)
| Sets the frame in which page title will be displayed.
void | SetRelatedStatusBar (int index)
| After calling SetRelatedFrame(), this sets statusbar slot where messages will be displayed.
void | SetRelatedStatusBar (wxStatusBar *statusbar, int index=0)
| Sets the associated statusbar where messages will be displayed.
wxString | ToText ()
| Returns content of currently displayed page as plain text.
virtual void | WriteCustomization (wxConfigBase *cfg, wxString path=wxEmptyString)
| Saves custom settings into wxConfig.

## Static Public Member Functions

static void | AddFilter (wxHtmlFilter *filter)
| Adds input filter to the static list of available filters.

## 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.
virtual void | OnCellMouseHover (wxHtmlCell *cell, wxCoord x, wxCoord y)
| This method is called when a mouse moves over an HTML cell.

List of all members.

## 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 input filter to the static list of available filters.

These filters are present by default:

- `text/html` MIME type
- `image/*` MIME types
- Plain Text filter (this filter is 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.

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 |
| ) |  |  | `[protected, virtual]`

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 |
| ) |  |  | `[protected, virtual]`

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

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.

|  | [ top ]