tooltip(n)                    Tooltip management                    tooltip(n)



______________________________________________________________________________

NAME
       tooltip - Tooltip management

SYNOPSIS
       package require Tcl  8.4

       package require msgcat  1.3

       package require tooltip  ?1.4.4?

       ::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.

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.4                          tooltip(n)
