PtHtml

A widget for displaying HTML files

Class hierarchy:

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

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

PhAB icon:

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

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.

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. &copy; is rendered as ©).

PtHtml also supports the following entities:

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:

Pt_ARG_HTML_BORDER_WIDTH

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

The cursor when loading a file.

Pt_ARG_HTML_CURSOR_DEFAULT

The default cursor.

Pt_ARG_HTML_CURSOR_LINK

The cursor when over a link.

Pt_ARG_HTML_FILL_COLOR

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

Pt_ARG_HTML_FLAGS

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

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

Pt_ARG_HTML_H2_FONT

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

Pt_ARG_HTML_H3_FONT

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

Pt_ARG_HTML_H4_FONT

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

Pt_ARG_HTML_H5_FONT

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

Pt_ARG_HTML_H6_FONT

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

Pt_ARG_HTML_LINK_COLOR

The RGB color value used to draw links.

Pt_ARG_HTML_PAGE_BM

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

Pt_ARG_HTML_PAGE_H (read-only)

The height of the rendered HTML page.

Pt_ARG_HTML_PAGE_LM

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

Pt_ARG_HTML_PAGE_N

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

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

Pt_ARG_HTML_PAGE_TM

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

Pt_ARG_HTML_PAGE_W (read-only)

The width of the rendered HTML page.

Pt_ARG_HTML_PAGE_X

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

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)

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

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

Pt_ARG_HTML_SCROLL_FILL_COLOR

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

Pt_ARG_HTML_SCROLL_HORIZONTAL

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

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

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

Pt_ARG_HTML_TEXT_FONT

The font to be used to display the body text.

Pt_ARG_HTML_URL

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

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

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

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

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.

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.