wxRuby Documentation Home

# 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,
load_page or
load_file. The width of the window is
constant – given in the constructor – and virtual height is changed
dynamically depending on page size.

## Derived from

ScrolledWindow

## 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.

## Event handling

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

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

## See also

HtmlLinkEvent, HtmlCellEvent

## Methods

- HtmlWindow.new
- HtmlWindow#add_filter
- HtmlWindow#append_to_page
- HtmlWindow#get_internal_representation
- HtmlWindow#get_opened_anchor
- HtmlWindow#get_opened_page
- HtmlWindow#get_opened_page_title
- HtmlWindow#get_related_frame
- HtmlWindow#history_back
- HtmlWindow#history_can_back
- HtmlWindow#history_can_forward
- HtmlWindow#history_clear
- HtmlWindow#history_forward
- HtmlWindow#load_file
- HtmlWindow#load_page
- HtmlWindow#on_opening_url
- HtmlWindow#on_set_title
- HtmlWindow#read_customization
- HtmlWindow#select_all
- HtmlWindow#selection_to_text
- HtmlWindow#select_line
- HtmlWindow#select_word
- HtmlWindow#set_borders
- HtmlWindow#set_fonts
- HtmlWindow#set_page
- HtmlWindow#set_related_frame
- HtmlWindow#set_related_status_bar
- HtmlWindow#to_text
- HtmlWindow#write_customization

### HtmlWindow.new

HtmlWindow.new(%(arg-type)Window% parent, Integer id = -1, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer style = HW_DEFAULT_STYLE, String name = “htmlWindow”)

Constructor. The parameters are the same as for the ScrolledWindow constructor.

#### Parameters

- style Window style. See HtmlWindow.

### HtmlWindow#add_filter

add_filter(%(arg-type)HtmlFilter% 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)

### HtmlWindow#append_to_page

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

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

#### Parameters

- source HTML code fragment

#### Return value

false if an error occurred, true otherwise.

### HtmlWindow#get_internal_representation

HtmlContainerCell get_internal_representation()

Returns pointer to the top-level container.

See also: Cells Overview,
Printing Overview

### HtmlWindow#get_opened_anchor

String get_opened_anchor()

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

### 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.

### 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.

### HtmlWindow#get_related_frame

Frame get_related_frame()

Returns the related frame.

### HtmlWindow#history_back

Boolean history_back()

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

### 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).

### 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).

### HtmlWindow#history_clear

history_clear()

Clears history.

### HtmlWindow#history_forward

Boolean history_forward()

Moves to next page in history.

### HtmlWindow#load_file

Boolean load_file(%(arg-type)FileName% filename)

Loads HTML page from file and displays it.

#### Return value

false if an error occurred, true otherwise

#### See also

load_page

### 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”);

#### Parameters

- location The address of document. See FileSystem for details on address format and behaviour of “opener”.

#### Return value

false if an error occurred, true otherwise

#### See also

load_file

### 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.

### HtmlWindow#on_set_title

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

