HtmlViewer

  + Object
    + Display
      + UIComponent
        + Control
          + HtmlViewer

The HtmlViewer class is a control designed to render XHTML pages. Like all classes derived from UIComponent, it is not instantiable, cloneable or derivable. The only instances available to the programmer are those automatically generated by HB++ when you place the corresponding control on a form.

If the XHTML page to render is standalone, ie it does not reference any external CSS file nor it contains any image, you can simply place the control on your form and set its content by calling its SetHtmlText method. The following example displays a simple rich text:

Private Sub Button1_Click()
  HtmlViewer1.SetHtmlText "<html><body><p><strong>Bold text</strong></p><p><em>Italic text</em></p></body></html>"
End Sub

Note: by default, the control assumes the text is UTF-8 encoded. If a different encoding is used, you can either convert your text to UTF-8 using the Utf8 function or either specify the code page it uses by adding a <meta> tag in the page header. For example:

Private Sub Button1_Click()
  HtmlViewer1.SetHtmlText "<html><head><meta http-equiv=""Content-Type"" content=""text/html; charset=iso-8859-1""/></head><body><p>The <em>crème brûlée</em>is the best dessert ever.</p></body></html>"
End Sub

However, most XHTML pages require a CSS file and some images to be rendered properly. Since the control cannot resolve URIs, as it does not kown where the XHTML content comes from, it respectively raises CSS and Image events when it encouters <link> and <img> tags. It is then up to your code to catch these events, to retrieve the requested content, and to return it to the control. The following example displays a page located on an expansion card; it supposes image URIs are simply paths and filenames on the card:

Private vfs As New VFSVolume

Private Sub Form_Load()
  Dim f As New StreamFile

  vfs.FindFirstVolume
  f.Open vfs.Reference, "/mypage.html", hbModeReadOnly+hbModeOpenExisting
  HtmlViewer1.SetHtmlText f
  f.Close
End Sub

Private Sub HtmlViewer1_Image(ByVal sBase As String, ByVal sURI As String, ByRef objBmp As Bitmap)
  Dim f As New StreamFile
  
  f.Open vfs.Reference, sURI, hbModeOpenExisting+hbModeReadOnly
  objBmp = New Bitmap

  Select Case LCase(Right(sURI,4))
    Case ".png"
      objBmp.CreateFromPNG f
    Case ".gif"
      objBmp.CreateFromGIF f
    Case ".jpg"
      objBmp.CreateFromJPEG f
    Case Else
      Err.Raise 999, "Unsupported file format"
  End Select
End Sub

A similar code could be used to load a CSS file on the CSS event.

The HtmlViewer control can be associated a vertical scrollbar at design time through its Scrollbar property. The ScrollPos can be used at runtime to scroll the control content. Once a page is successfully parsed and displayed, the Title property can be used to retrieve the title of the page. The Click event is raised when the user clicks on a link, ie the content enclosed into a <a> tag. You'll typically process this event to load a new page in the control. Finally, the XmlError event is raised to report syntax errors in the XHTML page.

Due to the limited screen size and computing power, the HtmlViewer control is not as powerful and flexible as a desktop web navigator:

* It can only parse strict XHTML 1.0 pages. Transitionnal XHTML and HTML 4.0 are not supported.
* Forms are not supported. Tags such as <form>, <fieldset>, <textarea>, or <option> are simply ignored.
* It only supports CSS mobile properties, which is a subset of the full CSS specification.
* The height of the rendered page cannot exceed 32767 pixels.

For the sake of completeness, here are the tags the HtmlViewer control recognizes: a, abbr, acronym, address, b, base, bdo, big, blockquote, body, br, caption, cite, code, col, colgroup, dd, del, dfn, div, dl, dt, em, frame, frameset, h1, h2, h3, h4, h5, h6, head, hr, html, i, iframe, img, ins, kbd, li, link, map, noframes, noscript, ol, p, pre, q, samp, small, span, strong, style, sub, sup, table, tbody, td, tfoot, th, thead, title, tr, tt, ul, var.

Members	Description

Click	Raised when the user taps an hyperlink.
CSS	Raised to obtain a CSS file.
Dispose	Raised when a data stream is no longer used.
Image	Raised to obtain an image.
Scrollbar	Scrollbar attached to the control.
ScrollPos	Scroll position.
SetHtmlText	Sets the document.
Title	Title of the page.
XmlError	Raised when an error is encountered in the XHTML document.

Inherited from Control	Description

DrawFocusRing	Draws the focus ring.
GotFocus	Event raised when the control gains the focus.
Layer	Layer to which the control belongs.
LostFocus	Event raised when the control loses the focus.
NavFlags	Navigation flags for the control.
RemoveFocusRing	Erase the focus ring.
Tag	String associated with the control.
Visible	Indicates if a control is visible or not.

Inherited from UIComponent	Description

ComponentToScreen	Converts coordinates relative to a component into coordinates relative to the screen.
FiveWayNavigator	Event raised when the user presses one of the 5-way navigator keys.
Height	Element height.
Left	Distance between the left edge of the form and the left edge of the element.
Move	Moves or resizes an element.
PenDown	Event raised when the user touches an UI element with the stylus.
PenMove	Event raised when the user moves the stylus.
PenUp	Event raised when the user releases the stylus.
ScreenToComponent	Converts coordinates relative to the screen into coordinates relative a component.
Top	Distance between the top edge of the form and the top edge of the element.
UIRef	Internal reference to a control.
Width	Element width.

Inherited from Display	Description

Arc	Draws an arc.
BackColor	Background color.
BatchLimit	Size of the graphics instruction buffer.
CoordinateSystem	Coordinates system.
CopyArea	Efficiently copies part of a Display object to another.
DrawFont	Font used to draw the text.
Flush	Empties the graphics instruction buffer.
FontMetrics	Returns a FontMetrics object describing the physical charateristics of the currently active font.
ForeColor	Foreground color.
GetPixel	Queries the color of a given pixel.
hWin	Returns the window handle.
Line	Draws a line.
Oval	Draws a circle or ellipse.
Pattern	Defines the pattern used to fill drawings.
Polygon	Draws a polygon.
PutPixel	Sets the color of a pixel.
Rectangle	Draw a rectangle.
ResID	Identifier of the resource associated with the object.
ScaleFont	Enable or disable font scaling.
TextColor	Text color.
TextOut	Draw text.

Inherited from Object	Description

ClassID	Returns the type identifier corresponding to the actual class of the object.
Implements	Determines whether the object implements the features of a given class.
Iterate	Event raised to iterate over the elements of a container object.
Recipient	Recipient of events sent by the object.
Serialize	Event raised to serialize the object content into a stream.

System	Minimal version	Remarks

Palm OS	Palm OS 3.0	N/A