******************
wx.html.HtmlWindow
******************

Inheritance diagram for `wx.html.HtmlWindow`:

|

.. inheritance-diagram:: wx.html.HtmlWindow

|

Description
===========

`wx.html.HtmlWindow` 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 <#SetPage>`_, `LoadPage <#LoadPage>`_ or `LoadFile <#LoadFile>`_.


Derived From
^^^^^^^^^^^^^

* `wx.ScrolledWindow <../Widgets/wx.ScrolledWindow.html>`_ 


Window Styles
^^^^^^^^^^^^^

==================================================  ==================================================  
Window Style                                        Description
==================================================  ==================================================  
``wx.html.HW_SCROLLBAR_NEVER``                      Never display scrollbars, not even when the page is larger than the window.
``wx.html.HW_SCROLLBAR_AUTO``                       Display scrollbars only if page's size exceeds window's size.
``wx.html.HW_NO_SELECTION``                         Don't allow the user to select text.
==================================================  ==================================================  

Event Handling
^^^^^^^^^^^^^^

==================================================  ==================================================  
Event Name                                          Description
==================================================  ==================================================  
wx.html.EVT_HTML_CELL_CLICKED(id, func)             A `wx.html.HtmlCell <wx.html.HtmlCell.html>`_ was clicked.
wx.html.EVT_HTML_CELL_HOVER(id, func)               The mouse passed over a `wx.html.HtmlCell`.
wx.html.EVT_HTML_LINK_CLICKED(id, func)             A `wx.html.HtmlCell` which contains an hyperlink was clicked.
==================================================  ==================================================  

Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `AddFilter <#AddFilter>`_ 
* `AppendToPage <#AppendToPage>`_ 
* `GetDefaultHTMLCursor <#GetDefaultHTMLCursor>`_ 
* `GetInternalRepresentation <#GetInternalRepresentation>`_ 
* `GetOpenedAnchor <#GetOpenedAnchor>`_ 
* `GetOpenedPage <#GetOpenedPage>`_ 
* `GetOpenedPageTitle <#GetOpenedPageTitle>`_ 
* `GetParser <#GetParser>`_ 
* `GetRelatedFrame <#GetRelatedFrame>`_ 
* `HasAnchor <#HasAnchor>`_ 
* `HistoryBack <#HistoryBack>`_ 
* `HistoryCanBack <#HistoryCanBack>`_ 
* `HistoryCanForward <#HistoryCanForward>`_ 
* `HistoryClear <#HistoryClear>`_ 
* `HistoryForward <#HistoryForward>`_ 
* `LoadFile <#LoadFile>`_ 
* `LoadPage <#LoadPage>`_ 
* `OnCellClicked <#OnCellClicked>`_ 
* `OnCellMouseHover <#OnCellMouseHover>`_ 
* `OnLinkClicked <#OnLinkClicked>`_ 
* `OnOpeningURL <#OnOpeningURL>`_ 
* `OnSetTitle <#OnSetTitle>`_ 
* `ReadCustomization <#ReadCustomization>`_ 
* `ScrollToAnchor <#ScrollToAnchor>`_ 
* `SelectAll <#SelectAll>`_ 
* `SelectLine <#SelectLine>`_ 
* `SelectWord <#SelectWord>`_ 
* `SelectionToText <#SelectionToText>`_ 
* `SetBackgroundImage <#SetBackgroundImage>`_ 
* `SetBorders <#SetBorders>`_ 
* `SetFonts <#SetFonts>`_ 
* `SetPage <#SetPage>`_ 
* `SetRelatedFrame <#SetRelatedFrame>`_ 
* `SetRelatedStatusBar <#SetRelatedStatusBar>`_ 
* `SetStandardFonts <#SetStandardFonts>`_ 
* `ToText <#ToText>`_ 
* `WriteCustomization <#WriteCustomization>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `InternalRepresentation <#InternalRepresentation>`_ 
* `OpenedAnchor <#OpenedAnchor>`_ 
* `OpenedPage <#OpenedPage>`_ 
* `OpenedPageTitle <#OpenedPageTitle>`_ 
* `Parser <#Parser>`_ 
* `RelatedFrame <#RelatedFrame>`_ 

Class API
=========

Methods
^^^^^^^


