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

NAME

       tkhtml - Widget to render html documents.

SYNOPSIS

       html pathName ?options?

STANDARD OPTIONS

              -height
              -width
              -xscrollcommand
              -xscrollincrement
              -yscrollcommand
              -yscrollincrement

       See the options(n) manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

       Command-Line Name:-defaultstyle
        .br Database Name:  defaultstyle
        .br Database Class: Defaultstyle
        .br
        .RS
        .PP  This  option is used to set the default style-sheet for the widget. The option value
       should be the entire text of the default style-sheet.

       The default stylesheet defines things that are "built-in" to the document  -  for  example
       the behaviour of <p> or <img> tags in html. The idea behind making it flexible is to allow
       Tkhtml to display anything that looks roughly like an XML document. But this will not work
       at the moment because of other assumptions the implementation makes about the set of valid
       tags. Currently, only valid HTML tags are recognized.

       The Tkhtml package adds the [::tkhtml::htmlstyle] command to the interpreter it is  loaded
       into.  Invoking  this  command  returns  a  CSS  document suitable for use with Tkhml as a
       default  stylesheet  for  HTML  documents.  If   the   -quirks   option   is   passed   to
       [::tkhtml::htmlstyle]  then  the  returned  document  includes  some extra rules used when
       rendering legacy documents.

       If the value of the -defaultstyle option is changed, the new value does  not  take  effect
       until after the next call to the widget [reset] method.

       The   default   value  of  this  option  is  the  same  as  the  string  returned  by  the
       [::tkhtml::htmlstyle] command.
        .RE Command-Line Name:-fontscale
        .br Database Name:  fontscale
        .br Database Class: Fontscale
        .br
        .RS
        .PP This option is set to a floating point number, default 1.0.  After CSS algorithms are
       used  to determine a font size, it is multiplied by the value of this option. Setting this
       to a value other than 1.0 breaks standards compliance.
        .RE Command-Line Name:-fonttable
        .br Database Name:  fonttable
        .br Database Class: Fonttable
        .br
        .RS
        .PP This option must be set to a list of 7 integers. The first integer  must  be  greater
       than 0 and each subsequent integer must be greater than or equal to its predecessor.

       The  seven integers define the sizes of the Tk fonts (in points) used when a CSS formatted
       document requests font-size "xx-small", "x-small", "small", "medium",  "large",  "x-large"
       or "xx-large", respectively.

       The default value is {8 9 10 11 13 15 17}.
        .RE Command-Line Name:-forcefontmetrics
        .br Database Name:  forcefontmetrics
        .br Database Class: Forcefontmetrics
        .br
        .RS
        .PP  This  is  a  boolean option. If true, the font-metrics returned by Tk are overridden
       with calculated values based on the font requested. This improves CSS  compatibility,  but
       on some systems may cause problems. The default is true.
        .RE Command-Line Name:-forcewidth
        .br Database Name:  forcewidth
        .br Database Class: Forcewidth
        .br
        .RS
        .PP  When  determining the layout of a document, Tkhtml3 (and all other HTML/CSS engines)
       require as an input the width of the containing block for the  whole  document.  For  web-
       browsers,  this  is  usually  the  width  of  the  viewport  in which the document will be
       displayed.

       If this option is true or the widget window is not mapped, Tkhtml3 uses the value  of  the
       -width  option  as  the initial containing block width. Otherwise, the width of the widget
       window is used.

       The default value is false.
        .RE Command-Line Name:-imagecache
        .br Database Name:  imagecache
        .br Database Class: Imagecache
        .br
        .RS
        .PP This boolean option (default true) determines  whether  or  not  Tkhtml3  caches  the
       images  returned  to  it  by the -imagecmd callback script. If true, all images are cached
       until the next time the [reset] sub-command is invoked. If false, images are discarded  as
       soon as they are not in use.

       For simple applications, or applications that retrieve images from local sources, false is
       usually a better value for this option (since it may save memory). However for web-browser
       applications  where  the background images of elements may be modified by mouseover events
       and so on, true is a better choice.
        .RE Command-Line Name:-imagecmd
        .br Database Name:  imagecmd
        .br Database Class: Imagecmd
        .br
        .RS
        .PP As well as for replacing entire document nodes  (i.e.  <img>),  images  are  used  in
       several  other  contexts  in  CSS  formatted  documents,  for  example  as list markers or
       backgrounds. If the
        -imagecmd option is not set to an empty string (the default), then each time an image URI
       is  encountered  in the document, it is appended to the -imagecmd script and the resulting
       list evaluated.

       The command should return either an empty string, the name of a Tk image,  or  a  list  of
       exactly  two  elements,  the  name  of  a Tk image and a script. If the result is an empty
       string, then no image can be displayed. If the result is a Tk image name, then  the  image
       is  displayed  in  the widget. When the image is no longer required, it is deleted. If the
       result of the command is a list containing a Tk image name and a script, then  instead  of
       deleting the image when it is no longer required, the script is evaluated.

       If  the size or content of the image are modified while it is in use the widget display is
       updated automatically.
        .RE Command-Line Name:-mode
        .br Database Name:  mode
        .br Database Class: Mode
        .br
        .RS
        .PP This option may be set to "quirks", "standards" or "almost  standards",  to  set  the
       rendering engine mode. The default value is "standards".

       TODO: List the differences between the three modes in Tkhtml.
        .RE Command-Line Name:-parsemode
        .br Database Name:  parsemode
        .br Database Class: Parsemode
        .br
        .RS
        .PP  This  option  may  be  set  to "html", "xhtml" or "xml", to set the parser mode. The
       default value is "html".

       In "html" mode, the parser attempts to mimic the tag-soup  approach  inherited  by  modern
       web-browsers  from  the bad old days. Explicit XML style self-closing tags (i.e. closing a
       markup tag with "/>" instead of ">") are not handled specially. Unknown tags are ignored.

       "xhtml" mode is the same as  "html"  mode  except  that  explicit  self-closing  tags  are
       recognized.

       "xml"  mode  is  the  same  as  "xhtml"  mode  except that unknown tag names and XML CDATA
       sections are recognized.
        .RE Command-Line Name:-shrink
        .br Database Name:  shrink
        .br Database Class: Shrink
        .br
        .RS
        .PP This boolean option governs the way  the  widgets  requested  width  and  height  are
       calculated.  If  it is set to false (the default), then the requested width and height are
       set by the -width and -height options as per usual.

       If this option is set to true, then the widgets requested width and height are  determined
       by  the  current  document.  Each  time  the  document  layout  is calculated, the widgets
       requested height and width are set to the size of the document layout. If  the  widget  is
       unmapped  when  the  layout  is calculated, then the value of the -width option is used to
       determine the width of the initial containing block for the layout. Otherwise, the current
       window width is used.
        .RE Command-Line Name:-zoom
        .br Database Name:  zoom
        .br Database Class: Zoom
        .br
        .RS
        .PP  This  option  may be set to any floating point number. Before the document layout is
       calculated,  all  lengths  and  sizes  specified  in  the  HTML  document  or  CSS   style
       configuration, implicit or explicit, are multiplied by this value.

       The default value is 1.0.
        .RE Command-Line Name:-logcmd
        .br Database Name:  logcmd
        .br Database Class: Logcmd
        .br
        .RS
        .PP  This  option  is  used  for  debugging  the  widget.  It is not part of the official
       interface and may be modified or removed at any time. Don"t worry about it.
        .RE Command-Line Name:-timercmd
        .br Database Name:  timercmd
        .br Database Class: Timercmd
        .br
        .RS
        .PP This option is used for debugging  the  widget.  It  is  not  part  of  the  official
       interface and may be modified or removed at any time. Don"t worry about it.
        .RE Command-Line Name:-layoutcache
        .br Database Name:  layoutcache
        .br Database Class: Layoutcache
        .br
        .RS
        .PP  This  option  is  used  for  debugging  the  widget.  It is not part of the official
       interface and may be modified or removed at any time. Don"t worry about it.

       If this boolean option is set to true, then Tkhtml caches layout  information  to  improve
       performance when the layout of a document must be recomputed. This can happen in a variety
       of situations, for example when extra text is appended to the document,  a  new  style  is
       applied  to  the  document,  a dynamic CSS selector (i.e. :hover) is activated, the widget
       window is resized, or when the size of an embedded image or Tk window changes.

       Layout caching consumes no extra memory or significant processing cycles, so in  an  ideal
       world there is no real reason to turn it off. But it can be a source of layout bugs, hence
       this option.

       The default value is true.
        .RE

