Tk Library Source Code

Documentation
Login
Core Home Blog Docs Downloads Tickets Timeline Branches Tags Wiki

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

shtmlview - Extended Tcl/Tk text widget with basic support for rendering of HTML and Markdown

Table Of Contents

SYNOPSIS

package require Tk
package require snit
package require Markdown ;# optional Markdown support
package require img::jpeg ;# optional jpeg image support
package require shtmlview::shtmlview ?1.1.0?

::shtmlview::converter extension description cmdprefix
::shtmlview::shtmlview pathName ?options?
pathName back
pathName browse filename ?args?
pathName dosearch string direction
pathName edittext cmd ?options?
pathName editView
pathName forward
pathName getFiles
pathName getHistory
pathName getEditWidget
pathName getTextWidget
pathName helptext cmd ?options?
pathName home
pathName open
pathName reload
pathName render text ?ext?
pathName sourceView
pathName url

DESCRIPTION

The shtmlview::shtmlview package provides a pure Tcl/Tk widget of the same name to render and display basic HTML and Markdown files and string.

Some history: The widget is based on the htmllib library developed in the 90ties by Stephen Uhler and Clif Flynt. In 2009 Robert Heller wrapped this library into the excellent mega-widget framework snit. The resulting widget was however tied directly into a help system. The author of this document first just isolated the display part and then added some functions such as changing font size and a few buttons in the toolbar. Then a rudimentary display of data tables was added. Even later support for inline images and extended keybindings and Markdown support was added.

The widget is not a web browser. It only supports relative links in the local filesystem. It does not support style sheets. It does not support http(s) links nor images. It is thought of as a last fallback to use in cases where no other possibilities exists to display HTML or Markdown markup from a Tk application.

Use cases are as a help viewer and wherever the developer has control about the used html tags.

Comments and feedbacks are welcome.

The shtmlview::shtmlview widget overloads the text widget and provides new commands and options. These are explained in the sections WIDGET COMMANDS and WIDGET OPTIONS.

Note that the file "shtmlview.tcl" is not only a package but also a standalone application for the direct viewing of Markdown and HTML files. Invoke it as

tclsh shtmlview.tcl filename.html

in a terminal.

The API described in this document is not the whole API offered by the snit object ::shtmlview::shtmlview. Instead, it is the subset of that API that is expected not to change in future versions.

COMMANDS

WIDGET OPTIONS

Use method helptext to configure the internal text widget.

WIDGET COMMANDS

Each shtmlview widget created with the above command supports the following commands and options:

BINDINGS FOR THE WIDGET

The following keys are bound to the widget for navigation and other actions:

EXAMPLE

package require shtmlview::shtmlview
proc browsed {url} {
    puts "You browsed $url"
}
::shtmlview::shtmlview .help -toolbar true -browsecmd browsed
.help browse index.html
pack .help -fill both -expand true -side left
package require Markdown
.help browser test.md

More examples can be found in the sources of the package.

EXTENSIONS

While the package natively only support HTML documents, and Markdown documents if the supporting Markdown package is available, it is possible to extend the range of supported formats by means of a plugin mechanism.

The main entry point to that system is the shtmlview::converter command. With it is possible to register a document format and an associated conversion command. The format is identified by its file extension, like, for example ".md", ".man", etc. The conversion command is expected to convert the content of the file given to it into HTML for display.

The packages shtmlview::doctools and shtmlview::mkdoc are examples of such plugins. The first provides support for the doctools format used by both Tcllib and Tklib for their manpages, while the second provides support for mkdoc-enhanced Tcl source files. In other words, Tcl files with embedded documentation in mkdoc syntax.

Enclosed below the bare Tcl code of the shtmlview::mkdoc package:

    package require shtmlview::shtmlview
    package require mkdoc::mkdoc

    ::shtmlview::converter .tcl {Tcl+mkdoc files}   ::shtmlview::mkdoc
    ::shtmlview::converter .tm  {Tcl+mkdoc modules} ::shtmlview::mkdoc

    proc ::shtmlview::mkdoc {url} {
	close [file tempfile htmltemp .html]

	mkdoc::mkdoc $url $htmltemp -html

	if {[catch {
	    open $htmltemp r
	} result]} {
	    return -code error "Cannot open $url: $result"
	}

	set html [read $result]
	close $result
	file delete $htmltemp

	return $html
    }

    package provide shtmlview::mkdoc 0.1

It is of course possible to write plugins which use an external application like pandoc to generate the HTML to render, instead of a Tcl package.

And it is of course also possible to register conversion commands directly from the application using this package, instead of going through a separate package.

CHANGELOG

TODO

Thanks

Stephen Uhler, Clif Flynt and Robert Heller, they provided the majority of the code in this widget.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such to the author of this package. Please also report any ideas for enhancements you may have for either package and/or documentation.

Code Copyright

BSD License type:

Sun Microsystems, Inc. The following terms apply to all files a ssociated with the software unless explicitly disclaimed in individual files.

The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply.

In no event shall the authors or distributors be liable to any party for direct, indirect, special, incidental, or consequential damages arising out of the use of this software, its documentation, or any derivatives thereof, even if the authors have been advised of the possibility of such damage.

The authors and distributors specifically disclaim any warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. This software is provided on an "as is" basis, and the authors and distributors have no obligation to provide maintenance, support, updates, enhancements, or modifications.

RESTRICTED RIGHTS: Use, duplication or disclosure by the government is subject to the restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software Clause as DFARS 252.227-7013 and FAR 52.227-19.

SEE ALSO

text

KEYWORDS

html, text, widget

COPYRIGHT

Copyright © 2018-2022, Detlef Groth
Copyright © 2009, Robert Heller
Copyright © 2000, Clif Flynt
Copyright © 1995-1999, Stephen Uhler

This page was generated in about 0.026s by Fossil 2.24 [f4ffefe708] 2024-04-17 14:02:19