html3widget - a tcl/tk megawidget

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 following picture illustrates of how a html file with underlying css bootstrap3.xx framework might look like:

The package might be used to implement an internal help viewer (for an application) in an easy way. Help pages can be written in markdown and converted with markdown2go.

CSS Support:

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

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?

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


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]
    }
}

Revision history:

  • 16-xx-xx, Hans, 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.


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, there is also a <a name="Name"></a> tag required for each individual entry. This is a little bit of extra work when editing a textfile manually. Might be also a fairly easy job to create a script, which creates the TOC automatically.