hv3 (n)

hv3 - Mega-widget building on Tkhtml.

THIS IS A WORK IN PROGRESS. IT IS POSSIBLE TO USE THE HV3 WIDGET, BUT IT IS NOT YET PROPERLY PACKAGED. POST ON THE MAILING LIST IF YOU WISH TO USE IT NOW.

Comments and feedback also welcome.

package require snit
package require hv3
::hv3::hv3 pathName ?options?

The [hv3] command creates a new window (given by the pathName argument) and makes it into hv3 widget. The hv3 command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist. Hv3 is a pure Tcl widget implemented using Tkhtml3 and the excellent mega-widget framework Snit.

An [hv3] widget is not a web-browser. If it were to be used as a component in a web-browser application it would represent a single browser frame (or iframe). The API described in this document is not the whole API offered by the snit object ::hv3::hv3. Instead, it is the subset of that API that is expected not to change. No guarantees of course.

There are two 'objects' involved in using the [hv3] widget. One is the widget itself ([::hv3::hv3]). The other is the request-handle ([::hv3::request]). A request-handle is the interface between the hv3 widget and wherever it is getting its data from (i.e. your implementation of http://, https:// etc.). Many users will also wish to understand the Tkhtml3 "node-handle" interface, documented as part of the Tkhtml3 manpage.

An [hv3] widget provides the following features on top of the [html] widget:

• Built-in scrollbars.
• Support for selecting text with the pointer.
• Support for loading linked images and stylesheets from URIs.
• Support for HTML forms and submission thereof.
• Support for CSS configured hover (mouseover) effects.
• Support for loading a new document by clicking on a hyper-link.

The two most important interfaces are the [goto] method and the -requestcmd option. The [goto] method tells the widget to load the document identified by the specified absolute or relative URI.

The -requestcmd option must be configured with a callback script that the widget invokes to request the requested document. It is the users responsibility to retrieve the document and pass it back to the widget. If the document contains links to external resources (images or CSS stylesheets), then the widget invokes the -requestcmd script to request these. The -requestcmd callback may choose to implement handling for one or more of http:// URIs, file:// URIs or any other existing or invented URI scheme. See the "Example Usage" section below for an example.

-height
-width

The following Tkhtml options are exposed as public options of this mega-widget.

-fontscale
-fonttable
-forcefontmetrics
-zoom

The following Tkhtml commands are exposed as public options of this mega-widget.

node ? ?-index? x y?

Command-Line Name: -enableimages
Database Name: enableimages
Database Class: Enableimages

Command-Line Name: -isvisitedcmd
Database Name: isvisitedcmd
Database Class: Isvisitedcmd

Command-Line Name: -requestcmd
Database Name: requestcmd
Database Class: Requestcmd

Command-Line Name: -targetcmd
Database Name: targetcmd
Database Class: Targetcmd

The [hv3] command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget as follows:

pathName cget option

pathName configure ?option? ?value?

pathName goto uri

pathName stop

To be useful, the user must provide the hv3 with some way to request resources ((X)HTML documents, CSS stylesheets and binary image files) identified by URI for display. To this end, the user configures a -requestcmd script with the hv3 widget. Each time a resource is required, the -requestcmd script is evaluated with a single argument, a request handle object identifier, appended to it.

A request handle object is a snit object. The -requestcmd script can query the object to determine the parameters of the request and then invoke object methods to return data and meta data. The key APIs are the -uri option and the [finish] method.

Data may be returned asynchronously. That is, it is not necessary to return data from within the -requestcmd evaluation, the request handle may be stored and data returned at some later time.

Command-Line Name: -enctype
Database Name: enctype
Database Class: Enctype

if {[$handle cget -postdata] ne ""} {
  # This is a POST request.
} else {
  # This is a GET request.
}

Command-Line Name: -header
Database Name: header
Database Class: Header

Command-Line Name: -mimetype
Database Name: mimetype
Database Class: Mimetype

Command-Line Name: -postdata
Database Name: postdata
Database Class: Postdata

Command-Line Name: -requestheader
Database Name: requestheader
Database Class: Requestheader

Command-Line Name: -uri
Database Name: uri
Database Class: Uri

requestHandle append data

requestHandle finish

The hv3 widget may seem a little unusual at first in that there is no interface to feed data directly from the users script to the widget. Instead, the widget requests the required data by invoking the -requestcmd script. Data is identified by the -uri option of the request handle passed as an argument.

The reason for this is that the widget often deals with documents that contain linked resources (external CSS stylesheets or images). The resources are not always known when the user script initiates loading the document. For example, if the following document is to be loaded from URI "http://tkhtml.tcl.tk":

<HTML>
  <BODY>
    <IMG src="image.gif">
  </BODY>
</HTML>

then the -requestcmd must implement the HTTP protocol. The user calls:

$hv3 goto http://tkhtml.tcl.tk

which causes the -requestcmd script to be invoked with a request handle argument specifying the URI "http://tkhtml.tcl.tk".

When the -requestcmd returns the data for the URI "http://tkhtml.tcl.tk", the widget invokes the -requestcmd a second time, with a request handle argument specifying the URI "http://tkhtml.tcl.tk/image.gif". If the document contained links to CSS stylesheets or other images, the _-requestcmd- script would be invoked for each of these also.

All this is fine if you are fetching data from http servers, but a little inconvenient if the user script already has the document to display ready in a Tcl variable (or variables). The solution here is to invent a custom URI scheme to use within the application. For example, the following example demonstrates a -requestcmd script that implements the "tclvar:", URI scheme for refering to global Tcl variables.

proc tclvar_requestcmd {R} {
  # Get the URI from the request handle. The URI should look 
  # something like:
  #
  #   tclvar:///<global varname>
  #
  set uri [$R cget -uri]

  # Strip "tclvar:///" from the start of the URI.
  set var [string range $uri 10 end]

  # Return the data in the global variable $var to the widget.
  global $var
  $R finish [set $var]
}

And a simple script for using this -requestcmd:

set my_document {
  <HTML>
    <LINK rel="stylesheet" href="my_stylesheet">
    <BODY>
      <P>Some red text.</P>
    </BODY>
  </HTML>
}
set my_stylesheet {
  P { color : red }
}

::hv3::hv3 .hv3 
pack .hv3 -fill both -expand true

.hv3 configure -requestcmd tclvar_requestcmd
.hv3 goto tclvar:///my_document

Note the complication in the code above - the string "tclvar:///" is found at the start of each URI passed to [tclvar_requestcmd]. This is because Hv3 resolves and escapes all URIs against the base URI of the currently loaded document before passing them to the -requestcmd. This means you need to be careful with special characters. If the name of the variable storing the stylesheet document in the above example were ::css::my_stylesheet, then markup like this:

<LINK rel="stylesheet" href="::css::my_stylesheet">

would not work. The string "::css::my_stylesheet" is not a valid relative or absolute URI, so the results of resolving it against the base URI of the document, "tclvar:///my_document", are not defined. The solution is to escape the variable names using URI escapes. The Tkhtml3 package provides the [::tkhtml::encode] and [::tkhtml::decode] commands for escaping and unescaping strings, respectively. After modifying the -requestcmd proc to support escaped strings, it looks like this:

proc tclvar_requestcmd {R} {
  # Get the URI from the request handle. The URI should look 
  # something like:
  #
  #   tclvar:///<global varname>
  #
  set uri [$R cget -uri]

  # Strip "tclvar:///" from the start of the URI.
  set var [::thtml::decode [string range $uri 10 end]]

  # Return the data in the global variable $var to the widget.
  global $var
  $R finish [set $var]
}

This could be used with a script like this:

set my/document {
  <HTML>
    <LINK rel="stylesheet" href="%3A%3Acss%3A%3Amy_stylesheet">
    <BODY>
      <P>Some red text.</P>
    </BODY>
  </HTML>
}
namespace eval ::css {
  set my_stylesheet {
    P { color : red }
  }
}

::hv3::hv3 .hv3
pack .hv3 -fill both -expand true

.hv3 configure -requestcmd tclvar_requestcmd
.hv3 goto tclvar:///[::tkhtml::encode my/document]

In this case the two invocation of tclvar_requestcmd are made with request handle arguments with the following -uri option values:

tclvar:///my%2Fdocument
tclvar:///%3A%3Acss%3A%3Amy_stylesheet

Other custom URI scheme handlers could retrieve data by evaluating Tcl scripts, querying a database or accessing any other part of the application.