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

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, or an empty string, in which case a built-in default stylesheet (for HTML) is used.

At the moment, this option is not very useful. 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 it will not work at the moment because of other assumptions the implementation makes about the set of valid tags.

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.

This option is used for internally debugging the widget.

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.

If the handler script is a "script" handler, whenever a document node of type tag is parsed, then the text that appears between the start and end tags of the node is appended to script and the resulting list evaluated as a Tcl command.

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?

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.

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 an index into the text obtainable by [nodeHandle text] for the character closest to coordinates (x, y). The index may be used with the [pathName select] commands.

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

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.

TODO: Describe these commands.

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

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>   "destroy <window>"
-configurecmd <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.

• 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
}
set ::stylecount 0

#
# 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">
#
# Contents of B.css
#
@import "E.css"

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

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