Provided by: tk-html3_3.0~fossil20110109-8_amd64 bug

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:

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

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
              Returns the current value of the configuration option given by option.  Option  may
              have any of the values accepted by the [hv3] command.

       pathName configure ?option? ?value?
              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.

       pathName goto uri
              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).

       pathName stop
              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.

       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.

   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.

       The cannonical test to check if a given request is a POST or GET request is:

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

       For POST requests, this option may be set by the Hv3 widget to contain the Content-Type of
       the data stored in the -postdata option. For example "application/x-www-form-urlencoded".
        .RE

       Command-Line Name:-header
        .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.

       The user code may set this option to a list containing data  to  be  handled  by  the  hv3
       widget  as  if  it  had  been  returned  as  the HTTP header for an HTTP request. The list
       consists of alternating HTTP header-names and values. This  is  the  same  format  as  the
       "meta" element of the "state array" interface used by Tcl"s built-in http package.

       The Hv3 widget interprets the following HTTP headers:

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

       If  the  user  code knows the mime type of the resource being returned, it should set this
       option before the first invocation of the [append] method. Useful values recognized by the
       hv3 widget include "text/xhtml" and "image/gif".
        .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.

       It contains the data to be posted.
        .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).

       The user code should not change the value of this option.
        .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.

       The user code should not change the value of this option.
        .RE

   REQUEST HANDLE METHODS
       requestHandle append data
              This 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.

       requestHandle finish
              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.

       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.

                                         Sat Feb 25 2006                                hv3(3tcl)