NAME

       tooltip - Tooltip management

SYNOPSIS

       package require Tcl  8.4

       package require msgcat  1.3

       package require tooltip  ?1.4.6?

       ::tooltip::tooltip command ?options?

       ::tooltip::tooltip pathName ?option arg? message

________________________________________________________________________________________________________________

DESCRIPTION

       This  package  provides  tooltips, small text messages that can be displayed when the mouse hovers over a
       widget, menu item, canvas item, listbox item or text widget tag.

COMMANDS

       ::tooltip::tooltip command ?options?
              Manage the tooltip package using the following subcommands.

              clear index
                     Prevents the specified widgets from  showing  tooltips.  pattern  is  a  glob  pattern  and
                     defaults to matching all widgets.

              delay ?millisecs?
                     Query  or  set  the hover delay. This is the interval that the pointer must remain over the
                     widget before the tooltip is displayed. The delay is specified in milliseconds and must  be
                     greater than 50ms.  With no argument the current delay is returned.

              fade ?boolean?
                     Enable or disable fading of the tooltip.  The is enabled by default on Win32 and Aqua.  The
                     tooltip will fade away on Leave events instead disappearing.

              disable

              off    Disable all tooltips

              enable

              on     Enables tooltips for defined widgets.

       ::tooltip::tooltip pathName ?option arg? message
              This  command arranges for widget pathName to display a tooltip with message message.  The tooltip
              uses a late-binding msgcat call on the passed in message to allow for on-the-fly language  changes
              in  an  application.   If  the  widget  specified is a menu, canvas or text widget then additional
              options are used to tie the tooltip to specific menu entries, canvas items or text tags.

              -index index
                     This option is used to set a tooltip on a menu item. The index  may  be  either  the  entry
                     index  or  the entry label. The widget must be a menu widget but the entries do not have to
                     exists when the tooltip is set.

              -items name
                     This option is used to set a tooltip for canvas widget or listbox items.   For  the  canvas
                     widget, the item must already be present in the canvas widget and will be found with a find
                     withtag lookup.  For listbox widgets the item(s) may be created later but the programmer is
                     responsible  for  managing  the  link  between the listbox item index and the corresponding
                     tooltip. If the listbox items are re-ordered, the tooltips will need amending.

                     If the widget is not a canvas or listbox then an error is raised.

              -tag name
                     The -tag option can be used to set a tooltip for a text widget tag. The tag should  already
                     be  present  when this command is called or an error will be returned. The widget must also
                     be a text widget.

              --     The -- option marks the end of options.  The argument following this one will be treated as
                     message even if it starts with a -.

EXAMPLE

              # Demonstrate widget tooltip
              package require tooltip
              pack [label .l -text "label"]
              tooltip::tooltip .l "This is a label widget"

              # Demonstrate menu tooltip
              package require tooltip
              . configure -menu [menu .menu]
              .menu add cascade -label Test -menu [menu .menu.test -tearoff 0]
              .menu.test add command -label Tooltip
              tooltip::tooltip .menu.test -index 0 "This is a menu tooltip"

              # Demonstrate canvas item tooltip
              package require tooltip
              pack [canvas .c]
              set item [.c create rectangle 10 10 80 80]
              tooltip::tooltip .c -item $item "Canvas item tooltip"

              # Demonstrate listbox item tooltip
              package require tooltip
              pack [listbox .lb]
              .lb insert 0 "item one"
              tooltip::tooltip .lb -item 0 "Listbox item tooltip"

              # Demonstrate text tag tooltip
              package require tooltip
              pack [text .txt]
              .txt tag configure TIP-1 -underline 1
              tooltip::tooltip .txt -tag TIP-1 "tooltip one text"
              .txt insert end "An example of a " {} "tooltip" TIP-1 " tag.\n" {}

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes, will undoubtedly contain bugs and  other  problems.   Please
       report  such in the category tooltip of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist].  Please
       also report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

       balloon, help, hover, tooltip

COPYRIGHT

       Copyright (c) 1996-2008, Jeffrey Hobbs

tklib                                                 1.4.6                                         tooltip(3tk)