/ 
Tk-Help-0.3
River stage zero No dependents
++
 / Tk::Help
Doug Gruber

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.

SEE ALSO

Tk::Toplevel, Tk::HList, Tk::Tree

KEYWORDS

help

AUTHOR

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

COPYRIGHT

Copyright (c) 2005 Doug Gruber. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.