<HTML>
<HEAD><TITLE>DynamicHelp</TITLE></HEAD>
<BODY BGCOLOR=white>
<DL><DT><I><A HREF="#descr">NAME</A></I></DT>
<DD><B>DynamicHelp</B>
 - Provide help to Tk widget or BWidget
</DD></DL>
<DL>
<DT><I><A HREF="#wc">COMMAND</A></I></DT>
<DD>DynamicHelp::<A HREF="#add"><B>add</B></A>
<i>widget</i> ?<I>option value ...</I>?
</DD>
<DD>DynamicHelp::<A HREF="#configure"><B>configure</B></A>
 ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...?
</DD>
<DD>DynamicHelp::<A HREF="#delete"><B>delete</B></A>
<i>widget</i>
</DD>
<DD>DynamicHelp::<A HREF="#include"><B>include</B></A>
 <I>class</I>
 <I>type</I>
</DD>
<DD>DynamicHelp::<A HREF="#register"><B>register</B></A>
 <I>path</I>
 <I>type</I>
 ?<I>arg...</I>?
</DD>
<DD>DynamicHelp::<A HREF="#sethelp"><B>sethelp</B></A>
 <I>path</I>
 <I>subpath</I>
 ?<I>force</I>?
</DD>
</DL>
<BR><HR WIDTH="100%"><BR>
<B><A NAME="descr"></A>DESCRIPTION</B><BR>
<P>
Description text
</P>
<HR WIDTH="50%"><BR>
<B><A NAME="wc">COMMAND</A></B><BR>

<DL><DT><A NAME="add">DynamicHelp::<B>add</B></A>
 ?<I>option value ...</I>?
</DT><DD>
<p>
This command adds dynamic help to the given <i>widget</i>.
</p>
    <DL><DT><A NAME="add-command"><B>-command</B></A></DT>
    <DD>
    	If specified, refers to a command to execute to get the help
	text to display.  The command must return a string to display.
	If the command returns an empty string, no help is displayed.
    </DD>
    </DL>

    <DL><DT><A NAME="add-index"><B>-index</B></A></DT>
    <DD>
	If specified, refers to a menu index to bind the help to instead of
	a widget.  If <b>-type</b> is not menu, this option is ignored.
    </DD>
    </DL>

    <DL><DT><A NAME="add-item"><B>-item</B></A></DT>
    <DD>
    	If specified, refers to an item or tag on a canvas widget or to a tag
        in a text widget to bind the help to instead of to a widget.
    </DD>
    </DL>

    <DL><DT><A NAME="add-type"><B>-type</B></A></DT>
    <DD>
	Specifies the type of help.  Can be:
	<b>balloon</b>, <b>variable</b> or <b>menu</b>.
	Default is <b>balloon</b>.
    </DD>
    </DL>

    <DL><DT><A NAME="add-text"><B>-text</B></A></DT>
    <DD>
    	The text to be displayed as help.
    </DD>
    </DL>

    <DL><DT><A NAME="add-variable"><B>-variable</B></A></DT>
    <DD>
    	Specifies a variable name to which the help string will be
        written.  Some other widget (e.g., a status bar) is
        responsible for displaying this variable.
    </DD>
    </DL>

    <p>
    Creating dynamic help for a menu is a two-step process.  The menu
    itself must first be added and then each menu entry must be added
    separately.  Here is a brief example.
    </p>

    <TABLE BORDER=2 CELLSPACING=2 WIDTH="80%">
    <TR><TD><PRE>
    <FONT COLOR=red><I># create menu</I></FONT>
    menu .m -type menubar
    <FONT COLOR=red><I># associate menubar to toplevel BEFORE DynamicHelp::register</I></FONT>
    <FONT COLOR=red><I># to make it works with menu clone name</I></FONT>
    . configure -menu .m
    .m add cascade -label "File" -menu .m.file
    menu .m.file
    .m.file add command -label "Open..."
    .m.file add command -label "Quit"
    <FONT COLOR=red><I># create label for help, using variable varinfo</I></FONT>
    label .l -textvariable varinfo
    <FONT COLOR=red><I># associate all entries of menu .m.file to variable varinfo</I></FONT>
    DynamicHelp::add .m.file -type menu -variable varinfo
    <FONT COLOR=red><I># then declare entries of .m.file</I></FONT>
    DynamicHelp::add .m.file -type menu -index 0 -text "Detach menu"
    DynamicHelp::add .m.file -type menu -index 1 -text "Open a file"
    DynamicHelp::add .m.file -type menu -index 2 -text "Exit demo"
    </PRE></TD></TR></TABLE></CENTER>

</DL>

<DL><DT><A NAME="configure">DynamicHelp::<B>configure</B></A>
 ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...?