.. method:: __init__(parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.html.HW_DEFAULT_STYLE, name="htmlWindow")

   Constructor. All the parameters are the same as `wx.ScrolledWindow <../Widgets/wx.ScrolledWindow.html>`_ constructor, except `style`.

   For `style`, see `Window Styles`_.

   **Parameters:**

   * `parent` (`wx.Window <../Widgets/wx.Window.html>`_)
   * `id` (int)
   * `pos` (`wx.Point <../Widgets/wx.Point.html>`_)
   * `size` (`wx.Size <../Widgets/wx.Size.html>`_)
   * `style` (int)
   * `name` (string)

   |

   **Returns:**

   `wx.html.HtmlWindow <wx.html.HtmlWindow.html>`_ 

--------

.. method:: AddFilter(filter)

   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)

   |

   **Parameters:**

   * `filter` (`wx.html.HtmlFilter <wx.html.HtmlFilter.html>`_) 

--------

.. method:: AppendToPage(source)

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

   Returns ``False`` if an error occurred, ``True`` otherwise.

   **Parameters:**

   * `source` (string): HTML code fragment.

   |  

   **Returns:**

   `bool` 

--------

.. method:: GetDefaultHTMLCursor(type)

   |
   
   **Parameters:**

   * `type` (int)

   |

   **Returns:**

   `wx.Cursor <../Widgets/wx.Cursor.html>`_
 

--------

.. method:: GetInternalRepresentation()

   Returns pointer to the top-level container.

   |  

   **Returns:**

   `wx.html.HtmlContainerCell <wx.html.HtmlContainerCell.html>`_
 

--------

.. method:: GetOpenedAnchor()

   Returns anchor within currently opened page (see `GetOpenedPage <#GetOpenedPage>`_).  

   If no page is opened or if the displayed page wasn't produced by call to `LoadPage <#LoadPage>`_, empty string is returned.

   |  

   **Returns:**

   `string` 

--------

.. method:: GetOpenedPage()

   Returns full location of the opened page.

   If no page is opened or if the displayed page wasn't produced by call to `LoadPage <#LoadPage>`_, empty string is returned.

   |  

   **Returns:**

   `string` 

--------

.. method:: GetOpenedPageTitle()

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

   |  

   **Returns:**

   `string` 

--------

.. method:: GetParser()

   `No docstrings available for this method.` 

--------


.. method:: GetRelatedFrame()

   Returns the related frame.

   |  

   **Returns:**

   `wx.Frame <../Widgets/wx.Frame.html>`_
 

--------

.. method:: HasAnchor(anchor)

   |
   
   **Parameters:**

   * `anchor` (string)

   |

   **Returns:**

   `bool` 

--------

.. method:: HistoryBack()

   Moves back to the previous page. 

   Each page displayed using `LoadPage <#LoadPage>`_ is stored in history list.

   |  

   **Returns:**

   `bool` 

--------

