Help!!

By: Slaven Rezic

Don't let the user alone with your Perl/Tk application. It's quite easy to implement some help functions with existing modules. This article will discuss three of them: Tk::Balloon, Tk::Pod and Tk::ContextHelp.

Tk::Balloon

A balloon in a Perl/Tk application.

A familiar help facility in most Windows and Macintosh programs is the "tool tips" window, or, in the terminology of Perl/Tk, the help balloon. This is a small window with a help message popping up if the user leaves the mouse cursor over a widget for a short time. Additionally, if there is a status bar, the help message is also displayed in it. The standard Perl/Tk module Tk::Balloon provides this feature.

To use it, the balloon object first has to be created: 

    $balloon = $top->Balloon(-statusbar => $status_bar_widget);
This will create a hidden balloon, which is technically a borderless toplevel widget (to get it borderless, the overrideredirect method is used, see the Tk::Wm man page). The -statusbar argument is optional. It can be set to a widget object which understands the -text or -textvariable option, like (typically) a Label, a Button, or a Message widget.

Now, to associate a part of the GUI with a help message, we have to use the attach method to the wanted widget: 

    $balloon->attach($widget, -msg => "A help message");
There are three types of message options. The -msg option specifies the message for both the balloon and the status bar, and with -balloonmsg and -statusmsg it is possible to differentiate those messages.

For Canvas and Menu widgets, there is an additional special mode. For a Canvas widget, it is possible to attach messages to individual canvas items. For menus, each menu entry can get an individual balloon message (note that probably this will not work on Windows). To use this feature, the argument to -msg should be a hash with the canvas item numbers or tag strings as the keys and the messages as the values. For menus, the argument should be an array with the first message attached to the first menu entry and so on (however, keep in mind that the first menu entry is often the tear-off entry). Examples for this usage can be found in the SYNOPSIS section of the Tk::Balloon manual page.

The forgotten help menu

The last entry of a menu bar in a common gui application, is a help menu. It's almost always there, but often there is not much information in it. At least, there should be an "About" entry providing copyright, version and author information. Better, if there is an entry for the manual of the application.

You are programming in Perl, so there's a chance you are familiar with the Pod documentation format. There is a number of Pod utilities bundled with the core Perl, so there is always a chance to get the documentation in a format you like.

To display Pod documentation, there are some naïve approaches:

But I think a better way is to use the Perl/Tk module Tk::Pod...

Tk::Pod

Tk::Pod is a Pod browser written in Perl/Tk. This module is not in the standard Perl/Tk distribution. You have to fetch it from the CPAN. Look at a screenshot of a Tk::Pod window.

Tk::Pod is in fact a hypertext browser. Links in the Pod documentation (which are marked with L< ... >) are functional: you can jump to references inside the Pod and to other Pods.

You can search the document. Moreover, if Text::English is installed and a fulltext index of the perl documentation is built, a query over the whole installed perl documentation is possible.

Additionally, there is a menu displaying the structure of the document, thus it's possible to jump quickly to different sections.

These features make Tk::Pod also a good choice for reading perl documentation instead of man or perldoc. Together with the module, the program tkpod is installed as a standalone Pod viewer. Here is an example for Pod use: this defines a menu entry for the manual: 

use FindBin;
use Tk;
...

$help_menu->command
  (-label => "~Documentation",
   -command => sub {
       eval {
           require Tk::Pod;
           Tk::Pod->Dir($FindBin::RealBin);
           $top->Pod(-file => $FindBin::RealScript . ".pod",
                     -title => 'Documentation for this program');
       };
       if ($@) {
           my $r;
           my $doc_html = "$FindBin::RealBin/$FindBin::RealScript.html";
           my $url;
           if (defined $doc_html && -r $doc_html) {
               $url = "file:$doc_html";
	       system("netscape $url&");
           }
       }
   },
  );
(A complete example script can be found here)

For explanation: the FindBin module helps to find the current position of the running script. $FindBin::RealBin will be set to the directory of the running script (not the current working directory!) and $FindBin::RealScript will contain the basename of the running script. There are also versions of these variables without the "Real", which will contain the values without all links resolved. The code above assumes that the documentation is in a separat file with the extension ".pod". Of course, the documentation can also be embedded in the perl script.

The menu entry handler will first try to see if Tk::Pod is installed. Therefore an eval block is put around the require statement, to prevent any error messages. With Tk::Pod->Dir, an additional search directory for Pods is set to the directory containg the running script - assuming that the Pod is in the same directory (otherwise, only $ENV{PATH} and @INC is searched for Pods). Then a new Pod widget is created with the contents of the appropriate Pod file (the -file option).

In case that the Tk::Pod is not installed or there were other errors in the processing, the program tries a fall back: it checks whether there is a html documentation file in the same directory. If there is one, then Netscape is called with this file. You can adjust the system line to your liking, e.g. calling "xterm -e lynx $url&" or "xterm -e w3m $url&" for your favorite text-oriented web browser. Note that the "&" is necessary to prevent the blocking of the Perl/Tk program; otherwise, it won't react to any user input unless the web browser is shut down.

Tk::ContextHelp

The last module described in this article is somewhat like a combination of the previous two. It can be used to attach widgets to individual help messages, but it can also use Tk::Pod to display the appropriate parts of the documentation. This help facility is similar to the one in Windows 95: There is a context help button. By clicking this button, the cursor changes and now displays a question mark next to the arrow. If the user moves the mouse to a widget without a context help entry, then the question mark is crossed to show that there is no help for this topic available. Otherwise the user can click on the widget and a Tk::Pod window will pop up with the appropriate topic. In case Tk::Pod is not installed, a Tk::Text widget will be shown instead with the output of pod2text.

Although this is a Windows technique, this module will not work on Windows. This is because Tk::ContextHelp uses the Tk::InputO widget, which is only available for the X11 version of Perl/Tk.

The coding is similar as in Tk::Balloon. Widgets can be attache()d to the Tk::ContextHelp object. To attach a widget to a section in the Pod file, use the -pod option. The argument should be a regular expression matching text in the pod, e.g. the section header. For example, to jump to the foo widget section, you have to write: 

    $contexthelp->attach($widget, -pod => '^\s*FOO WIDGET');
and the corresponding Pod section will look like: 
=head2 FOO WIDGET
.

There are two methods activate and deactivate, to turn the help system on and off. The module has also a method for creating a convenience button for turning the help system on/off. To use this button, write: 

    $contexthelp->HelpButton($top)->pack;

This was a short introduction to some help facilities in Perl/Tk. Of course, you should consult the manual pages for detailed information. You can also think of other ways to display the documentation, e.g. using a native Perl/Tk WWW browser (at CPAN, there is Tk::Web).