</DT><DD>
This command configure the ballon help.
<P>
<DL><DT><A NAME="DynamicHelp-borderwidth"><B>-borderwidth</B></A></DT>
<DD>
Width of the black border around the balloon.
</DD>
</DL>
<DL><DT><A NAME="DynamicHelp-delay"><B>-delay</B></A></DT>
<DD>
Define the delay in millisecond of mouse inactivity before displaying
the balloon.
</DD>
</DL>
<dl>
    <dt><a name="DynamicHelp-state"><b>-state</b></a></dt>
    <dd>
    Specifies one of two states for help balloons: <b>normal</b> and
    <b>disabled</b>.
    </dd>
    <dd>
    If <b>state</b> is <b>disabled</b>, help balloons will not be displayed
    for any registered widget.
    </dd>
</dl>
<DL><DT><A NAME="DynamicHelp-topbackground"><B>-topbackground</B></A></DT>
<DD>
The background color of the toplevel window created for a balloon.
</DD>
</DL>
<BR>Other standard options are:
<DD><TABLE CELLSPACING=0 CELLSPACING=0 BORDER=0>
<TR>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-background">-background or -bg</A></TD>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-font">-font</A></TR>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-foreground">-foreground or -fg</A></TD>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-justify">-justify</A></TR>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-padx">-padx</A></TD>
<TD>&nbsp;&nbsp;<A HREF="options.htm#M-pady">-pady</A></TR>
</TR>
</TABLE></DD>
</DD></DL>

<DL><DT><A NAME="delete">DynamicHelp::<B>delete</B></A>
 <I>widget</I>
</DT><DD>
    Delete all dynamic help for the given <i>widget</i>.
</DD></DL>

<DL><DT><A NAME="include">DynamicHelp::<B>include</B></A>
 <I>class</I>
 <I>type</I>
</DT><DD>
Description text
</DD></DL>
<DL><DT><A NAME="register">DynamicHelp::<B>register</B></A>
 <I>path</I>
 <I>type</I>
 ?<I>arg...</I>?
</DT><DD>
<p>
<b>Its use is deprecated.  Use <i>DynamicHelp::add</i> instead.</b>
</p>

Register a help text to the widget <I>path</I>.
<I>type</I> determines the type of the help or the type of the widget.
Depending on <I>type</I>, other options must be provided.
<BR>
<TABLE CELLSPACING=5 CELLPADDING=0 BORDER=0>
<TR><TD><B>    type      </B></TD><TD><B>     options      </B></TD></TR>
<TR><TD><B><I> balloon   </I></B></TD><TD><I> ?tagOrItem? text </I></TD></TR>
<TR><TD><B><I> variable  </I></B></TD><TD><I> ?tagOrItem? varName text </I></TD></TR>
<TR><TD><B><I> menu      </I></B></TD><TD><I> varName      </I></TD></TR>
<TR><TD><B><I> menuentry </I></B></TD><TD><I> index text   </I></TD></TR>
</TABLE>
<BR>If one of the option is missing or is empty, help is removed for this widget.
<p>

If <i>tagOrItem</i> is specified, then <i>path</i> is a canvas or a text. In
case of a canvas, <i>tagOrItem</i> is the name of a tag or item on the canvas
to which the help will be bound. In case of a text, <i>tagOrItem</i> is the
name of a tag on the text to which the help will be bound.

</p>
For type other than <I>balloon</I>, <I>varName</I> is typically a variable
linked to a label.
<BR>For menu, balloon type help is not available. To declare a help for menu,
you first declare the menu, and then entries of this menu.
<BR>For example:
<BR><BR>
<CENTER>
<TABLE BORDER=2 CELLSPACING=2 WIDTH="80%">
<TR><TD><PRE>
     <FONT COLOR=red><I># create menu</I></FONT>
menu .m -type menubar
<FONT COLOR=red><I># associate menubar to toplevel BEFORE DynamicHelp::register</I></FONT>
<FONT COLOR=red><I># to make it works with menu clone name</I></FONT>
. configure -menu .m
.m add cascade -label "File" -menu .m.file
menu .m.file
.m.file add command -label "Open..."
.m.file add command -label "Quit"
<FONT COLOR=red><I># create label for help, using variable varinfo</I></FONT>
label .l -textvariable varinfo
<FONT COLOR=red><I># associate all entries of menu .m.file to variable varinfo</I></FONT>
DynamicHelp::register .m.file menu varinfo
<FONT COLOR=red><I># then declare entries of .m.file</I></FONT>
DynamicHelp::register .m.file menuentry 0 "Detach menu"
DynamicHelp::register .m.file menuentry 1 "Open a file"
DynamicHelp::register .m.file menuentry 2 "Exit demo"
</PRE></TD></TR></TABLE></CENTER>
<BR>
<BR>Notice that if popup menu is owned by a menubar, you must associate first the menubar
to its toplevel. In this case, when you create a menu popup, its clone window is also
created, and DynamicHelp::register detects the exitence of the clone window and maps
events to it.
</DD></DL>
<DL><DT><A NAME="sethelp">DynamicHelp::<B>sethelp</B></A>
 <I>path</I>
 <I>subpath</I>
 ?<I>force</I>?
</DT><DD>
Description text
</DD></DL>
</BODY></HTML>
