h1(#wxhtmlwindow). Wx::HtmlWindow

HtmlWindow is a widget for displaying simple HTML. IT supports key HTML
features like links, images, tables and headings, but does not support
all the features of modern browsers such as CSS and Javascript. It's well
suited for creating hypertext-based applications, but not for creating a
complete web browser.

Once the window is created you can set its content by calling
"set_page(html_code)":#HtmlWindow_setpage,
"load_page(location)":#HtmlWindow_loadpage or
"load_file(file_name)":#HtmlWindow_loadfile. The width of the window is
constant - given in the constructor - and virtual height is changed
dynamically depending on page size.

h2. Derived from

"ScrolledWindow":scrolledwindow.html

h2. Window styles



|@HW_SCROLLBAR_NEVER@|Never display scrollbars, noteven when the page is larger than the window.|
|@HW_SCROLLBAR_AUTO@|Display scrollbars only ifpage's size exceeds window's size.|
|@HW_NO_SELECTION@|Don't allow the user to selecttext.|

h2. Event handling

To process user interaction with an HtmlWindow, use these event handlers
to direct input to blocks that take a "HtmlCellEvent":htmlcellevent.html
argument or a "HtmlLinkEvent":htmllinkevent.html.


|*evt_html_cell_clicked(id) { | event | ... }*|A "HtmlCell":htmlcell.html was clicked.|
|*evt_html_cell_hover(id) { | event | ... }*|The mouse passed over a "HtmlCell":htmlcell.html.|
|*evt_html_link_clicked(id) { | event | ... }*|A "HtmlCell":htmlcell.html which contains an hyperlink was clicked.|

h2. See also

"HtmlLinkEvent":htmllinkevent.html, "HtmlCellEvent":htmlcellevent.html

h2. Methods

<div id="methods">

* "HtmlWindow.new":#HtmlWindow_wxhtmlwindow
* "HtmlWindow#add_filter":#HtmlWindow_addfilter
* "HtmlWindow#append_to_page":#HtmlWindow_appendtopage
* "HtmlWindow#get_internal_representation":#HtmlWindow_getinternalrepresentation
* "HtmlWindow#get_opened_anchor":#HtmlWindow_getopenedanchor
* "HtmlWindow#get_opened_page":#HtmlWindow_getopenedpage
* "HtmlWindow#get_opened_page_title":#HtmlWindow_getopenedpagetitle
* "HtmlWindow#get_related_frame":#HtmlWindow_getrelatedframe
* "HtmlWindow#history_back":#HtmlWindow_historyback
* "HtmlWindow#history_can_back":#HtmlWindow_historycanback
* "HtmlWindow#history_can_forward":#HtmlWindow_historycanforward
* "HtmlWindow#history_clear":#HtmlWindow_historyclear
* "HtmlWindow#history_forward":#HtmlWindow_historyforward
* "HtmlWindow#load_file":#HtmlWindow_loadfile
* "HtmlWindow#load_page":#HtmlWindow_loadpage
* "HtmlWindow#on_opening_url":#HtmlWindow_onopeningurl
* "HtmlWindow#on_set_title":#HtmlWindow_onsettitle
* "HtmlWindow#read_customization":#HtmlWindow_readcustomization
* "HtmlWindow#select_all":#HtmlWindow_selectall
* "HtmlWindow#selection_to_text":#HtmlWindow_selectiontotext
* "HtmlWindow#select_line":#HtmlWindow_selectline
* "HtmlWindow#select_word":#HtmlWindow_selectword
* "HtmlWindow#set_borders":#HtmlWindow_setborders
* "HtmlWindow#set_fonts":#HtmlWindow_setfonts
* "HtmlWindow#set_page":#HtmlWindow_setpage
* "HtmlWindow#set_related_frame":#HtmlWindow_setrelatedframe
* "HtmlWindow#set_related_status_bar":#HtmlWindow_setrelatedstatusbar
* "HtmlWindow#to_text":#HtmlWindow_totext
* "HtmlWindow#write_customization":#HtmlWindow_writecustomization

</div>

h3(#HtmlWindow_wxhtmlwindow). HtmlWindow.new

  *HtmlWindow.new*(%(arg-type)"Window":window.html% parent,  %(arg-type)Integer% id = -1, 
                 %(arg-type)"Point":point.html% pos = DEFAULT_POSITION, 
                 %(arg-type)"Size":size.html% size = DEFAULT_SIZE, 
                 %(arg-type)Integer% style = HW_DEFAULT_STYLE, 
                 %(arg-type)String% name = "htmlWindow")

Constructor. The parameters are the same as for the "ScrolledWindow":scrolledwindow.html constructor.

h4. Parameters

* _style_ Window style. See "HtmlWindow":htmlwindow.html.

h3(#HtmlWindow_addfilter). HtmlWindow#add_filter

  *add_filter*(%(arg-type)"HtmlFilter":htmlfilter.html% filter)

Adds "input filter":filters.html 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)


h3(#HtmlWindow_appendtopage). HtmlWindow#append_to_page

 Boolean *append_to_page*(%(arg-type)String% source)

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

h4. Parameters

* _source_ HTML code fragment

h4. Return value

false if an error occurred, true otherwise.

h3(#HtmlWindow_getinternalrepresentation). HtmlWindow#get_internal_representation

 "HtmlContainerCell":htmlcontainercell.html *get_internal_representation*()

Returns pointer to the top-level container.

See also: "Cells Overview":cells.html, 
"Printing Overview":printing.html

h3(#HtmlWindow_getopenedanchor). HtmlWindow#get_opened_anchor

 String *get_opened_anchor*()

Returns anchor within currently opened page
(see "get_opened_page":#HtmlWindow_getopenedpage). 
If no page is opened or if the displayed page wasn't
produced by call to LoadPage, empty string is returned.


h3(#HtmlWindow_getopenedpage). HtmlWindow#get_opened_page

 String *get_opened_page*()

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.

h3(#HtmlWindow_getopenedpagetitle). HtmlWindow#get_opened_page_title

 String *get_opened_page_title*()

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

h3(#HtmlWindow_getrelatedframe). HtmlWindow#get_related_frame

 "Frame":frame.html *get_related_frame*()

Returns the related frame.

h3(#HtmlWindow_historyback). HtmlWindow#history_back

 Boolean *history_back*()

Moves back to the previous page. (each page displayed using 
"load_page":#HtmlWindow_loadpage is stored in history list.)

h3(#HtmlWindow_historycanback). HtmlWindow#history_can_back

 Boolean *history_can_back*()

Returns true if it is possible to go back in the history (i.e. HistoryBack()
won't fail).

h3(#HtmlWindow_historycanforward). HtmlWindow#history_can_forward

 Boolean *history_can_forward*()

Returns true if it is possible to go forward in the history (i.e. HistoryBack()
won't fail).


h3(#HtmlWindow_historyclear). HtmlWindow#history_clear

  *history_clear*()

Clears history.

h3(#HtmlWindow_historyforward). HtmlWindow#history_forward

 Boolean *history_forward*()

Moves to next page in history.

h3(#HtmlWindow_loadfile). HtmlWindow#load_file

 Boolean *load_file*(%(arg-type)"FileName":filename.html% filename)

Loads HTML page from file and displays it.

h4. Return value

false if an error occurred, true otherwise

h4. See also

"load_page":#HtmlWindow_loadpage

h3(#HtmlWindow_loadpage). HtmlWindow#load_page

 Boolean *load_page*(%(arg-type)String% location)

Unlike SetPage this function first loads HTML page from _location_ 
and then displays it. See example:


 htmlwin->LoadPage("help/myproject/index.htm");
 

h4. Parameters

* _location_ The address of document. See "FileSystem":filesystem.html for details on address format and behaviour of "opener".

h4. Return value

false if an error occurred, true otherwise

h4. See also

"load_file":#HtmlWindow_loadfile

h3(#HtmlWindow_onopeningurl). HtmlWindow#on_opening_url

  Boolean _or_ String *on_opening_url*(%(arg-type)String% url)

This method is called whenever the HtmlWindow attempts to open a URL,
either a page, or an image within a page. It can be used to block access
to certain URLs, or rewrite them. This method should return @true@, if
access to the URL should be allowed or @false@ if it should be
blocked. It may also return a string containing a new URL to which the
request should be redirected.

Note that if redirecting, the method will immediately be called again
with the new URL, so to avoid entering an endless loop, you should test
for this and return true if no rewriting is to be done.

The default implementation in the standard Wx::HtmlWindow class always
returns @true@, ie allow the URL.

h3(#HtmlWindow_onsettitle). HtmlWindow#on_set_title

  *on_set_title*(%(arg-type)String% title)

Called on parsing <TITLE> tag. This can be overloaded in subclasses to
customise what happens as that part of an HTML page is read.


h3(#HtmlWindow_readcustomization). HtmlWindow#read_customization

  *read_customization*(%(arg-type)"ConfigBase":configbase.html% cfg,  %(arg-type)String% path = '')

This reads custom settings from Config. It uses the path 'path'
if given, otherwise it saves info into currently selected path.
The values are stored in sub-path @HtmlWindow@

Read values: all things set by SetFonts, SetBorders.

h4. Parameters

* _cfg_ Config from which you want to read the configuration.
* _path_ Optional path in config tree. If not given current path is used.

h3(#HtmlWindow_selectall). HtmlWindow#select_all

  *select_all*()

Selects all text in the window.

h4. See also

"select_line":#HtmlWindow_selectline,
"select_word":#HtmlWindow_selectword

h3(#HtmlWindow_selectiontotext). HtmlWindow#selection_to_text

 String *selection_to_text*()

Returns current selection as plain text. Returns empty string if no text
is currently selected.

h3(#HtmlWindow_selectline). HtmlWindow#select_line

  *select_line*(%(arg-type)"Point":point.html% 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
"calc_unscrolled_position":#HtmlWindow_calcunscrolledposition
to convert physical coordinate.

h4. See also

"select_all":#HtmlWindow_selectall,
"select_word":#HtmlWindow_selectword

h3(#HtmlWindow_selectword). HtmlWindow#select_word

  *select_word*(%(arg-type)"Point":point.html% pos)

Selects the word at position pos. Note that pos
is relative to the top of displayed page, not to window's origin, use
"calc_unscrolled_position":#HtmlWindow_calcunscrolledposition
to convert physical coordinate.

h4. See also

"select_all":#HtmlWindow_selectall,
"select_line":#HtmlWindow_selectline

h3(#HtmlWindow_setborders). HtmlWindow#set_borders

  *set_borders*(%(arg-type)Integer% border_width)

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

h4. Parameters

* _border_width_ indentation from borders in pixels

h3(#HtmlWindow_setfonts). HtmlWindow#set_fonts

  *set_fonts*(%(arg-type)String% normal_face,  %(arg-type)String% fixed_face, 
            %(arg-type)Integer% sizes = nil)

This function sets font sizes and faces.

h4. Parameters

* _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.
* _fixed_face_ The same thing for fixed face ( <TT>..</TT> )
* _sizes_ This is an array of 7 items of _int_ type.
The values represent size of font with HTML size from -2 to +4 (equivalent to the SIZE attribute value of the HTML FONT tag). Default sizes are used if _sizes_
is NULL.

h4. Defaults

Default font sizes are defined by constants HTML_FONT_SIZE_1,
HTML_FONT_SIZE_2, ..., HTML_FONT_SIZE_7. Note that they differ among
platforms. Default face names are empty strings.

h3(#HtmlWindow_setpage). HtmlWindow#set_page

 Boolean *set_page*(%(arg-type)String% source)

Sets HTML page and display it. This doesn't *load* the page!
It parses and displays the HTML in the string _source_.

If you want to load a document from some location use 
"load_page":#HtmlWindow_loadpage instead.

h4. Parameters

* _source_ The HTML source to be displayed as a document

h4. Return value

false if an error occurred, true otherwise.

h3(#HtmlWindow_setrelatedframe). HtmlWindow#set_related_frame

  *set_related_frame*(%(arg-type)"Frame":frame.html% frame,  %(arg-type)String% 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.

h3(#HtmlWindow_setrelatedstatusbar). HtmlWindow#set_related_status_bar

  *set_related_status_bar*(%(arg-type)Integer% bar)

*After* calling "set_related_frame":#HtmlWindow_setrelatedframe,
this sets statusbar slot where messages will be displayed.
(Default is -1 = no messages.)

h4. Parameters

* _bar_ statusbar slot number (0..n)

h3(#HtmlWindow_totext). HtmlWindow#to_text

 String *to_text*()

Returns content of currently displayed page as plain text.

h3(#HtmlWindow_writecustomization). HtmlWindow#write_customization

  *write_customization*(%(arg-type)"ConfigBase":configbase.html% cfg,  %(arg-type)String% path = '')

Saves custom settings into 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 
@HtmlWindow@.

Saved values: all things set by SetFonts, SetBorders.

h4. Parameters

* _cfg_ Config to which you want to save the configuration.
* _path_ Optional path in config tree. If not given, the current path is used.