other versions
other sections
hv3(3tcl) | hv3(3tcl) |
NAME¶
hv3 - Mega-widget building on Tkhtml.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.- *
- 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.
-requestcmd option. The [goto] method tells the widget to load the document identified by the specified absolute or relative URI.
-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.
.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.
.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:Returns the current value of the configuration
option given by option. Option may have any of the values accepted by the
[hv3] command.
Query or modify the configuration options of
the widget. If no option is specified, returns a list describing all of the
available options for pathName (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with no value, then the command
returns a list describing the one named option (this list will be identical to
the corresponding sublist of the value returned if no option is specified). If
one or more option-value pairs are specified, then the command modifies the
given widget option(s) to have the given value(s); in this case the command
returns an empty string. Option may have any of the values accepted by the
[hv3] command.
Load the resource at uri into the widget. If
uri is not an absolute URI, it is resolved with respect to the widget"s
current document URI (or <BASE> element contents, if
present).
Abandon all pending requests. All request
handle objects that are still outstanding are destroyed (it is an error to use
such a request handle after calling [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.REQUEST HANDLE OPTIONS¶
Command-Line Name:-enctype.br Database Name: enctype
.br Database Class: Enctype
.br
.RS
.PP This option is used by "POST" requests, which may be made by an hv3 widget if the loaded document contains a form and the end-user submits it. For a "GET" request (all other requests, the usual case) it is set to an empty string.
if {[$handle cget -postdata] ne ""} { # This is a POST request. } else { # This is a GET request. }
.RE
.br Database Name: header
.br Database Class: Header
.br
.RS
.PP The Hv3 widget sets this option to an empty string before passing the request handle to the user code.
- *
- TODO.
.RE Command-Line Name:-mimetype
.br Database Name: mimetype
.br Database Class: Mimetype
.br
.RS
.PP The Hv3 widget sets this option to the expected mime type of the resource requested.
.RE Command-Line Name:-postdata
.br Database Name: postdata
.br Database Class: Postdata
.br
.RS
.PP This option is used by "POST" requests, which may be made by an hv3 widget if the loaded document contains a form and the end-user submits it.
.RE Command-Line Name:-requestheader
.br Database Name: requestheader
.br Database Class: Requestheader
.br
.RS
.PP The Hv3 widget sets this option to a list of HTTP header-names and values to be handled as request parameters for an HTTP request (i.e. the "referrer" header).
.RE Command-Line Name:-uri
.br Database Name: uri
.br Database Class: Uri
.br
.RS
.PP This option is always set by the Hv3 widget before passing the request handle to the user code. It contains the absolute URI of the resource required by the widget.
.RE
REQUEST HANDLE METHODS¶
requestHandle append dataThis method should be invoked one or more
times to return data to the hv3 widget.
The data passed to this method should always be binary data. If the data is
actually text data for a document or stylesheet, it"s encoding is
determined based on either a HTTP header returned via the [header] option, or
a <meta> element in the header section of an HTML or XHTML
document. If neither of these are present, the assumed encoding is either the
document encoding in the case of linked CSS stylesheet, or the value returned
by [encoding system] for an HTML or XHTML document.
This method should be called after all data
has been obtained. The request handle object is deleted by the system from
within this call, so the object may not be used after this method has been
invoked.
EXAMPLES¶
CUSTOM URI SCHEMES¶
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.<HTML> <BODY> <IMG src="image.gif"> </BODY> </HTML>
$hv3 goto http://tkhtml.tcl.tk
-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] }
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
-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">
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]
Sun Nov 11 18:57:26 EST 2012 |