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


  use Tk::ContextHelp;

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


  $ch2 = $top->ContextHelp(-podfile => "perlfaq");
  $ch2->attach($widget2, -pod => '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.


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


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


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.


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.


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


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


Be verbose if something goes wrong. Default is true.


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


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:


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


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');

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.


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


Detaches the specified widget widget from the help system.


Turn the help system on.


Turn the help system off.


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.


  • 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)


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

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


Slaven Rezic <>

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

Copyright (c) 1998,2000,2003,2015 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.


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