PtHtml

`PtHtml`

A widget for displaying HTML files

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtHtml

For more information, see the diagram of the widget hierarchy.

Public header:

<photon/PtHtml.h>

You'll need some other definitions and header files, depending on what kinds of images your widget will display. You need to define at least one type of image. See "Supporting images" below.

Description:

The PtHtml widget displays files containing the Hypertext Markup Language (HTML).

PtHtml

A PtHtml widget.

This widget supports HTML 1.0 with a few extensions (such as simple table support), and can load files only from the local filesystem. For this reason, the widget wouldn't be useful in an application such as a web browser, which would require many more features.

Instead, the widget is intended to be used to create a custom helpviewer or similar applications, which require the display of formatted text and images with hyperlinks.

Given the filename of an HTML file, the widget will load and render the HTML within the canvas (or viewport) of the widget. If the rendered page is larger than the viewport, the widget will create scrollbars so that the user can scroll around the page.

The widget lets you attach callbacks, which will be called before and after a new file is loaded (for example if the user clicks on a hyperlink), and before any inline images are loaded.

Elements

The following table summarizes the HTML elements and attributes supported by the PtHtml class.

For some of the elements, the end tag is optional and is indicated by square brackets.

The attributes are shown with the possible attribute values. Where more than one option is shown, one of them must be selected.

Element	Tags	Attributes
Comment	`<!-- comment -->`
Document	<html>...</html>
Head	<head>...</head>
Title	<title>...</title>
Link	<link>	`href=`url, `rel=`string
Body	<body>...</body>
Heading 1	<h1>...</h1>	`id=`string, `align={left,center,right}`
Heading 2	<h2>...</h2>	`id=`string, `align={left,center,right}`
Heading 3	<h3>...</h3>	`id=`string, `align={left,center,right}`
Heading 4	<h4>...</h4>	`id=`string, `align={left,center,right}`
Heading 5	<h5>...</h5>	`id=`string, `align={left,center,right}`
Heading 6	<h6>...</h6>	`id=`string, `align={left,center,right}`
Rule	<hr>	`id=`string
Paragraph	<p>...[</p>]	`id=`string
Linebreak	<br>	`id=`string
Image	<img>	`src=`url, `align={top,middle,bottom}`, `alt=`string, `id=`string
Anchor	<a>...</a>	`href=`url, `name=`string, `id=`string
Preformatted	<pre>...</pre>	`id=`string
Blockquote	<blockquote>...</blockquote>	`id=`string
Address	<address>...</address>	`id=`string
Note	<note>...</note>	`src=`url, `id=`string
Definition list	<dl>...</dl>	`compact`, `id=`string
Term	<dt>...[</dt>]	`id=`string
Description	<dd>...[</dd>]	`id=`string
Ordered list	<ol>...</ol>	`id=`string
Unordered list	<ul>...</ul>	`id=`string
List item	<li>...[</li>]	`id=`string
Emphasis	<em>...</em>	`id=`string
Strong	<strong>...</strong>	`id=`string
Code	<code>...</code>	`id=`string
Sample	<samp>...</samp>	`id=`string
Keyboard	<kbd>...</kbd>	`id=`string
Variable	<var>...</var>	`id=`string
Definition	<dfn>...</dfn>	`id=`string
Citation	<cite>...</cite>	`id=`string
Teletype	<tt>...</tt>	`id=`string
Bold	<b>...</b>	`id=`string
Italic	<i>...</i>	`id=`string
Underlined	<u>...</u>	`id=`string
Table	<table>...</table>	`border`, `align={left,center,right}`, `id=`string
Table heading	<th>...[</th>]	`align={left,center,right}`, `id=`string
Table data	<td>...[</td>]	`align={left,center,right}`, `id=`string
Table row	<tr>...[</tr>]	`id=`string

Entities

The PtHtml widget supports the standard HTML 1.0 and ISO-8859 character entities. An entity starts with an ampersand, is followed by the entity name, and ends with a semicolon (e.g. © is rendered as ©).

PtHtml also supports the following entities:

