Interface Specification For The HTML Widget

This is a draft interface specification for the Tk HTML widget currently under development. Since it is still a draft, it is subject to change. Eventually, the interface will stabilize and this interface specification will morph into a manual page.

Configuration Options

`-appletcommand`	This option specifies the name of the Tcl procedure to invoke when the `<applet>...</applet>` tag sequence is seen. The html widget will append two arguments to the procedure before calling it. The first argument is the name of a widget that the callback should create to hold the applet. The second argument is a list of name/value pairs which are the arguments to the `<applet>` tag. The text between `<applet>` and `</applet>` is normally suppressed. However, if the `-appletcommand` option is set to the empty string, the `<applet>` tag is ignored and all text between `<applet>` and `</applet>` is displayed normally. "<embed>" is treated as an alias for "<applet></applet>".
`-background`	The background color for the widget. Note that the `<body bgcolor=...>` HTML tag does not automatically cause the widget to change its background color. If you want the background color to change in response to this HTML tag, then your Tcl script should intercept the `<body>` tag using the ```token handler`'' widget command (described below) and change the background color manually.
`-base`	The base URI for the current document. This should be set to the URI that was used to retrieve the document before parsing begins.
`-bd`	An alias for `-borderwidth`
`-bg`	An alias for `-background`
`-borderwidth`	The width of the 3-D border drawn around the parameter of the widget, in pixels.
`-cursor`	The cursor displayed when the pointer is positioned over the HTML widget. If {}, the cursor reverts to its default shape.
`-exportselection`
`-fontcommand`	The name of a TCL procedure that is used to convert HTML font names into TCL font names. A default built-in procedure is used if the value of this option is {}. When the HTML widget needs a new font, it calls this procedure with two arguments. This first argument is the font size expressed as an integer between 1 and 7. The standard size is 4. The second argument is a set of between 0 and 3 keywords drawn from the following set: "bold", "italic", and "fixed". If the "bold" keyword is present in the second argument, the font returned should be bold. If the "italic" keyword is present, the font should be italic. If the "fixed" keyword is present, the font should be fixed-width. The TCL procedure should return the name of the TCL font that the HTML widget will use to render the given HTML font. If the TCL procedure returns an empty string, then the built-in default procedure is used to determine the font. Examples: This is {4 {}}. `This is {4 fixed}`. This is {3 {}}. `This is {5 {fixed bold}}`
`-fg`	An alias for `-foreground`.
`-foreground`	The default foreground color in which HTML text is rendered. The HTML can override this using the `color=...` attribute on various HTML tags.
`-formcommand string`	Declares a handler for everything to do with forms within a document. Arguments will be appended to `string` and the result evaluated during parsing (for form creation) and when the widget is cleared (for form cleanup). The first argument is a token for identifying a form. The second argument selects the action to perform. The remaining arguments depend on the action, as follows. `string token form URL method attrs` The handler should begin taking notes for form `token`, especially the (resolved) `URL` of the action and the `method` to be applied. The raw attributes of the FORM element are in the pairlist `attrs`. `string token flush` When the document is cleared, the widget will destroy all the windows it requested. This handler should clean up anything else it created for that form. `string token input path attrs` The handler should create a window named `path` appropriate for the element described by the `attrs`. The widget will map the window into its rendering appropriately. It is not an error for the handler to return without creating such a window (it's natural in the case of type=hidden); the widget simply ignores the element in that case. The attributes are the raw values in the HTML, with one exception; a `src` will be resolved before the handler is called. `string token textarea path attrs initial` The handler should create a window (a single Text, or a Frame with Text and Scrollbars, or whatever) appropriate for a <textarea> and initialise it to the `initial` string. `string token select path attrs choices initial` <select> is quite a complicated case... The handler should create a window appropriate for a <select> of the given attributes and present the list of `choices`. Each choice is a pair, the value and its label. `initial` is a list of values initially selected. This approach is somewhat questionable but should do most of the time. Caution: Be very careful to avoid confusing HTML variables with TCL variables. It may be tempting to use the `name` attribute fairly directly to link together related widgets, but it will likely cause incorrect behaviours. Also be careful to observe the order in which the elements are created; this determines the order in which they must be submitted. A default form handler with the correct bahaviour written in TCL will be bundled with the widget. The attribute names will be downcased within `attrs`.
`-framecommand`	The script specified by this option is invoked when the HTML parser encounters a `<frameset>...</frameset>` tag sequence. The arguments to the script are TBD. If the value of the option is the empty string, then the text within the `<noframe>...</noframe>` tag sequence is displayed.
`-height`	Specifies the height of the area into which HTML is rendered. This value plus twice the `-padx`, `-borderwidth` and `-highlightthickness` values is the total height of the widget.
`-highlightbackground`
`-highlightcolor`
`-highlightthickness`
`-hyperlinkcommand`	The script specified by this option is invoked whenever the user clicks on a hyperlink on the HTML page. Before invoking this script, the URI for the hyperlink is appended.
`-imagecommand`	When a ```<img src=...>`'' tag is encountered, the HTML widget invokes the script specified by this option in order to get the name of a Tk image object to display the HTML image. Before invoking the script, the following arguments are appended: The value of the `src=...` parameter after have been processed by the resolver. The value of the `width=...` parameter. The value of the `height=...` parameter. A list containing the names and values of all parameters. If the name returned by this script is the empty string, or if the script is an empty string, then the HTML widget displays the `alt=...` text of the `<img>` tag instead of an image.
`-isvisitedcommand`	When the HTML widget encounters a hyperlink (```<a href=...>`'') it invokes the script specified by this option in order to determine whether or not the hyperlink has been visited. This information is needed to determine what color to use to display the hyperlink.
`-padx`	The amount of extra space to insert between the 3-D border and the left and right sides of the document text.
`-pady`	The amount of extra space to insert between the 3-D border and the top and bottom of the document text.
`-relief`	The relief used to draw the 3-D border.
`-resolvercommand`	The name of a TCL command used to resolve URIs. If blank, a built-in resolver is used. If a TCL command is specified but it returns an empty string, the built-in resolver is used then too. The build-in resolver is based on the algorithm in section 5.2 of RFC 2396. Multiple URIs are appended to the TCL command before it is executed. The first URI is the BASE URI of the document (the URL that specified by the -base configuration option and updated according to any prior <BASE> markup). Zero or more additional URIs are appended to this base. The result of the script should be the resolution of the whole series or URIs.
`-rulerelief`	Determines the appearance of the Horizontal Rule (<HR>) markup. The default is "sunken". This can also be "raised" or "flat". If "flat", then the <HR> is drawn using a solid line in the current foreground color. "groove" and "ridge" are the same as "flat".
`-scriptcommand`	Whenever <SCRIPT>...</SCRIPT> markup is encountered in the input HTML, the attributes of the <SCRIPT> markup and the body of the script are appended to this string and the result is executed as a TCL command. If this options is the empty string, then the script is ignored.
`-selectioncolor`	The background color used when drawing the selection. The foreground color for the selection is the same as the regular foreground color.
`-tablerelief`	Determines the appearance of the borders around tables. The default is "raised". This can also be "sunken" or "flat". If "flat", then the borders is drawn using solid lines in the current foreground color. "groove" and "ridge" are the same as "flat".
`-takefocus`
`-unvisitedcolor`	The foreground color used to draw hyperlinks that have not been visited.
`-underlinehyperlinks`	Set to TRUE to cause hyperlinks to be drawn using an underlined font.
`-visitedcolor`	The foreground color used to draw hyperlinks that have been visited.
`-width`	The width of the document text. This value does not include space allocated for `-highlightthickness`, `-borderwiddth` or `-padx`.
`-xscrollcommand`
`-yscrollcommand`

Indices

Internally, the HTML widget stores the HTML document as a list of tokens. Each token is either

a contiguous sequence of non-space characters (Text),
a contiguous sequence of spaces, tabs or newlines (Space),
or an HTML markup tag (such as ``<em>''.)

Tokens are identified by number. The first token is ``1'', the second is ``2'' and so forth. So in its simplest form, an index is just an integer greater than 0.

Within a single Text or Space token, individual characters are also identified by number, though the counting starts with 0 instead of 1. The character number is connected to the token number by a period. So, for example, the 4th character in the 9th token would be ``9.3''.

Two integers separated by a dot is called the connonical form of an index. Other index forms are available, including:

end The keyword ``end'' means one character past the last character of the last token.
@X,Y The character located at screen coordinates X,Y.
*.last The second integer can be replaced by the keyword ``last'' to mean the last character in the token.
sel.first This is the first character that is part of the selection.
sel.last This is the last character that is part of the selection.
ins The character immediately following the insertion cursor.

Commands

html window ?options ...?

Create a new HTML widget instance named windows

html reformat from to text

Convert text from one encoding to another. The text is given in the text argument. The current encoding of the text is specified by the from argument. This command returns the same text in the to encoding.

From and to may be any of the following values:

plain Ordinary text with no characters escaped.

http The text is encoded in a form suitable for use with the HTTP protocol. Spaces are converted to "+". Special characters and escaped as "%aa" where "a" is a hexadecimal digit. A special character is anything other than an alphanumeric or one of these: ".", "$", "-", or "_".

url The text is encoded in a form suitable for use as a URI. Spaces are converted to "+". Special characters and escaped as "%aa" where "a" is a hexadecimal digit. A special character is anything other than an alphanumeric or one of these: ".", "$", "-", "_", or "/".

html The text is encoded in a form suitable for use within HTML. "&" is encoded as "&", "<" is encoded as "<" and so forth.

This command is intended to be useful to the TCL procedures that implement callbacks for the HTML widget.

html uri join scheme authority path query fragment

This command takes the five main components of a URI and joins them together into a complete URI. Special characters in any component are escaped.

html uri split uri

This command takes a single URI and splits it into its five major components: scheme, authorithy, path, query and fragement. The command returns a list where each component is an element of the list. Components missing from the URI are represented as empty elements in the list.

Widget Commands

WIDGET cget config-option

Return the value of a configuration option. Works just like any other Tk widget.

WIDGET clear

Remove all tokens and text from the HTML widget. The parser is reset to its initial state. This routine should be called to changes pages.

WIDGET configure ?args...?

The standard Tk configuration command.

WIDGET href X Y

If the coordinates X Y define a point above a hyperlink, then this command will return the target URL for that hyperlink. The URL will be resolved using the -resolvercommand before it is returned.

WIDGET index INDEX ?COUNT UNITS?

Translates INDEX into its connonical form. The connonical form of an index is two integers separated by a period.

The optional 3rd and 4th arguments specify a displacement from INDEX to the value of the index returned. COUNT can be any integer value, including a negative number. UNITS must be either ``char'' or ``line''.

WIDGET insert INDEX

Causes the insertion cursor (a flashing vertical bar) to be positioned immediately before the character specified by INDEX.

WIDGET names

This command causes the widget to scan the entire text of the document looking for tags of the form ``<a name=...>''. It returns a list of values of the name=... fields.

The vertical position of the document can be moved to any of these names using the ``WIDGET yview NAME'' command described below.

WIDGET parse HTML-TEXT

Adds the given HTML text to the end of any text previously received through the parse command and parses as much of the text as possible into tokens. Afterwards, the display is updated to show the new tokens, if they are visible.

WIDGET resolver ?uri ...?

The resolver specified by the -resolvercommand option is called with the base URI of the document followed by the remaining arguments to this commant. The result of this command is the result of the -resolvercommand script.

WIDGET selection subcommand args...

The selection widget command is used to control the selection.

WIDGET selection clear: Clear the current selection. No text will be selected after this command executes.
WIDGET selection set START END: Change the selection to be all text contained within the given indices.

WIDGET text subcommand args...

There are several token commands. They all have the common property that they directly manipulate the text that is displayed. These commands (none of which are currently implemented) can be used to build an WYSIWYG editor for HTML.

WIDGET text ascii INDEX-1 INDEX-2

Returns plain ASCII text that represents all characters between INDEX-1 and INDEX-2. Formatting tags are omitted. The INDEX-1 character is included by INDEX-2 is omitted.

WIDGET text delete INDEX-1 INDEX-2

All text from INDEX-1 up to, but not including INDEX-2 is removed and the display is updated accordingly.

WIDGET text html INDEX-1 INDEX-2

Returns HTML text that represents all characters and formatting tags between INDEX-1 and INDEX-2. The INDEX-1 character is included by INDEX-2 is omitted.

WIDGET text insert INDEX TEXT

Inserts one or more characters immediately before the character whose index is given.

WIDGET token subcommand args...

There are several token commands. They all have the common property that they involve the list of tokens into which the HTML is parsed.

Some of the following subcommands make use of indices. The character number of these indices is ignored since these commands deal only with whole tokens.

WIDGET token append TAG ARGUMENTS

The command causes a token to be appended to the current list of tokens in the HTML widget. This command is typically used within a token handler.

WIDGET token delete INDEX ?INDEX-2?

Deletes the single token indentified by the index. If a second index is given, the range of tokens from the first to the second index inclusive is deleted.

WIDGET token find TAG

Locates all tokens with the given TAG and returns them all as a list. Each element of the returned list is a sublist containing the index for the token and the arguments for the token.

WIDGET token get INDEX ?INDEX-2?

Returns a list of tokens in the range of INDEX through INDEX-2. Each element of the list consists of the token tag followed by the token arguments.

WIDGET token handler TAG ?SCRIPT?

This command allows special processing to occur for selected tokens in the HTML input stream. The TAG argument is either ``Text'' or ``Space'' or the name of an HTML tag (ex: ``H3'' or ``/A''). If a non-empty script is specified for a particular tag, then when instances of that tag are encountered by the parser, the parser calls the corresponding script instead of appending the token to the end of the token list. Before calling the script, three arguments are appended:

The token number.
The tag. (ex: H3)
A list of name/value pairs describing all arguments to the tag.

An empty handler script causes the default processing to occur for the tag. If the script argument is omitted all together, then the current value of the token handler for the given tag is returned.

Only one handler may be defined for each token type. If a new handler is specified for a token type that previously had a different handler defined, then the old handler is overwritten by the new.

WIDGET token insert INDEX TAG ARGUMENTS

Inserts a single token given by TAG and ARGUMENTS into the token list immediately before INDEX.

WIDGET xview args...

Used to control horizontal scrolling.

WIDGET xview: Returns a list containing two elements. The elements are a fractions between 0.0 and 1.0 that define the position of the left and right edges of the visible part of the document as a fraction of the whole.
WIDGET xview moveto FRACTION: Adjusts the horizontal position of the document so that FRACTION of the horizontal span of the document is off-screen to the left.
WIDGET xview scroll NUMBER WHAT: Shifts the view in the window left or right according to NUMBER and WHAT. NUMBER is an integer and WHAT is either units or pages.

WIDGET yview args...

Used to control the vertical position of the document. WIDGET yview Returns a list containing two elements. The elements are a fractions between 0.0 and 1.0 that define the position of the top and bottom edges of the visible part of the document as a fraction of the whole. WIDGET yview NAME Adjusts the vertical position of the document so that the tag ``<a name=NAME>'' is on screen, and preferably near the top of the screen. WIDGET yview moveto FRACTION Adjusts the horizontal position of the document so that FRACTION of the vertical span of the document is off-screen above the visible region. WIDGET xview scroll NUMBER WHAT Shifts the view in the window up or down according to NUMBER and WHAT. NUMBER is an integer and WHAT is either units or pages.

end	The keyword ``end'' means one character past the last character of the last token.
@X,Y	The character located at screen coordinates X,Y.
*.last	The second integer can be replaced by the keyword ``last'' to mean the last character in the token.
sel.first	This is the first character that is part of the selection.
sel.last	This is the last character that is part of the selection.
ins	The character immediately following the insertion cursor.

plain	Ordinary text with no characters escaped.
http	The text is encoded in a form suitable for use with the HTTP protocol. Spaces are converted to "+". Special characters and escaped as "%aa" where "a" is a hexadecimal digit. A special character is anything other than an alphanumeric or one of these: ".", "$", "-", or "_".
url	The text is encoded in a form suitable for use as a URI. Spaces are converted to "+". Special characters and escaped as "%aa" where "a" is a hexadecimal digit. A special character is anything other than an alphanumeric or one of these: ".", "$", "-", "_", or "/".
html	The text is encoded in a form suitable for use within HTML. "&" is encoded as "&", "<" is encoded as "<" and so forth.