.. method:: HistoryCanBack()

   Returns ``True`` if it is possible to go back in the history (i.e. `HistoryBack <#HistoryBack>`_ won't fail).

   |  

   **Returns:**

   `bool` 

--------

.. method:: HistoryCanForward()

   Returns ``True`` if it is possible to go forward in the history (i.e. `HistoryForward <#HistoryForward>`_ won't fail).

   |  

   **Returns:**

   `bool` 

--------

.. method:: HistoryClear()

   Clears history.


--------

.. method:: HistoryForward()

   Moves to next page in history.

   |  

   **Returns:**

   `bool` 

--------

.. method:: LoadFile(filename)

   Loads HTML page from file and displays it.

   Returns ``False`` if an error occurred, ``True`` otherwise.

   **Parameters:**

   * `filename` (string) 

   |  

   **Returns:**

   `bool` 

.. seealso:: `LoadPage <#LoadPage>`_
  

--------

.. method:: LoadPage(location)

   Unlike `SetPage <#SetPage>`_ this function first loads HTML page from `location`  and then displays it. For example::

       htmlWin.LoadPage("help/myproject/index.htm")


   Returns ``False`` if an error occurred, ``True`` otherwise.

   **Parameters:**

   * `location` (string): The address of document. See `wx.FileSystem <../Widgets/wx.FileSystem.html>`_ for details on address format and behaviour of "opener".

   |  

   **Returns:**

   `bool` 

.. seealso:: `LoadFile <#LoadFile>`_
  

--------

.. method:: OnCellClicked(cell, event)

   This method is called when a mouse button is clicked inside `wx.html.HtmlWindow`.

   The default behaviour is to emit a `wx.html.HtmlCellEvent <../Events/wx.html.HtmlCellEvent.html>`_ and, if the event was not processed or skipped, 
   call `OnLinkClicked <#OnLinkClicked>`_ if the cell contains an hypertext link.

   **Parameters:**

   * `cell` (`wx.html.HtmlCell <wx.html.HtmlCell.html>`_): The cell inside which the mouse was clicked, always a simple (i.e. non-container) cell.
   * `event` (int): The mouse event containing other information about the click.

   |  

   **Returns:**

   `bool` 


.. warning:: Overloading this method is deprecated; intercept the event instead.

--------

.. method:: OnCellMouseHover(cell, x, y)

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

   Default behaviour is to emit a `wx.html.HtmlCellEvent <../Events/wx.html.HtmlCellEvent.html>`_.

   **Parameters:**

   * `cell` (`wx.html.HtmlCell <wx.html.HtmlCell.html>`_): The cell inside which the mouse is currently, always a simple (i.e. non-container) cell.
   * `x, y` (int): The logical coordinates of the click point.


.. warning:: Overloading this method is deprecated; intercept the event instead.

--------

.. method:: OnLinkClicked(link)

   Called when user clicks on hypertext link. 

   Default behaviour is to emit a `wx.html.HtmlLinkEvent <../Events/wx.html.HtmlLinkEvent.html>`_ and, if the event was not processed or skipped, 
   call `LoadPage <#LoadPage>`_ and do nothing else. 


   **Parameters:**

   * `link` (`wx.HtmlLinkInfo <wx.HtmlLinkInfo.html>`_) 


.. warning:: Overloading this method is deprecated; intercept the event instead.

.. seealso:: `wx.html.HtmlLinkInfo <wx.html.HtmlLinkInfo.html>`_

--------

.. method:: OnOpeningURL(type, url, redirect)

   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 ``wx.html.HTML_OPEN``. 

   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 ``wx.html.HTML_OPEN``, but if overloaded the possible return values are:

   ===========================================  =====================================================
   Return Values                                Description
   ===========================================  =====================================================
   ``wx.html.HTML_OPEN``                        Open the URL.  
   ``wx.html.HTML_BLOCK``                       Deny access to the URL.
   ``wx.html.HTML_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.  
   ===========================================  =====================================================

   |

   **Parameters:**

   * `type` (int): Indicates type of the resource. Is one of:

      ===========================================  =====================================================
      Resource Flag                                Description
      ===========================================  =====================================================
      ``wx.html.HTML_URL_PAGE``                    Opening a HTML page. 
      ``wx.html.HTML_URL_IMAGE``                   Opening an image. 
      ``wx.html.HTML_URL_OTHER``                   Opening a resource that doesn't fall into any other category.
      ===========================================  =====================================================

   * `url` (string): URL being opened.
   * `redirect` (string): string that must be filled with an URL if `OnOpeningURL` returns ``wx.html.HTML_REDIRECT``.

   |  

   **Returns:**

   `int` 

--------

.. method:: OnSetTitle(title)

   Called on parsing ``<TITLE>`` tag.

   **Parameters:**

   * `title` (string) 

--------

.. method:: ReadCustomization(cfg, path="")

   This reads custom settings from `wx.Config`. 

   It uses the path `path` if given, otherwise it saves info into currently selected path. The values are stored in sub-path ``wx.HtmlWindow``.

   Read values: all things set by `SetFonts <#SetFonts>`_, `SetBorders <#SetBorders>`_.

   **Parameters:**

   * `cfg` (`wx.ConfigBase <../Widgets/wx.ConfigBase.html>`_): `wx.Config` from which you want to read the configuration.
   * `path` (string): Optional path in config tree. If not given current path is used.

--------

.. method:: ScrollToAnchor(anchor)

   |
   
   **Parameters:**

   * `anchor` (string)

   |

   **Returns:**

   `bool` 

--------

.. method:: SelectAll()

   Selects all text in the window.


.. seealso:: `SelectLine <#SelectLine>`_, `SelectWord <#SelectWord>`_
  

--------

.. method:: SelectLine(pos)

   Selects the line of text that `pos` points at. 

   **Parameters:**

   * `pos` (`wx.Point <../Widgets/wx.Point.html>`_) 


.. note:: Note that `pos` is relative to the top of displayed page, not to window's origin, use `CalcUnscrolledPosition <../Widgets/wx.ScrolledWindow.html#CalcUnscrolledPosition>`_ 
   to convert physical coordinate.

.. seealso:: `SelectAll <#SelectAll>`_, `SelectWord <#SelectWord>`_
  

--------

.. method:: SelectWord(pos)

   Selects the word at position `pos`. 

   **Parameters:**

   * `pos` (`wx.Point <../Widgets/wx.Point.html>`_) 


.. note:: Note that `pos` is relative to the top of displayed page, not to window's origin, use `CalcUnscrolledPosition <../Widgets/wx.ScrolledWindow.html#CalcUnscrolledPosition>`_ 
   to convert physical coordinate.

.. seealso:: `SelectAll <#SelectAll>`_, `SelectLine <#SelectLine>`_
  

--------

.. method:: SelectionToText()

   Returns current selection as plain text. 

   Returns empty string if no text is currently selected.

   |  

   **Returns:**

   `string` 

--------

.. method:: SetBackgroundImage(bmpBg)

   |
   
   **Parameters:**

   * `bmpBg` (`wx.Bitmap <../Widgets/wx.Bitmap.html>`_)

--------

.. method:: SetBorders(b)

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

   |

   .. image:: ../images/wxWidgets/border.png

   |

   **Parameters:**

   * `b` (int): indentation from borders in pixels.

--------

.. method:: SetFonts(normal_face, fixed_face, sizes=None)

   This function sets font sizes and faces.

   Default font sizes are defined by constants ``wx.html.HTML_FONT_SIZE_1``, ``wx.html.HTML_FONT_SIZE_2``, ..., ``wx.html.HTML_FONT_SIZE_7``. 
   Note that they differ among platforms. 

   Default face names are empty strings.

   **Parameters:**

   * `normal_face` (string): 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.
   * `fixed_face` (string): As above but for fixed face.
   * `sizes` (int): This is an array of 7 integers items. 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 ``None``

--------

.. method:: SetPage(source)

   Sets HTML page and display it. This won't **load** the page!! It will display the `source`. See example::

       htmlWin.SetPage("<html><body>Hello, world!</body></html>")


   If you want to load a document from some location use `LoadPage <#LoadPage>`_ instead.

   Returns ``False`` if an error occurred, ``True`` otherwise.

   **Parameters:**

   * `source` (string): The HTML document source to be displayed.

   |  

   **Returns:**

   `bool` 

--------

.. method:: SetRelatedFrame(frame, format)

   Sets the frame in which page title will be displayed. 

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

   **Parameters:**

   * `frame` (`wx.Frame <../Widgets/wx.Frame.html>`_) 
   * `format` (string) 

--------

.. method:: SetRelatedStatusBar(bar)

   **After** calling `SetRelatedFrame <#SetRelatedFrame>`_, this sets statusbar slot where messages will be displayed. (Default is -1 = no messages.)

   **Parameters:**

   * `bar` (int): `wx.StatusBar <../Widgets/wx.StatusBar.html>`_ slot number (0..n)

--------

.. method:: SetStandardFonts(size=-1, normal_face="", fixed_face="")

   |
   
   **Parameters:**

   * `size` (int)
   * `normal_face` (string)
   * `fixed_face` (string)

--------

.. method:: ToText()

   Returns content of currently displayed page as plain text.

   |  

   **Returns:**

   `string` 

--------

.. method:: WriteCustomization(cfg, path="")

   Saves custom settings into `wx.Config`. 

   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 ``wx.HtmlWindow``.

   Saved values: all things set by `SetFonts <#SetFonts>`_, `SetBorders <#SetBorders>`_.

   **Parameters:**

   * `cfg` (`wx.ConfigBase <../Widgets/wx.ConfigBase.html>`_): `wx.Config` to which you want to save the configuration.
   * `path` (string): Optional path in config tree. If not given, the current path is used.

--------

Properties
^^^^^^^^^^


.. attribute:: InternalRepresentation

   See `GetInternalRepresentation <#GetInternalRepresentation>`_

.. attribute:: OpenedAnchor

   See `GetOpenedAnchor <#GetOpenedAnchor>`_

.. attribute:: OpenedPage

   See `GetOpenedPage <#GetOpenedPage>`_

.. attribute:: OpenedPageTitle

   See `GetOpenedPageTitle <#GetOpenedPageTitle>`_

.. attribute:: Parser

   See `GetParser <#GetParser>`_

.. attribute:: RelatedFrame

   See `GetRelatedFrame <#GetRelatedFrame>`_