Called on parsing tag. This can be overloaded in subclasses to<br /> customise what happens as that part of an <span class="caps">HTML</span> page is read.</p> <h3 id="HtmlWindow_readcustomization">HtmlWindow#read_customization</h3> <strong>read_customization</strong>(%(arg-type)<a href="">ConfigBase</a>% cfg, <span class="arg-type">String</span> path = ’’) <p>This reads custom settings from Config. It uses the path ‘path’<br /> if given, otherwise it saves info into currently selected path.<br /> The values are stored in sub-path <code>HtmlWindow</code></p> <p>Read values: all things set by SetFonts, SetBorders.</p> <h4>Parameters</h4> <ul> <li><em>cfg</em> Config from which you want to read the configuration.</li> <li><em>path</em> Optional path in config tree. If not given current path is used.</li> </ul> <h3 id="HtmlWindow_selectall">HtmlWindow#select_all</h3> <strong>select_all</strong>() <p>Selects all text in the window.</p> <h4>See also</h4> <p><a href="#HtmlWindow_selectline">select_line</a>,<br /> <a href="#HtmlWindow_selectword">select_word</a></p> <h3 id="HtmlWindow_selectiontotext">HtmlWindow#selection_to_text</h3> String <strong>selection_to_text</strong>() <p>Returns current selection as plain text. Returns empty string if no text<br /> is currently selected.</p> <h3 id="HtmlWindow_selectline">HtmlWindow#select_line</h3> <strong>select_line</strong>(%(arg-type)<a href="">Point</a>% pos) <p>Selects the line of text that pos points at. Note that pos<br /> is relative to the top of displayed page, not to window’s origin, use<br /> <a href="#HtmlWindow_calcunscrolledposition">calc_unscrolled_position</a><br /> to convert physical coordinate.</p> <h4>See also</h4> <p><a href="#HtmlWindow_selectall">select_all</a>,<br /> <a href="#HtmlWindow_selectword">select_word</a></p> <h3 id="HtmlWindow_selectword">HtmlWindow#select_word</h3> <strong>select_word</strong>(%(arg-type)<a href="">Point</a>% pos) <p>Selects the word at position pos. Note that pos<br /> is relative to the top of displayed page, not to window’s origin, use<br /> <a href="#HtmlWindow_calcunscrolledposition">calc_unscrolled_position</a><br /> to convert physical coordinate.</p> <h4>See also</h4> <p><a href="#HtmlWindow_selectall">select_all</a>,<br /> <a href="#HtmlWindow_selectline">select_line</a></p> <h3 id="HtmlWindow_setborders">HtmlWindow#set_borders</h3> <strong>set_borders</strong>(%(arg-type)Integer% border_width) <p>This function sets the space between border of window and <span class="caps">HTML</span><br /> contents.</p> <h4>Parameters</h4> <ul> <li><em>border_width</em> indentation from borders in pixels</li> </ul> <h3 id="HtmlWindow_setfonts">HtmlWindow#set_fonts</h3> <strong>set_fonts</strong>(%(arg-type)String% normal_face, <span class="arg-type">String</span> fixed_face, <span class="arg-type">Integer</span> sizes = nil) <p>This function sets font sizes and faces.</p> <h4>Parameters</h4> <ul> <li><em>normal_face</em> This is face name for normal (i.e. non-fixed) font. <br /> It can be either empty string (then the default face is chosen) or<br /> platform-specific face name. Examples are “helvetica” under Unix or<br /> “Times New Roman” under Windows.</li> <li><em>fixed_face</em> The same thing for fixed face ( <TT>..</TT> )</li> <li><em>sizes</em> This is an array of 7 items of <em>int</em> type.<br /> The values represent size of font with <span class="caps">HTML</span> size from -2 to +4 (equivalent to the <span class="caps">SIZE</span> attribute value of the <span class="caps">HTML</span> <span class="caps">FONT</span> tag). Default sizes are used if <em>sizes</em><br /> is <span class="caps">NULL</span>.</li> </ul> <h4>Defaults</h4> <p>Default font sizes are defined by constants HTML_FONT_SIZE_1,<br /> HTML_FONT_SIZE_2, …, HTML_FONT_SIZE_7. Note that they differ among<br /> platforms. Default face names are empty strings.</p> <h3 id="HtmlWindow_setpage">HtmlWindow#set_page</h3> Boolean <strong>set_page</strong>(%(arg-type)String% source) <p>Sets <span class="caps">HTML</span> page and display it. This doesn’t <strong>load</strong> the page!<br /> It parses and displays the <span class="caps">HTML</span> in the string <em>source</em>.</p> <p>If you want to load a document from some location use <br /> <a href="#HtmlWindow_loadpage">load_page</a> instead.</p> <h4>Parameters</h4> <ul> <li><em>source</em> The <span class="caps">HTML</span> source to be displayed as a document</li> </ul> <h4>Return value</h4> <p>false if an error occurred, true otherwise.</p> <h3 id="HtmlWindow_setrelatedframe">HtmlWindow#set_related_frame</h3> <strong>set_related_frame</strong>(%(arg-type)<a href="">Frame</a>% frame, <span class="arg-type">String</span> format) <p>Sets the frame in which page title will be displayed. <em>format</em> is format of<br /> frame title, e.g. “HtmlHelp : <code>%s</code>”. It must contain exactly one <code>%s</code>. This<br /> <code>%s</code> is substituted with <span class="caps">HTML</span> page title.</p> <h3 id="HtmlWindow_setrelatedstatusbar">HtmlWindow#set_related_status_bar</h3> <strong>set_related_status_bar</strong>(%(arg-type)Integer% bar) <p><strong>After</strong> calling <a href="#HtmlWindow_setrelatedframe">set_related_frame</a>,<br /> this sets statusbar slot where messages will be displayed.<br /> (Default is -1 = no messages.)</p> <h4>Parameters</h4> <ul> <li><em>bar</em> statusbar slot number (0..n)</li> </ul> <h3 id="HtmlWindow_totext">HtmlWindow#to_text</h3> String <strong>to_text</strong>() <p>Returns content of currently displayed page as plain text.</p> <h3 id="HtmlWindow_writecustomization">HtmlWindow#write_customization</h3> <strong>write_customization</strong>(%(arg-type)<a href="">ConfigBase</a>% cfg, <span class="arg-type">String</span> path = ’’) <p>Saves custom settings into Config. It uses the path ‘path’<br /> if given, otherwise it saves info into currently selected path.<br /> Regardless of whether the path is given or not, the function creates sub-path <br /> <code>HtmlWindow</code>.</p> <p>Saved values: all things set by SetFonts, SetBorders.</p> <h4>Parameters</h4> <ul> <li><em>cfg</em> Config to which you want to save the configuration.</li> <li><em>path</em> Optional path in config tree. If not given, the current path is used.</li> </ul> <p id="datestamp">[This page automatically generated from <a href="htmlwindow.txtl">the Textile source</a> at 2023-06-09 00:45:25 +0000]</p> </body> </html>