/ 
Tk-HyperText-0.05
River stage one • 2 direct dependents • 2 total dependents
/ Tk::HyperText

NAME

Tk::HyperText - Create and manipulate ROText widgets which render HTML code.

SYNOPSIS

my $hypertext = $mw->Scrolled ("HyperText",
  -scrollbars   => 'e',
  -wrap         => 'word',
  -linkcommand  => \&onLink,  # what to do when <a> links are clicked
  -titlecommand => \&onTitle, # what to do when <title>s are found
)->pack (-fill => 'both', -expand => 1);

# insert some HTML code
$hypertext->insert ("end","<body bgcolor=\"black\" text=\"yellow\">"
  . "Hello, <b>world!</b></body>");

WIDGET-SPECIFIC OPTIONS

-rerender

Boolean. When true (the default), the ENTIRE contents of your HyperText widget will be (re)rendered every time you modify it. In this way, if you insert, e.g. a "bold" tag and don't close it, then insert new text, the new text should logically still be in bold, and it would be when this flag is true.

When false, only the newly inserted text will be rendered independently of what else is already there. If re-rendering the page is too slow for you, try disabling this flag.

-titlecommand

This should be a CODEREF pointing to a subroutine that will handle changes in a page's title. While HTML code is being parsed, when a title tag is found, it will call this method.

The callback will received the following variables:

$widget = a reference to the HyperText widget that wants to set a title.
$title  = the text in the <title> tag.
-linkcommand

This should be a CODEREF pointing to a subroutine that will handle the clicking of hyperlinks.

The callback will received the following variables:

$widget = a reference to the HyperText widget that invoked the link.
$href   = the value of the link's "href" attribute.
$target = the value of the link's "target" attribute.
-attributes

This option will allow you to define all of the default settings for the display of HTML pages. Here's an example:

my $html = $mw->Scrolled ("HyperText",
  -attributes => {
    body => {
      bgcolor => 'white',
      text    => 'black',
      link    => 'blue',
      vlink   => 'purple',
      alink   => 'red',
    },
    font => {
      family => 'Arial',
      size   => 3,
      color  => '', # inherit from <body>
      back   => '', # inherit from <body>
    },
  },
)->pack;
-basehref

The "base href" of the webpages being rendered. This should be the local file path (ex. "./demolib"). The base href can be reset using the <base> tag in a webpage. The base href is used for locating external files, such as images.

DESCRIPTION

Tk::HyperText is a derived Tk::ROText class which supports the automatic rendering of HTML code. It's designed to be easily useable as a drop-in replacement to any Tk::ROText widget. Rendering HTML code is as easy as inserting it as raw HTML, as shown in the synopsis.

WIDGET METHODS

In addition to all of the methods exported by Tk::ROText and Tk::Text, the following methods have special behaviors:

$text->insert (where, html-code)

Insert new HTML code, and render it automatically. Note that currently, only inserting to the "end" works. See "BUGS" below.

$text->delete (start, end)

Delete content from the textbox. Note that currently you can only delete EVERYTHING. See "BUGS" below.

$text->get (start, end)

Get the HTML code back out of the widget. Note that currently this gets ALL of the code. See "BUGS". This returns the actual HTML code, not just the text that's been rendered.

$text->clear

Clear the entire text widget display.

$text->clearHistory

Clear the history in the text widget. This will make all the links that were "visited links" become "unvisited links" again.

$text->namesMode ([new-mode])

Change the permissions mode. Valid options are allow_all, allow_some, deny_some, deny_all. The default is allow_all. Returns the current mode.

$text->namesAllow ([tag-list])

Add the list of tags to the allow list when the permissions mode is set to allow_some, or removes them from the deny list if the mode is deny_some.

$hypertext->namesAllow ("<body>", "<font>", "<br>");
$text->namesDeny ([tag-list])

Add the list of tags to the deny list when the permissions mode is set to deny_some, or removes them from the allow list if the mode is allow_some.

$hypertext->namesDeny ("<img>", "<hr>");

SUPPORTED HTML

The following HTML tags and attributes are fully supported by this module:

