"Balloon help" is sometimes known as "[tooltips]".





Effective Tcl's example code ( http://sf.net/projects/efftcl/ )
[http://www.awl.com/cseng/titles/0-201-63474-0/efftcl-ex.tar.Z]
as well as [Jeffrey Hobbs]'s widget library
[http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcllib/widget/library/balloonhelp.tcl]
include a balloonhelp.tcl

[[Where is its documentation?]]

[Bwidgets] have balloons under the title of "Dynamic help", here's an example how simple that can be ([RS]):
    interp alias {} help {} DynamicHelp::register
    Button .f.open -image $im(open) -command {starDOM::openFile .t}
    help .f.open balloon "Open existing XML file"

[Tix] has a ballon widget: see http://tix.sourceforge.net/man/html/TixCmd/tixBalloon.htm


----

[[Also describe the section in the M&M book.]]



This [Wiki] also has a related page under the title "[Balloon]", and this was from the [bag of Tk algorithms]:

Balloon help, (a.k.a. tooltips), minimalist version

  proc balloon {w help} {
    bind $w <Any-Enter> "after 1000 [list balloon:show %W [list $help]]"
    bind $w <Any-Leave> "destroy %W.balloon"
  }
  proc balloon:show {w arg} {
    if {[eval winfo containing  [winfo pointerxy .]]!=$w} {return}
    set top $w.balloon
    catch {destroy $top}
    toplevel $top -bd 1 -bg black
    wm overrideredirect $top 1
    if {$::tcl_platform(platform) == "macintosh"} {
     unsupported1 style $top floating sideTitlebar
    }
    pack [message $top.txt -aspect 10000 -bg lightyellow \
            -font fixed -text $arg]
    set wmx [winfo rootx $w]
    set wmy [expr [winfo rooty $w]+[winfo height $w]]
    wm geometry $top \
      [winfo reqwidth $top.txt]x[winfo reqheight $top.txt]+$wmx+$wmy
    raise $top
 }
 # Example:
  button  .b -text Exit -command exit
  balloon .b "Push me if you're done with this"
  pack    .b
DAS - added an 'unsupported1' command to make this work on macs as well, otherwise raising the balloon window would immediately post a Leave event leading to the destruction of the balloon... The 'unsupported1' command makes the balloon window into a floating window which does not put the underlying window into the background and thus avoids the problem. (BTW, for this to work, appearance manager needs to be present, but that shouldn't be a problem for all except very old macs, otherwise you can try using the older 'unsupported1 style $top floatSideProc' although I had problems with it)

[GPS]: I know from experience with earlier balloon code that the code has a problem.  If the $help string contains % then you will probably experience weird problems.  The way to fix this is to use string map to double % if they exist.

tcl[ol]:
 # dont try this at home:
 balloon .b "hey \[you\] }{ )( $ %"

I would rather do it using a global variable to store the help text. Generally I avoid having text in after or callback scripts. More, using a global can be useful for debugging or translating.

I modified the balloons script above.
Move the help/ folder in directory [lindex $tcl_pkgPath 0]

# you can replace 'help' with 'balloon' 
# i keep the balloon for my quick black dog jumping over lazy foxes

help/pkgIndex.tcl:

 package ifneeded help 1.0 [list source [file join $dir help.tcl]]



help/help.tcl:

 namespace eval ::help {
   namespace export set
   variable delay 1000
 }

 proc help::set {widget txt} {
   variable help
   ::set help($widget) $txt
   bind $widget <Enter> {after $help::delay [list help::show %W]}
   bind $widget <Leave> {destroy %W.help}
 }

 proc help::show {widget} {

   variable help

   if {[eval winfo containing [winfo pointerxy .]]!=$widget} {return}

   ::set w $widget.help
   catch {destroy $w}
   toplevel $w -bd 1 -bg black
   wm overrideredirect $w 1
   if {$::tcl_platform(platform) == "macintosh"} {
    unsupported1 style $w floating sideTitlebar
   }

   pack [message $w.txt -aspect 10000 -bg lightyellow -font fixed -text $help($widget)]

   ::set wmx [winfo rootx $widget]
   ::set wmy [expr [winfo rooty $widget]+[winfo height $widget]]
   wm geometry $w [winfo reqwidth $w.txt]x[winfo reqheight $w.txt]+$wmx+$wmy
   #useless ?
   raise $w
 }
 package provide help 1.0



help/test.tcl:
 
 package require help
 interp alias {} help {} help::set

 button .b
 pack .b
 help .b "hey \[you\] }{ )( $ %"


----
[EKB] I made a couple of modest changes to the minimalist code (without the fixes for embedding %s and other characters).

There are two changes:
   * A "balloon_delay" proc with associated global variable "last_balloon" that has the balloon pop up quickly if the user is scanning (e.g., scanning across a toolbar), and more slowly initially.
   * Adding a "+" to the start of the binding procs so that other actions that should take place as the widget is entered and exited can also take place.

It's still not as smooth as a "real" balloon help, but it works well enough for my purposes.

 set last_balloon 0

 proc balloon_delay {} {
    global last_balloon
    
    set curr_balloon [clock seconds]
    if {[expr $curr_balloon - $last_balloon] < 3} {
        set delay 50
    } else {
        set delay 1000
    }
    set last_balloon $curr_balloon
    return $delay
 }
 
 proc set_balloon {w help} {
    bind $w <Enter> "+after \[balloon_delay\] [list balloon:show %W [list $help]]"
    bind $w <Leave> "+destroy %W.balloon"
 }

 proc balloon:show {w arg} {
    if {[eval winfo containing  [winfo pointerxy .]]!=$w} {return}
    set top $w.balloon
    catch {destroy $top}
    toplevel $top -bd 1 -bg black
    wm overrideredirect $top 1
    if {$::tcl_platform(platform) == "macintosh"} {
        unsupported1 style $top floating sideTitlebar
    }
    pack [message $top.txt -aspect 10000 -bg lightyellow \
            -text $arg]
    set wmx [winfo rootx $w]
    set wmy [expr [winfo rooty $w]+[winfo height $w]]
    wm geometry $top \
      [winfo reqwidth $top.txt]x[winfo reqheight $top.txt]+$wmx+$wmy
    raise $top
 }


----
[category gui]