html3widget - a tcl/tk megawidget

A tcl/tk megawidget to render html + css based on the Tkhtml3.0 library.

Purpose

The html3widget is a tcl/tk package which implements a megawidget to render html + css.

The code is based on Tkhtml3.0 and as well HV3 which (for the moment) is not actively developed, but still offers a solid base to render html including css support.

The picture illustrates of how a html file with underlying css might look like.

You can even use a fully featured css framework like bootstrap or similar. Features defined in the framework which are not implemented by Tkhtml are simply ignored.

CSS Support

Tkhtml3 aims to support those aspects of HTML 4.01 and CSS 2.1 that apply to the parsing and visual rendering of documents.

As of now, CSS support is reasonable good, responsive images are supported as well.

Use Case

For example, the package can be used to implement an internal help viewer in an easy way.
Help pages on the other hand might be written in markdown and converted with markdown2go.

Implementation

The following functions are available:

• Search dialog with “live preview” of the search string,
• browsing to the next/previous search item,
• selection manager to be able to select text with the mouse and to copy&paste the selected text <CTRL+C>,
• Increase/Decrease font with <CTRL plus> / <CTRL minus>
• a very basic link management,…

Tkhtml 3.0

As stated in the HV3 homepage tkhtml.tcl.tk:

• Tkhtml3 aims to support those aspects of HTML 4.01 and CSS 2.1 that apply to the parsing and visual rendering of documents.

  I personally use the kit-enabled wish executables from the kbskit project (kbs.tcl), downloaded as binaries from sourceforge. You can find binaries for windows and OSX here.

• The Tkhtml3.0 binary package I got from ActiveState - you need to use teacup command line utility, as the standard installation of ActiveTcl includes only Tkhtml2.0 by default.

  Note: To avoid version conflicts package require -exact Tkhtml 3.0 is required all the way long…

• When searching the web for some modifications and improvements regarding the Tkhtml3.0 library, I discovered some patches here: tkhtml3-master-github.

  Unfortunately I do not know right now, if these patches are already incorporated in the ActiveState distribution or not.

  In other words: would be interesting to know, if ActiveState binaries are from tk-html3_3.0-fossil20110109.orig or maybe the one from: tkhtml3-master-github?

Usage

# some demo code

set dir [file normalize [file dirname [info script]]]

# where to find required packages, change file path to fit your requirements ...

set auto_path [linsert $auto_path 0 [file join $dir "."]]
set auto_path [linsert $auto_path 0 [file join $dir ".."]]
set auto_path [linsert $auto_path 0 [file join $dir "../../00-lib"]]


package require Tk
package require TclOO
package require -exact Tkhtml 3.0

# html3widget dependencies:
catch {package require http}

package require scrolledwidget
package require html3widget

# --------------------
# demo starts here ...
# --------------------
# catch {console show}
# console eval {wm protocol . WM_DELETE_WINDOW {exit 0}}


set w [toplevel .test]
wm withdraw .
wm title    $w "Test"
wm geometry $w "800x600"
# wm minsize  $w 400 200
wm protocol $w WM_DELETE_WINDOW "exit 0"


set ft [ttk::frame $w.top]
pack $ft -padx 4 -pady 4 -side top -fill x

ttk::label $ft.lbl -text "Tkhtml-3.0 widget test!"
pack $ft.lbl -anchor center


set fb [ttk::labelframe $w.bottom -text "Browser:"]
pack $fb -padx 4 -pady 4 -side bottom -fill both -expand true

# -----------------------------------------------
set html3 [html3widget::html3widget $fb.html3]
pack $html3 -side bottom -fill both -expand true
# -----------------------------------------------


set html_file [file join $dir "demo_doc/tkhtml_doc.html"]

$html3 parsefile $html_file
# $html3 showSearchWidget

# some more bindings...
bind all <Escape> {exit 0}

bind all <MouseWheel> {
	set w %W
	while { $w != [winfo toplevel $w] } {
		catch {
			set ycomm [$w cget -yscrollcommand]
			if { $ycomm != "" } {
				$w yview scroll [expr int(-1*%D/36)] units
				break
			}
		}
		set w [winfo parent $w]
	}
}

Links

Required Tkhtml3.0 binaries for various platforms can be downloaded from ActiveStates.

• HV3 homepage: tkhtml.tcl.tk

• The source is also published here: wiki.tcl.tk/48458 for discussions.

  For the latest source package please refer on the download link listed down below in this article.

Download

Change History

• 16-xx-xx, Initial release

  • The main goal was purely to visualize html files and so the widget has only a minimum subset of functions to achive this.

• 18-04-13:

  • “bind all” removed, as it might possibly interfere with existing bindings already declared in the main caller application,
  • tk_focusFollowsMouse removed for the same reason

• 19-05-27:

  • hrefBinding procedure extended to follow links inside the currently loaded html document (for TOC support) thanks to Michael Niehren for his request.

• 18-03-13:

  • RegisterMiddleMouseScrollBindings added

• 21-03-09: V0.2.6.1

  • selectionmanager.tcl - “bind all” replaced, there was a side effect with ttk::entry widget

Add on: How to create a Table of Content with markdown

The following text is an example of how a TOC in markdown syntax might look like:

	# Table of Contents

	1. [Name](#Name)
	2. [Synopsis](#Synopsis)


	## Name <a name="Name"></a>

	Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
	ut labore et dolore magna aliquyam erat, sed diam voluptua.

	## Synopsis <a name="Synopsis"></a>

	Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt
	ut labore et dolore magna aliquyam erat, sed diam voluptua.

Please notice that beside the TOC declaration itself, for each individual entry it is also reqiored to list a <a name="Name"></a> tag.

This is a little bit of extra work when editing a text file manually. Might be also a fairly easy job to create a script, which creates the TOC automatically.