<html>, <head>
<title>      *calls -titlecommand when found
<link>       (type media href)
<style>      (type)
<body>       (bgcolor, link, vlink, alink, text)
<basefont>   (face, size, color)
<base>       (href)
<font>       (face, size, color, back)
<img>        (src, align, hspace, vspace)*
<hr>         (size, width)
<a>          (href, target)
<ol>, <ul>   (type, start)
<li>
<div>        (align=left|center|right)
<span>
<blockquote>
<p>, <br>
<pre>
<code>, <tt>, <kbd>, <samp>
<center>, <right>, <left>
<h1> - <h6>
<sup>, <sub>
<b>, <strong>
<i>, <em>, <address>, <var>, <cite>, <def>
<u>, <ins>
<s>, <del>

* Image alignment must be "top", "middle", "bottom", or "baseline". Tk::Text doesn't support "left" and "right" alignments.

SUPPORTED CSS

CSS support is relatively new as of version 0.05. The following "kinds" of CSS are supported:

External CSS files (<link type="text/css" href="external.css">)
Internal CSS code (<style type="text/css">)

The following type is NOT supported:

Inline CSS (<span style="...">)

As far as the actual CSS code, the following attributes are supported:

background       (only the "color" part)
background-color
font-family
font-size        *
font-style
font-weight      (bold, lighter, normal--lighter is the same as normal)
text-decoration  (none, underline, line-thru)
text-align       (left, center, right)
color

* With font-size, if you don't specify a unit of measurement, it's taken as a regular HTML font size (range 1 through 6). If you do specify a unit (i.e. px, pt, em, etc), the font size will be taken as a point size.

IMAGES

A couple of default images were provided within the module (Base64-encoded) to display when something is wrong with an image in your HTML code.

$Tk::HyperText::IMG_BROKEN is the Base64 data for the "image not found" image. It displays as a PNG image of a red "X" within a sunken-bordered box.

$Tk::HyperText::IMG_INVALID is the Base64 data for the "invalid image data" image. It displays as a PNG image of a yellow exclamation mark within a sunken box.

These images are included in their regular PNG form in the distribution of Tk::HyperText. You can reset these variables in your program if you'd like to have customized default images to handle these cases.

EXAMPLE

Run the `demo.pl` program included in the distribution for a demonstration. It's a kind of simple web browser that views HTML pages in the "demolib" directory, and supports hyperlinks that link from one page to another.

BUGS

As noted above, the insert method only inserts at the end, delete deletes everything, and get gets everything. I plan on coming up with a way to fix this in a later version.

There's a minor bug in the counting of alphabetic ordered lists. It counts them from A to Z, then AA to AY, B, BA to BY, C, CA to CY, D, etc.

SEE ALSO

Tk::ROText and Tk::Text.

CHANGES

0.05 July 11, 2007

- Added support for "tag permissions", so that you can allow/deny specific tags from
  being rendered (i.e. say you're making a chat client which uses HTML and you don't
  want people inserting images into their messages, or style sheets, etc)
- Added the tags <address>, <var>, <cite>, and <def>.
- Added the <hr> tag.
- Added two "default images" that are displayed when an <img> tag tries to show
  an image that couldn't be found, or was found but is a file type that isn't
  supported (e.g. <img src="index.html"> would show an "invalid image" icon).
- Bug fix: every opened tag that modifies your style will now copy all the other
  stacks. As a result, opening <font back="yellow">, then <font color="red">, and
  then closing the red font, will still apply the yellow background to the following
  text. The same is true for every tag.
- Added some support for Cascading StyleSheets.
- Added some actual use for the "active link color": it's used as the hover color
  on links (using it as a true active color is mostly useless, since most of the
  time the page won't remain very long when clicking on a link to even see it)

0.04 June 23, 2007

- Added support for the <basefont> tag.
- Added support for <ul>, <ol>, and <li>. I've even extended the HTML specs a
  little and added "diamonds" as a shape for <ul>, and allowed <ul> to specify
  a decimal escape code (<ul type="#0164">)
- Added a "page history", so that the "visited link color" on pages can actually
  be applied to the links.
- Fixed the <blockquote> so that the margin applies to the right side as well.

0.02 June 20, 2007

- Bugfix: on consecutive insert() commands (without clearing it in between),
  the entire content of the HTML already in the widget would be inserted again,
  in addition to the new content. This has been fixed.

0.01 June 20, 2007

- Initial release.

AUTHOR

Casey Kirsle, <casey at cuvou.net>