NAME

Tk::ContextHelp - context-sensitive help with perl/Tk

SYNOPSIS

  use Tk::ContextHelp;

  $ch = $top->ContextHelp;
  $ch->attach($widget, -msg => ...);

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

  $ch2 = $top->ContextHelp(-podfile => "perlfaq");
  $ch2->attach($widget2, -pod => 'description');

DESCRIPTION

ContextHelp provides a context-sensitive help system. By activating the help system (either by clicking on a HelpButton or calling the activate method, the cursor changes to a left pointer with a question mark and the user may click on any widget in the window to get a help message or jump to the corresponding pod entry.

ContextHelp accepts all the options that the Label widget accepts. In addition, the following options are also recognized.

-callback

Set a callback to be called on each state change (useful for own HelpButton implementations).

-cursor

Use another cursor for the help mode instead of the left pointer with question mark.

-helpkey

Enable use of a help key. A common choice would be "F1" (or written as "<F1>") or maybe "<Help>", if your keyboard has a help key.

-offcursor

Use another cursor for the help mode shown if the underlying widget is not attached to the help system. The default is a left pointer with a strike-through question mark.

-podfile

Set the pod file for the -pod argument of attach. The default is $0 (the current script).

-stayactive

If set to true, help mode is active until set to false. So the user may browse over all topics he like.

-verbose

Be verbose if something goes wrong. Default is true.

-widget

Use another widget instead of the default Label for displaying messages. Another possible choice would be Message.

METHODS

The ContextHelp widget supports the following non-standard methods:

attach(widget, option)

Attaches the widget indicated by widget to the context-sensitive help system. Option may be one of the following:

-msg

The argument is the message to be shown in a popup window.

-pod

The argument is a regular expression to jump in the corresponding pod file. For example, if you have a topic DESCRIPTION where you want to jump to, you can specify

    $contexthelp->attach($widget, -pod => '^\s*DESCRIPTION');

-podfile

The argument is a pod name to be used instead of the default pod file. -podfile may be used together with -pod or all alone.

-command

The argument is a user-defined command to be called when activating the help system on this widget.

detach(widget)

Detaches the specified widget widget from the help system.

activate

Turn the help system on.

deactivate

Turn the help system off.

toggle

Toggle help system on or off.

HelpButton(top, options)

Create a help button. It is a regular Button with -bitmap set to the help cursor bitmap and -command set to activation of the help system. The argument top is the parent widget, options are additional options for the help button.

The button stays pressed as the help is activated. Clicking on the pressed button causes the end of the help mode. Clicking with mousebutton-3 causes the help system to stay active until the user clicks on the button over again.

BUGS

• The user cannot click on the border of an attached widget to raise the help window.

• While in help mode, it is possible to click on buttons even if the buttons aren't attached to the help system. This is non-intuitive, but hard to fix. (Maybe a solution: create inputo-widgets for all not-attached widgets while in context mode)

TODO

 * optional use of html browsers (netscape -remote openURL ...)

 * on Win32, make InputO work and use the native help system

AUTHOR

Slaven Rezic <slaven@rezic.de>

Some code and documentation is derived from Rajappa Iyer's Tk::Balloon.

Copyright (c) 1998,2000,2003 Slaven Rezic. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Tk::Balloon(3), Tk::Pod(3).