NAME¶

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.

SYNOPSIS¶

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

DESCRIPTION¶

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:

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.

STANDARD OPTIONS¶

-height
-width

HTML OPTIONS¶

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

-fontscale
-fonttable
-forcefontmetrics
-zoom

HTML COMMANDS¶

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

node ? ?-index? x y?

WIDGET-SPECIFIC OPTIONS¶

Command-Line Name:-enableimages
.br Database Name: enableimages
.br Database Class: Enableimages
.br
.RS
.PP Boolean option (default true). True for image support, false otherwise. If this option is set to false, then the -requestcmd script will never be invoked to request an image resource.
.RE Command-Line Name:-isvisitedcmd
.br Database Name: isvisitedcmd
.br Database Class: Isvisitedcmd
.br
.RS
.PP If not an empty string, this option specifies a script for the widget to invoke to determine if a hyperlink (<A>) node should be styled with the :link or :visited pseudo-class. The script is invoked with the node handle appended to it. If true is returned, :visited is used, otherwise :link.
.RE Command-Line Name:-requestcmd
.br Database Name: requestcmd
.br Database Class: Requestcmd
.br
.RS
.PP If this option is not set by the user code, then the Hv3 widget will be unable to display anything.

It should be set to a script that may be invoked by the hv3 widget to request a resource required to display a URI requested via the [goto] method. Each time a resource is required, the -requestcmd script is invoked with a single argument appended to it, the name of a request handle object. See section "Request Handles" for details.
.RE Command-Line Name:-targetcmd
.br Database Name: targetcmd
.br Database Class: Targetcmd
.br
.RS
.PP If this option is not set to an empty string (the default), it should be set to a script that will be invoked each time a hyper-link is clicked or a form submitted in the hv3 widget by the end-user. A single argument is appended to the script before it is evaluated, the Tkhtml3 node-handle for the relevant <FORM> (in the case of form submittal) or <A> (if the end user clicked a hyperlink) node. The script should return the path of an hv3 widget into which the new resource should be loaded. This is useful for implementing browsers that support HTML frames and iframes.

If the script returns an empty string the request is abandoned and the new resource never loaded and the form data (if any) not submitted.

If the option is set to an empty string the new resource is always loaded into the hv3 widget itself.
.RE

WIDGET COMMAND¶

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

REQUEST HANDLES¶

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.

if {[$handle cget -postdata] ne ""} {


  # This is a POST request.
} else {


  # This is a GET request.
}

EXAMPLES¶

<HTML>


  <BODY>


    <IMG src="image.gif">


  </BODY>
</HTML>

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

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]
}

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

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

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]
}

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]

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