DESCRIPTION

       The [html] command creates a new window (given by the pathName argument) and makes it into
       an  html  widget. The html 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.

WIDGET COMMAND

       The  [html]  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 bbox nodeHandle
              If node nodeHandle generates content, this command returns a list of four  integers
              that  define  the  bounding-box  of the generated content, relative to the top-left
              hand corner of the rendered document. The first  two  integers  are  the  x  and  y
              coordinates of the top-left corner of the bounding-box, the later two are the x and
              y coordinates of the bottom-right corner of the same box.  If  the  node  does  not
              generate content, then an empty string is returned.

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

       pathName fragment html-text
              TODO: Document this command.

       pathName handler node tag script
       pathName handler attribute tag script
       pathName handler script tag script
       pathName handler parse tag script
              This command is used to define "handler" scripts - Tcl callback  scripts  that  are
              invoked  by  the  widget when document elements of specified types are encountered.
              The widget supports two types of handler scripts: "node" and "script".

              For a "node" handler script, whenever a document element having the  specified  tag
              type  (e.g.  "p" or "link") is encountered during parsing, then the node handle for
              the node is appended to script and the resulting list evaluated as a  Tcl  command.
              See  the  section  "NODE  COMMAND"  for details of how a node handle may be used to
              query and manipulate a document node. A node  handler  is  called  only  after  the
              subtree rooted at the node has been completely parsed.

              If  the  handler script is a "script" handler, whenever a document node of type tag
              is parsed, two arguments  are  appended  to  the  specified  script  before  it  is
              evaluated.   The  first  argument  is a key-value list (suitable for passing to the
              [array set] command containing the HTML attributes that were part  of  the  element
              declaration. The second argument is the literal text that appears between the start
              and end tags of the element.

              Elements for which a "script" handler is evaluated are not included in  the  parsed
              form  of the HTML document. Instead, the result of the script handler evaluation is
              substituted into the document and parsed. For  example,  to  handle  the  following
              embedded javascript:

                     <SCRIPT>
                       document.write("<p>A paragraph</p>")
                     </SCRIPT>

              a  script  handler  that returns the string "<p>A paragraph</p>" must be configured
              for nodes of type "SCRIPT".

              Unlike node or script handlers, a "parse" handler may be associated with a specific
              opening  tag, a closing tag or with text tags (by specifying an empty string as the
              tag type). Whenever such a tag is encountered the parse handler script  is  invoked
              with  two  arguments, the node handle for the created node and the character offset
              of the in the parsed document. For a closing tag (i.e. "/form") an empty string  is
              passed instead of a node handle.

              TODO: Describe "attribute" handlers.

              TODO:  The  offset  values passed to parse handler scripts currently have problems.
              See http://tkhtml.tcl.tk/cvstrac/tktview?tn=126

              Handler callbacks are always  made  from  within  [pathName  parse]  commands.  The
              callback  for  a given node is made as soon as the node is completely parsed.  This
              can happen because an implicit or explicit closing tag is parsed, or because  there
              is  no  more document data and the -final switch was passed to the [pathName parse]
              command.

              TODO: Return values of handler scripts? If an exception occurs in a handler script?

       pathName image
              This command returns the name of a new Tk image containing the  rendered  document.
              Where Tk widgets would be mapped in a live display, the image contains blank space.

              The  returned  image  should  be  deleted when the script has finished with it, for
              example:

                     set img [.html image]
                     # ... Use $img ...
                     image delete $img

              This command is included mainly for automated testing and should be used with care,
              as  large documents can result in very large images that take a long time to create
              and use vast amounts of memory.

              Currently this command is not available on  windows.  On  that  platform  an  empty
              string is always returned.

       pathName node ? ?-index? x y?
              This command is used to retrieve one or more document node handles from the current
              document. If the x and y parameters are omitted, then the handle  returned  is  the
              root-node  of  the  document,  or  an empty string if the document has no root-node
              (i.e. an empty document).

              If the x and y arguments are present, then a list of node handles is returned.  The
              list  contains one handle for each node that generates content currently located at
              viewport coordinates (x, y). Usually this is only a single node, but floating boxes
              and  other  overlapped content can cause this command to return more than one node.
              If no content is located at the specified coordinates or the widget window  is  not
              mapped, then an empty string is returned.

              If  the -index option is specified along with the x and y coordinates, then instead
              of a list of node handles, a list of two elements is returned. The first element of
              the  list  is  the  node-handle  associated  with the generated text closest to the
              specified (x, y) coordinates. The second list  value  is  a  byte  (not  character)
              offset  into  the text obtainable by [nodeHandle text] for the character closest to
              coordinates (x, y). The index may be used with the [pathName tag] commands.

              The document node can be queried and manipulated using the interface  described  in
              the "NODE COMMAND" section.

       pathName parse ?-final? html-text
              Append  extra  text to the end of the (possibly empty) document currently stored by
              the widget.

              If the -final option is present, this indicates that the supplied text is the  last
              of the document. Any subsequent call to [pathName parse] before a call to [pathName
              reset] will raise an error.

              If the -final option is not passed to [pathName parse] along with the final part of
              the  document  text, node handler scripts for any elements closed implicitly by the
              end of the document will not be executed. It is not an error to  specify  an  empty
              string for the html-text argument.

       pathName preload uri
              This  command  is  only  useful  if  the  -imagecache  option is set to true and an
              -imagecmd script is defined. It causes the widget to invoke the -imagecmd script to
              retrieve  the image at URI uri. Assuming -imagecache is true, the returned image is
              then stored in the image-cache.

              This command may be useful when implementing scripting  environments  that  support
              "preloading" of images.

       pathName reset
              This  is  used  to clear the internal contents of the widget prior to parsing a new
              document. The widget is reset such that the document tree is empty (as if no  calls
              to  [pathName  parse]  had  ever  been  made) and no stylesheets except the default
              stylesheet are loaded (as if no invocations of [pathName style] had occured).

       pathName search selector
              The selector argument passed to this command must be  a  valid  CSS  selector,  for
              example   "h1"   or   "a[href]".  This  command  returns  a  list  of  node-handles
              corresponding to the set of document nodes that match the supplied selector.

       pathName style ?options? stylesheet-text
              Add a  stylesheet  to  the  widgets  internal  configuration.  The  stylesheet-text
              argument  should contain the text of a complete stylesheet.  Incremental parsing of
              stylesheets is not supported, although of course multiple stylesheets may be  added
              to a single widget.

              The following options are supported:

                     Option                   Default Value
                     --------------------------------------
                     -id <stylesheet-id>      "author"
                     -importcmd <script>      ""
                     -urlcmd    <script>      ""

              The  value  of the -id option determines the priority taken by the style-sheet when
              assigning property values to document nodes (see chapter 6 of the CSS specification
              for more detail on this process).  The first part of the style-sheet id must be one
              of the strings "agent", "user" or "author". Following this, a  style-sheet  id  may
              contain any text.

              When  comparing  two  style-ids  to  determine which stylesheet takes priority, the
              widget uses the following approach: If the initial  strings  of  the  two  style-id
              values  are not identical, then "user" takes precedence over "author", and "author"
              takes precedence over "agent".  Otherwise,  the  lexographically  largest  style-id
              value  takes  precedence.   For  more  detail on why this seemingly odd approach is
              taken, please refer to the "STYLESHEET LOADING" below.

              The -importcmd option is used to provide a handler script  for  @import  directives
              encountered  within  the  stylesheet  text.  Each  time  an  @import  directive  is
              encountered, if the -importcmd option is set to other than an empty string, the URI
              to  be imported is appended to the option value and the resulting list evaluated as
              a Tcl script. The return value of the script is ignored. If the  script  raises  an
              error, then it is propagated up the call-chain to the [pathName style] caller.

              The -urlcmd option is used to supply a script to translate "url(...)" CSS attribute
              values. If this option is not set to "", each time a url() value is encountered the
              URI  is  appended  to  the value of -urlcmd and the resulting script evaluated. The
              return value is stored as the URL in the parsed stylesheet.

       pathName tag add tag-name node1 index1 node2 index2
       pathName tag remove tag-name node1 index1 node2 index2
       pathName tag configure tag-name option value ?option value...?
       pathName tag delete tag-name
              The [pathName tag] command is used to highlight regions of text  displayed  by  the
              widget. For example, a region of text selected using the pointer.

              Each  displayed  document character is identified by a text node-handle (see below)
              and an index into the text returned by the [node text] command. The index is a byte
              (not  character)  offset. See also the documentation for the [pathName node -index]
              command.   Both  the  [pathName  tag  add]  and  [pathName  tag  remove]  use  this
              convention.

              Evaluating  the  [pathName tag add] command adds the specified tag to all displayed
              characters between the point in the document described by (node1, index1)  and  the
              point  described  by  (node2,  index2).  If the specified tag does not exist, it is
              created with default option values. The order in which  the  two  specified  points
              occur in the document is not important.

              The  [pathName  tag  remove]  command  removes the specified tag from all displayed
              characters between the point in the document described by (node1, index1)  and  the
              point described by (node2, index2).

              The  [pathName  tag  configure]  command is used to configure a tags options, which
              determine how tagged characters are displayed. If the specified tag does not exist,
              it is created. The following options are supported:

                     Option                   Default Value
                     --------------------------------------
                     -background              black
                     -foreground              white

              A  tag  can be completely deleted (removed from all characters and have it"s option
              values set to the defaults) using the [pathName tag delete] command.

              The [pathName tag] command replaces the [pathName select] command that was  present
              in early alpha versions of Tkhtml3. Users should note that the options supported by
              [pathName tag configure] are likely to change before beta release. See
                              http://tkhtml.tcl.tk/cvstrac/tktview?tn=73 (ticket #73).

       pathName text bbox node1 index1 node2 index2
       pathName text index offset ?offset...?
       pathName text offset node index
       pathName text text
              The [pathName text] commands allow an application to query and  interact  with  the
              text  of  the  displayed  document.  This can be used, for example, to search for a
              string within an Html document,  or  to  copy  a  region  of  text  to  the  system
              clipboard.

              The  [pathName  text text] command returns a string containing the raw, unformatted
              text of the displayed document.  Each block box is separated from  the  next  by  a
              newline  character. Each block of whitespace is collapsed to a single space, except
              within blocks with the CSS "white-space" property set to "pre".

              The [pathName text index] command is used to transform from a character  offset  in
              the  string  returned by [pathName text text] to a node/index pair that can be used
              with the [pathName tag] commands. The return value is a list of two  elements,  the
              node-handle followed by the index.

              Command  [pathName  text  offset]  is the reverse of [pathName text index]. Given a
              node-handle and index of the type similar  to  that  used  by  the  [pathName  tag]
              commands,  this  command  returns  the corresponding character offset in the string
              returned by [pathName text text] command.

       pathName write continue
       pathName write text html-text
       pathName write wait
              TODO

       pathName xview
       pathName xview moveto fraction
       pathName xview scroll number what
              This command is used to query or adjust the horizontal  position  of  the  viewport
              relative  to  the document layout.  It is identical to the [pathName xview] command
              implemented by the canvas and text widgets.

       pathName yview
       pathName yview moveto fraction
       pathName yview scroll number what
       pathName yview nodeHandle
              This command is used to query or adjust  the  vertical  position  of  the  viewport
              relative  to  the  document layout.  It supports a superset of the [pathName yview]
              interface implemented by the canvas and text widgets.

              As well as the standard interface copied from the canvas and text  widgets,  Tkhtml
              supports  passing a single node-handle as the only argument to [pathName yview]. In
              this case the viewport is scrolled so  that  the  content  generated  by  the  node
              nodeHandle  is  visible.  This  can  be  useful  for  implementing  support for URI
              fragments.

NODE COMMAND

       There are several interfaces by which a script can obtain  a  "node  handle".   Each  node
       handle is a Tcl command that may be used to access the document node that it represents. A
       node handle is valid from the time it is obtained until the next call to [pathName reset].
       The  node  handle  may be used to query and manipulate the document node via the following
       subcommands:

       nodeHandle attribute ??-default default-value? ?attribute? ?new-value??
              If the attribute argument is present, then return  the  value  of  the  named  html
              attribute.  If  the  attribute  is  not  defined  for  the node, then a copy of the
              default-value argument is returned instead. If no  -default  option  was  specified
              (and  hence  there  is  no default-value argument) and the named attribute does not
              exist, an error is raised.

              If the new-value argument is present, then set the named
                              attribute to the specified new-value.

              If no attribute argument is  present,  return  a  key-value  list  of  the  defined
              attributes of the form that can be passed to [array set].

                     # Html code for node
                     <p class="normal" id="second" style="color : red">

                     # Value returned by [nodeHandle attr]
                     {class normal id second style {color : red}}

                     # Value returned by [nodeHandle attr class]
                     normal

       nodeHandle children
              Return  a  list of node handles for all children of nodeHandle.  The leftmost child
              node becomes element 0 of the list, the second leftmost element 1, and so on.

       nodeHandle destroy
              TODO. Experimental.

       nodeHandle dynamic set ?flag?
       nodeHandle dynamic clear ?flag?
              Set or clear a dynamic flag on a node.

              The supported values for the flag argument are "active", "hover",  "focus",  "link"
              and  "visited".  The  status  of  each  dynamic  flag determines whether or not the
              corresponding CSS dynamic pseudo-classes are considered  to  match  the  node.  For
              example, when the mouse moves over node $N, a script could invoke:

                     $N dynamic set hover
              Or possibly, if $PN were the node the mouse hovered over previously:

                     for {set n $PN} {$n ne ""} {set n [$n parent]} {
                             $n dynamic clear hover
                     }
                     for {set n $N} {$n ne ""} {set n [$n parent]} {
                             $n dynamic set hover
                     }

       nodeHandle insert ?-before node? node-list
              TODO. Experimental.

       nodeHandle override ?value?
              TODO. Experimental.

       nodeHandle parent
              Return  the  node  handle for the node"s parent. If the node does not have a parent
              (i.e. it is the document root), then return an empty string.

       nodeHandle property ?-before|-after? ?property-name?
              TODO.

       nodeHandle remove ?node-list?
              TODO.

       nodeHandle replace ? ?options? newValue?
              This command is used to set and get the name of  the  replacement  object  for  the
              node, if any. If the newValue argument is present, then this command sets the nodes
              replacement object name and returns the new value. If newValue is not present, then
              the current value is returned.

              A  nodes  replacement  object  may  be  set  to the name of a Tk window or an empty
              string. If it is an empty string (the default and usual case),  then  the  node  is
              rendered  normally.   If  the  node  replacement  object is set to the name of a Tk
              window, then the Tk window is mapped into the widget in place of any other  content
              (for example to implement form elements or plugins).

              The following options are supported:

                     Option                   Default Value
                     --------------------------------------
                     -deletecmd    <script>   ""
                     -configurecmd <script>   ""
                     -stylecmd     <script>   ""

              When  a  replacement object is no longer being used by the widget (e.g. because the
              node has been deleted or [pathName reset] is invoked), the value of the  -deletecmd
              option is evaluated as Tcl script.

              If  it  is  not  set  to  an  empty  string  (the  default) each time the nodes CSS
              properties are recalculated, a serialized array is appended to  the  value  of  the
              -configurecmd  option  and the result evaluated as a Tcl command. The script should
              update the replacement objects appearance where appropriate to reflect the property
              values. The format of the appended argument is {p1 v1 p2 v2 ... pN vN} where the pX
              values are property names (i.e. "background-color") and the vX values are  property
              values  (i.e.  "#CCCCCC").  The CSS properties that currently may be present in the
              array are listed below. More may be added in the future.

                     background-color    color
                     font                selected

              The value of the "font" property, if present in the serialized array is not set  to
              the  value of the corresponding CSS property. Instead it is set to the name of a Tk
              font determined by combining the various font-related CSS properties.  Unless  they
              are  set  to  "transparent",  the  two  color  values are guaranteed to parse as Tk
              colors. The "selected" property is either true or false, depending  on  whether  or
              not  the  replaced object is part of the selection or not. Whether or not an object
              is part of the selection is governed by previous calls  to  the  [pathName  select]
              command.

              The -configurecmd callback is always executed at least once between the [nodeHandle
              replace] command and when the replaced object is mapped into the widget display.

       nodeHandle tag
              Return the name of the Html tag that generated this  document  node  (i.e.  "p"  or
              "link"), or an empty string if the node is a text node.

       nodeHandle text ?-tokens|-pre?
              If  the node is a "text" node, return the string contained by the node. If the node
              is not a "text" node, return an empty string.

              TODO: Document -tokens and -pre.

STYLESHEET LOADING

       Apart from the default stylesheet that is  always  loaded  (see  the  description  of  the
       -defaultstyle  option  above),  a  script  may  configure  the  widget  with  extra  style
       information in the form of CSS stylesheet documents. Complete stylesheet documents (it  is
       not  possible  to incrementally parse stylesheets as it is HTML document files) are passed
       to the widget using the [pathName style] command.

       As well as any stylesheets specified by the application, stylesheets may  be  included  in
       HTML documents by document authors in several ways:

              * Embedded  in  the  document  itself,  using a <style> tag. To handle this case an
                application script must register a "script" type handler for <style>  tags  using
                the  [pathName handler] command. The handler command should call [pathName style]
                to configure the widget with the stylesheet text.

              * Linked from the document, using a <link> tag. To handle this case the application
                script should register a "node" type handler for <link> tags.

              * Linked  from  another stylesheet, using the @import directive. To handle this, an
                application needs to configure the widget -importcommand option.

              # Implementations of application callbacks to load
              # stylesheets from the various sources enumerated above.
              # ".html" is the name of the applications tkhtml widget.
              # The variable $document contains an entire HTML document.
              # The pseudo-code <LOAD URI CONTENTS> is used to indicate
              # code to load and return the content located at $URI.

              proc script_handler {tagcontents} {
                  incr ::stylecount
                  set id "author.[format %.4d $::stylecount]"
                  set handler "import_handler $id"
                  .html style -id $id.9999 -importcmd $handler $tagcontents
              }

              proc link_handler {node} {
                  if {[node attr rel] == "stylesheet"} {
                      set URI [node attr href]
                      set stylesheet [<LOAD URI CONTENTS>]

                      incr ::stylecount
                      set id "author.[format %.4d $::stylecount]"
                      set handler "import_handler $id"
                      .html style -id $id.9999 -importcmd $handler $stylesheet
                  }
              }

              proc import_handler {parentid URI} {
                  set stylesheet [<LOAD URI CONTENTS>]

                  incr ::stylecount
                  set id "$parentid.[format %.4d $::stylecount]"
                  set handler "import_handler $id"
                  .html style -id $id.9999 -importcmd $handler $stylesheet
              }

               .html handler script style script_handler
               .html handler node link link_handler

              set ::stylecount 0

               .html parse -final $document

       The complicated part of the example code above is the generation  of  stylesheet-ids,  the
       values  passed  to the -id option of the [.html style] command. Stylesheet-ids are used to
       determine the precedence of each stylesheet passed to the widget, and the role it plays in
       the  CSS  cascade algorithm used to assign properties to document nodes. The first part of
       each stylesheet-id, which must be either "user", "author" or "agent", determines the  role
       the  stylesheet  plays  in  the  cascade  algorithm.  In  general, author stylesheets take
       precedence over user stylesheets which take precedence over agent stylesheets.  An  author
       stylesheet  is  one supplied or linked by the author of the document. A user stylesheet is
       supplied by the user of the viewing application, possibly  by  configuring  a  preferences
       dialog or similar. An agent stylesheet is supplied by the viewing application, for example
       the default stylesheet configured using the -defaultstyle option.

       The stylesheet id mechanism is designed so that the cascade can be  correctly  implemented
       even when the various stylesheets are passed to the widget asynchronously and out of order
       (as may be the case if they are being downloaded from a network server or servers).

              #
              # Contents of HTML document
              #

              <html><head>
                  <link rel="stylesheet" href="A.css">
                  <style>
                      @import uri("B.css")
                      @import uri("C.css")
                      ... rules ...
                  </style>
                  <link rel="stylesheet" href="D.css">
               ... remainder of document ...

              #
              # Contents of B.css
              #

              @import "E.css"
               ... rules ...

       In the example above, the stylesheet documents A.css, B.css, C.css, D.css, E.css  and  the
       stylesheet  embedded  in  the  <style> tag are all author stylesheets. CSS states that the
       relative precedences of the stylesheets in this case is governed by the following rules:

              * Linked, embedded or imported stylesheets take precedence over stylesheets linked,
                embedded or imported earlier in the same document or stylesheet.

              * Rules  specified in a stylesheet take precedence over rules specified in imported
                stylesheets.

       Applying the above two rules to the example documents indicates  that  the  order  of  the
       stylesheets  from  least  to  most  important  is:  A.css,  E.css,  B.css, C.css, embedded
       <stylesheet>, D.css. For the widget to implement the cascade correctly, the stylesheet-ids
       passed to the six [pathName style] commands must sort lexigraphically in the same order as
       the stylesheet precedence determined by the above two rules. The example code above  shows
       one  approach  to  this.  Using  the  example  code,  stylesheets would be associated with
       stylesheet-ids as follows:

              Stylesheet         Stylesheet-id
              -------------------------------
              A.css              author.0001.9999
              <embedded style>   author.0002.9999
              B.css              author.0002.0003.9999
              E.css              author.0002.0003.0004.9999
              C.css              author.0002.0005.9999
              D.css              author.0006.9999

       Entries are specified in the above table in the order in which the calls to  [html  style]
       would  be  made.  Of course, the example code fails if 10000 or more individual stylesheet
       documents are loaded.  More inventive solutions that avoid this  kind  of  limitation  are
       possible.

       Other  factors,  namely  rule  specificity  and  the  !IMPORTANT directive are involved in
       determining  the  precedence  of  individual  stylesheet  rules.  These   are   completely
       encapsulated  by  the  widget,  so are not described here. For complete details of the CSS
       cascade algorithm, refer to the CSS and CSS 2 specifications (www.w3.org).

ORPHAN NODES

                                         Sat Feb 25 2006                             tkhtml(3tcl)