NAME

Tk::Help - Simple widget for creating a help system for Perl/Tk applications

SYNOPSIS

    use Tk::Help;
    my $help = $main->Help(-variable => \@array);

DESCRIPTION

This is an answer to a personal need to be able to create help systems for my Perl/Tk applications. Originally, I just created a really big dialog and formatted all the text, which was tedious and clumsy. I wanted to create something that looked 'similar' to the Windows help. This is by no means as featured or fluid as the Windows help, but it should provide a (somewhat) simple means to create a help dialog where all someone should need to do is create the array with their help content.

OPTIONS

-globalfontfamily: Set the font family for all text in the Help widget.
-detailsbackground: Sets the background color of the details section (right side) of the help window. Default is white.
-detailsborderwidth: Sets the borderwidth around the inside of the details section (right side) of the help window. Default is 10.
-detailsfontsize: Sets the font size of the details text. This is separate from the header text that appears in each detail window. Default is 8.
-detailsforeground: Sets the color of the details text. This is separate from the header color that appears in each detail window. Default is the OS's default text color for Windows and black otherwise.
-detailsheaderfontsize: Sets the font size of the headers in the details window above the text. This is separate from the details text. Default is 9.
-detailsheaderforeground: Sets the color of the headers in the details window above the text. This is separate from the details text. Default is the OS's default text color for Windows and black otherwise.
-detailsmenu: Determines if the right-click menu is active for the details section. Takes a boolean value. Default is 0.
-detailswidth: Sets the width of the details section. Default is 40.
-height: Sets the height for the help window. Default is 30 for Windows and 40 otherwise.
-icon: Sets the icon on the title bar of the application. This must be passed as a reference. Default is the red 'Tk' icon for Windows and the system default otherwise.
-listbackground: Sets the background color of the list section (left side) of the help window. Default is the OS's default application color, (Tk::NORMAL_BG).
-listborderwidth: Sets the borderwidth around the inside of the list section (left side) of the help window. Default is 0.
-listcursor: Sets the mouse cursor that is used over items in the list section (left side). Default is Perl/Tk's hand2 cursor. To use the OS's default cursor, set -listcursor => 'default'.
-listfontsize: Sets the font size of the list text. Default is 8.
-listforeground: Sets the color of the list text. Default is the OS's default text color for Windows and black otherwise.
-listselectbackground: Sets the background color of the selected list item. Default is whatever -listbackground is set to.
-listselectforeground: Sets the color of the selected list item's text. Default is blue.
-listtype: Sets the type of listbox Help is to use, either HList or Tree. Default is HList.
-listwidth: Sets the width of the list section of the help window. Default is 25.
-resizable: Determines if the help window is resizable or not. Takes a boolean value. The default is set to 0.
-title: Sets the title on the top of the window. Default is 'Help'.
-variable: The structure should be an array of arrayrefs of hashrefs. The very first arrayref should contain only one hashref and this will be the root of your entire help tree. This must be passed as a reference. This is required and there is no default.

EXAMPLES

    use Tk;
    use Tk::Help;

    my $main = MainWindow->new(-title => "My Application");
    $main->configure(-menu => my $menubar = $main->Menu);
    my $filemenu = $menubar->cascade(-label   => "~File",
                                     -tearoff => 0);
    my $helpmenu = $menubar->cascade(-label   => "~Help",
                                     -tearoff => 0);
    $filemenu->command(-label   => "E~xit",
                       -command => sub{$main->destroy});
    $helpmenu->command(-label   => "~Help Contents",
                       -command => sub{showhelp()});

    MainLoop;
    1;

    sub showhelp {
        my @helparray = ([{-title  => "My Application",
                           -header => "My Application Help",
                           -text   => "This is a description of my application for the help."}],
                         [{-title  => "Section 1",
                           -header => "\n\nSection 1 Help",
                           -text   => ""},
                          {-title  => "1st Feature",
                           -header => "The 1st Feature",
                           -text   => "This is the text describing the 1st feature of section 1."},
                          {-title  => "2nd Feature",
                           -header => "The 2nd Feature",
                           -text   => "This is the text describing the 2nd feature of section 1."}],
                         [{-title  => "Section 2",
                           -header => "\n\nSection 2 Help",
                           -text   => ""},
                          {-title  => "1st Feature",
                           -header => "The 1st Feature",
                           -text   => "This is the text describing the 1st feature of section 2."},
                          {-title  => "2nd Feature",
                           -header => "The 2nd Feature",
                           -text   => "This is the text describing the 2nd feature of section 2."}]);

        my $helpicon = $main->Photo(-file => "/path/to/some/gif/or/bmp");
        my $help = $main->Help(-icon     => \$helpicon,
                               -title    => "My Application - Help",
                               -variable => \@helparray);
    }

TODO

- Bind mouse events to the list items to create a mouseover and mouseout effect. - Figure out how to remove the dashed line around a selected item in the list. - Add individual font family switches for each text group.

KEYWORDS

help

AUTHOR

Doug Gruber <dougthug@cpan.org> http://www.dougthug.com/

COPYRIGHT

Tk::Help - Simple widget for creating a help system for Perl/Tk applications