Entity:	Meaning:	Rendered as:
` `	Nonbreaking space	Space
`&emsp;`	Em-space	Space
`&ensp;`	En-space	Space
`—`	Em-dash	Dash (`-`)
`–`	En-dash	Dash (`-`)
`“`	Left double quote	"
`”`	Right double quote	"
`‘`	Left single quote	'
`’`	Right single quote	'
`™`	Trademark	TM

Supporting images

To have the PtHtml widget support images, include code similar to the following example somewhere in your program (e.g. in the application's init file):

/* image headers */
#define PX_IMAGE_MODULES
#define PX_GIF_SUPPORT
#define PX_BMP_SUPPORT
#include <photon/PxImage.h>

This will cause the code for displaying GIF and BMP images to be linked into your program. For more information, see PxLoadImage() in the Photon Library Reference.

Printing

To support printing, the html widget has a special page mode, which you can set in the Pt_ARG_HTML_FLAGS resource. When in page mode, the widget tries to do a clean page break when the height of the current page is greater than the vertical display area. The loaded file is then divided into one or more pages.

The number of pages can be read from the Pt_ARG_HTML_PAGES resource. To display a particular page, you can set the Pt_ARG_HTML_PAGE_N resource. To print the current page, you can use the standard widget-printing mechanisms.

New resources:

Resource	C type	Pt type	Default
Pt_ARG_HTML_BORDER_WIDTH	`short`	Scalar	1
Pt_ARG_HTML_CURSOR_BUSY	`short`	Scalar	Ph_CURSOR_CLOCK
Pt_ARG_HTML_CURSOR_DEFAULT	`short`	Scalar	Ph_CURSOR_POINTER
Pt_ARG_HTML_CURSOR_LINK	`short`	Scalar	Ph_CURSOR_FINGER
Pt_ARG_HTML_FILL_COLOR	`PgColor_t`	Scalar	Pg_GREY
Pt_ARG_HTML_FLAGS	`long`	Flag	0
Pt_ARG_HTML_H1_FONT	`char *`	String	`"helv24"`
Pt_ARG_HTML_H2_FONT	`char *`	String	`"helv18"`
Pt_ARG_HTML_H3_FONT	`char *`	String	`"helv14"`
Pt_ARG_HTML_H4_FONT	`char *`	String	`"helv12"`
Pt_ARG_HTML_H5_FONT	`char *`	String	`"helv10"`
Pt_ARG_HTML_H6_FONT	`char *`	String	`"helv08"`
Pt_ARG_HTML_LINK_COLOR	`PgColor_t`	Scalar	Pg_DBLUE
Pt_ARG_HTML_PAGE_BM	`short`	Scalar	5
Pt_ARG_HTML_PAGE_H	`int`	Scalar	0 (read-only)
Pt_ARG_HTML_PAGE_LM	`short`	Scalar	5
Pt_ARG_HTML_PAGE_N	`long`	Scalar	0
Pt_ARG_HTML_PAGE_RM	`short`	Scalar	5
Pt_ARG_HTML_PAGE_TM	`short`	Scalar	5
Pt_ARG_HTML_PAGE_W	`int`	Scalar	0 (read-only)
Pt_ARG_HTML_PAGE_X	`int`	Scalar	0
Pt_ARG_HTML_PAGE_Y	`int`	Scalar	0
Pt_ARG_HTML_PAGES	`long`	Scalar	0 (read-only)
Pt_ARG_HTML_SCROLL_COLOR	`PgColor_t`	Scalar	Pg_GREY
Pt_ARG_HTML_SCROLL_FILL_COLOR	`PgColor_t`	Scalar	Pg_MGREY
Pt_ARG_HTML_SCROLL_HORIZONTAL	`short`	Scalar	Pt_ALWAYS
Pt_ARG_HTML_SCROLL_VERTICAL	`short`	Scalar	Pt_ALWAYS
Pt_ARG_HTML_SCROLL_WIDTH	`short`	Scalar	15
Pt_ARG_HTML_TEXT_FONT	`char *`	String	`"helv14"`
Pt_ARG_HTML_URL	`char *`	String	NULL
Pt_CB_HTML_ERROR	`PtCallback_t` *	Link	NULL
Pt_CB_HTML_FILE_POST	`PtCallback_t` *	Link	NULL
Pt_CB_HTML_FILE_PRE	`PtCallback_t` *	Link	NULL
Pt_CB_HTML_IMAGE	`PtCallback_t` *	Link	NULL

Pt_ARG_HTML_BORDER_WIDTH

C type	Pt type	Default
`short`	Scalar	1

The width of the inside border surrounding the canvas of the widget, and the width of the border of the scrollbars. The width of the outside border of the widget is set using the Pt_ARG_BORDER_WIDTH resource.

Pt_ARG_HTML_CURSOR_BUSY

C type	Pt type	Default
`short`	Scalar	Ph_CURSOR_CLOCK

The cursor when loading a file.

Pt_ARG_HTML_CURSOR_DEFAULT

C type	Pt type	Default
`short`	Scalar	Ph_CURSOR_POINTER

The default cursor.

Pt_ARG_HTML_CURSOR_LINK

C type	Pt type	Default
`short`	Scalar	Ph_CURSOR_FINGER

The cursor when over a link.

Pt_ARG_HTML_FILL_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pg_GREY

The RGB color value used to draw the background of the HTML page.

Pt_ARG_HTML_FLAGS

C type	Pt type	Default
`long`	Flag	0

Flags for changing the behavior of the widget. The possible values are:

Pt_HTML_RELOAD - load a page even if its URL is the same as the current page's.
Pt_HTML_PAGE_MODE - put the widget into page mode for printing. For more information, see "Printing," above.

Pt_ARG_HTML_H1_FONT

C type	Pt type	Default
`char *`	String	`"helv24"`

The font to be used to display the heading level 1 text.

Pt_ARG_HTML_H2_FONT

C type	Pt type	Default
`char *`	String	`"helv18"`

The font to be used to display the heading level 2 text.

Pt_ARG_HTML_H3_FONT

C type	Pt type	Default
`char *`	String	`"helv14"`

The font to be used to display the heading level 3 text.

Pt_ARG_HTML_H4_FONT

C type	Pt type	Default
`char *`	String	`"helv12"`

The font to be used to display the heading level 4 text.

Pt_ARG_HTML_H5_FONT

C type	Pt type	Default
`char *`	String	`"helv10"`

The font to be used to display the heading level 5 text.

Pt_ARG_HTML_H6_FONT

C type	Pt type	Default
`char *`	String	`"helv08"`

The font to be used to display the heading level 6 text.

Pt_ARG_HTML_LINK_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pg_DBLUE

The RGB color value used to draw links.

Pt_ARG_HTML_PAGE_BM

C type	Pt type	Default
`short`	Scalar	5

The width of the bottom margin of the rendered HTML page.

Pt_ARG_HTML_PAGE_H (read-only)

C type	Pt type	Default
`int`	Scalar	0

The height of the rendered HTML page.

Pt_ARG_HTML_PAGE_LM

C type	Pt type	Default
`short`	Scalar	5

The width of the left margin of the rendered HTML page.

Pt_ARG_HTML_PAGE_N

C type	Pt type	Default
`long`	Scalar	0

When the widget is in page mode (i.e. Pt_HTML_PAGE_MODE is set in Pt_ARG_HTML_FLAGS), this resource holds the current page number. You can set this resource to display a particular page. For more information, see "Printing," above.

Pt_ARG_HTML_PAGE_RM

C type	Pt type	Default
`short`	Scalar	5

The width of the right margin of the rendered HTML page.

Pt_ARG_HTML_PAGE_TM

C type	Pt type	Default
`short`	Scalar	5

The width of the top margin of the rendered HTML page.

Pt_ARG_HTML_PAGE_W (read-only)

C type	Pt type	Default
`int`	Scalar	0

The width of the rendered HTML page.

Pt_ARG_HTML_PAGE_X

C type	Pt type	Default
`int`	Scalar	0

The horizontal position (in pixels) of the top-left hand corner of the viewport relative to the rendered HTML page. Horizontal scrolling changes the x position.

Pt_ARG_HTML_PAGE_Y

C type	Pt type	Default
`int`	Scalar	0

The vertical position (in pixels) of the top-left hand corner of the viewport relative to the rendered HTML page. Vertical scrolling changes the y position.

Pt_ARG_HTML_PAGES (read-only)

C type	Pt type	Default
`long`	Scalar	0

When the widget is in page mode (i.e. Pt_HTML_PAGE_MODE is set in Pt_ARG_HTML_FLAGS), this resource holds the number of pages in the current document. For more information, see "Printing," above.

Pt_ARG_HTML_SCROLL_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pg_GREY

The RGB color value used to draw the slider of the scrollbars.

Pt_ARG_HTML_SCROLL_FILL_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Pg_MGREY

The RGB color value used to draw the trough of the scrollbars.

Pt_ARG_HTML_SCROLL_HORIZONTAL

C type	Pt type	Default
`short`	Scalar	Pt_ALWAYS

The horizontal scrollbar mode. Possible values are:

Pt_ALWAYS
Pt_AS_REQUIRED - the scrollbar is displayed only if the page width is larger than the viewport width.
Pt_NEVER

Pt_ARG_HTML_SCROLL_VERTICAL

C type	Pt type	Default
`short`	Scalar	Pt_ALWAYS

The vertical scrollbar mode. Possible values are:

Pt_ALWAYS
Pt_AS_REQUIRED - the scrollbar is displayed only if the page height is larger than the viewport height.
Pt_NEVER

Pt_ARG_HTML_SCROLL_WIDTH

C type	Pt type	Default
`short`	Scalar	15

The width of the vertical scrollbar and the height of the horizontal scrollbar, in pixels.

Pt_ARG_HTML_TEXT_FONT

C type	Pt type	Default
`char *`	String	`"helv14"`

The font to be used to display the body text.

Pt_ARG_HTML_URL

C type	Pt type	Default
`char *`	String	NULL

The Universal Resource Locator (URL) of the HTML file to be displayed. The URL can have the form:

//node/directory/file.html#name

When the URL resource is set, the widget loads and displays the HTML file (and any images in the file), moving to the position of identifier name on the page. If the given file path is relative (doesn't start with a forward slash) then an absolute path is constructed relative to the currently displayed file.

Pt_CB_HTML_ERROR

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks the widget invokes when the given URL can't be opened.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_HTML_ERROR

cbdata

A pointer to a PtHtmlCallback_t structure that contains at least the following member:

char *url;: The URL of the file that couldn't be loaded by the widget.

These callbacks should return Pt_CONTINUE.

Pt_CB_HTML_FILE_POST

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks that the widget invokes after loading an HTML file.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_HTML_FILE_POST

cbdata

A pointer to a PtHtmlCallback_t structure that contains at least the following member:

char *url;: The full URL of the currently loaded file. This can be used to implement a history mechanism by recording the URL.

These callbacks should return Pt_CONTINUE.

Pt_CB_HTML_FILE_PRE

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks that the widget invokes before loading an HTML file.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_HTML_FILE_PRE

cbdata

A pointer to a PtHtmlCallback_t structure that contains at least the following member:

char *url;: The URL of the HTML file about to be loaded. The URL is given exactly as it was specified in the HTML file. The URL can be changed here if another file should be loaded instead, or set to NULL if no file should be loaded.

These callbacks should return Pt_CONTINUE.

Pt_CB_HTML_IMAGE

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks that the widget invokes before loading an image file.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_HTML_IMAGE

cbdata

A pointer to a PtHtmlCallback_t structure that contains at least the following member:

char *url;: The URL of the image about to be loaded. The URL is given exactly as it was specified in the HTML file. The URL can be changed here if another file should be loaded instead, or set to NULL if no file should be loaded.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.

Resource	Inherited from	Default override
Pt_ARG_ANCHOR_FLAGS	`PtContainer`	Pt_TOP_ANCHORED_TOP \| Pt_RIGHT_ANCHORED_RIGHT \| Pt_BOTTOM_ANCHORED_BOTTOM \| Pt_LEFT_ANCHORED_LEFT
Pt_ARG_ANCHOR_OFFSETS	`PtContainer`
Pt_ARG_AREA	`PtWidget`
Pt_ARG_BANDWIDTH_THRESHOLD	`PtBasic`	Not used by this class.
Pt_ARG_BITMAP_CURSOR	`PtWidget`
Pt_ARG_BORDER_WIDTH	`PtWidget`	1
Pt_ARG_BOT_BORDER_COLOR	`PtBasic`
Pt_ARG_COLOR	`PtBasic`
Pt_ARG_CONTAINER_FLAGS	`PtContainer`
Pt_ARG_CURSOR_COLOR	`PtWidget`
Pt_ARG_CURSOR_TYPE	`PtWidget`
Pt_ARG_DATA	`PtWidget`
Pt_ARG_DIM	`PtWidget`
Pt_ARG_EFLAGS	`PtWidget`	Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR	`PtBasic`	Pg_GREY
Pt_ARG_FILL_PATTERN	`PtBasic`
Pt_ARG_FLAGS	`PtWidget`
Pt_ARG_HELP_TOPIC	`PtWidget`
Pt_ARG_HIGHLIGHT_ROUNDNESS	`PtBasic`
Pt_ARG_MARGIN_HEIGHT	`PtBasic`	2
Pt_ARG_MARGIN_WIDTH	`PtBasic`	2
Pt_ARG_POS	`PtWidget`
Pt_ARG_RESIZE_FLAGS	`PtWidget`	0
Pt_ARG_TOP_BORDER_COLOR	`PtBasic`
Pt_ARG_TRANS_PATTERN	`PtBasic`
Pt_ARG_USER_DATA	`PtWidget`
Pt_CB_ACTIVATE	`PtBasic`
Pt_CB_ARM	`PtBasic`
Pt_CB_BALLOONS	`PtContainer`
Pt_CB_BLOCKED	`PtWidget`
Pt_CB_DESTROYED	`PtWidget`
Pt_CB_DISARM	`PtBasic`
Pt_CB_FILTER	`PtContainer`
Pt_CB_GOT_FOCUS	`PtBasic`
Pt_CB_HOTKEY	`PtWidget`
Pt_CB_LOST_FOCUS	`PtBasic`
Pt_CB_MENU	`PtBasic`
Pt_CB_RAW	`PtWidget`
Pt_CB_REALIZED	`PtWidget`
Pt_CB_REPEAT	`PtBasic`
Pt_CB_RESIZE	`PtContainer`
Pt_CB_UNREALIZED	`PtWidget`

Convenience functions:

The following convenience functions are defined by the PtHtml class for accessing some of the data in the HTML file. Here's a brief overview:

PtHtmlTitle(): Returns the title of an HTML file.
PtHtmlLink(): Returns links to related HTML documents.

Entity:	Meaning:	Rendered as:
` `	Nonbreaking space	Space
`&emsp;`	Em-space	Space
`&ensp;`	En-space	Space
`—`	Em-dash	Dash (`-`)
`–`	En-dash	Dash (`-`)
`“`	Left double quote	"
`”`	Right double quote	"
`‘`	Left single quote	'
`’`	Right single quote	'
`™`	Trademark	TM

Entity:	Meaning:	Rendered as:
` `	Nonbreaking space	Space
`&emsp;`	Em-space	Space
`&ensp;`	En-space	Space
`—`	Em-dash	Dash (`-`)
`–`	En-dash	Dash (`-`)
`“`	Left double quote	"
`”`	Right double quote	"
`‘`	Left single quote	'
`’`	Right single quote	'
`™`	Trademark	TM

QNX Community Resources

Entity:	Meaning:	Rendered as:
` `	Nonbreaking space	Space
`&emsp;`	Em-space	Space
`&ensp;`	En-space	Space
`—`	Em-dash	Dash (`-`)
`–`	En-dash	Dash (`-`)
`“`	Left double quote	"
`”`	Right double quote	"
`‘`	Left single quote	'
`’`	Right single quote	'
`™`	Trademark	TM