baltip

# LAST CHANGES:


Version `1.4.2 (6 Oct'22)`

  - BUGFIX: baltip::cget to return {} on a widget without a tip
  - NEW   : baltip::show to show tips on click, timer etc. (not on hovering widgets)


Version `1.4.1 (14 Sep'22)`

  - NEW   : for a widget: baltip::configure w -opt val ?-opt val?
  - NEW   : for a widget: baltip::cget w -opt
  - CHANGE: -pause option: default 1000 (1sec.) instead of 600

To update a tip's text and options:

      ::baltip::update widgetpath text ?options?

When you click on a widget with its tip being displayed, the tip is hidden. It is the default behavior of *baltip*, but sometimes you need to re-display the hidden tip. If the widget is a button, you can include the following command in `-command` of the button:

      ::baltip::repaint widgetpath

To show a tip under the mouse pointer, e.g. on clicking, timeout, processing etc.:

      ::baltip::show text ?options?

## Some special tips

The "text" for *listbox* can contain %i wildcard - and in such cases the text means a callback receiving a current index of item to tip:

      proc ::lbxTip {idx} {
        set item [lindex $::lbxlist $idx]
        return "Tip for \"$item\"\nindex=$idx"
      }

Also, you can test *baltip* with *test2_pave.tcl* of [apave package](https://chiselapp.com/user/aplsimple/repository/pave/download).

## Acknowledgements

The *baltip* package has been developed with help of these kind people:

  * [Nicolas Bats](https://github.com/sl1200mk2) prompted to add canvas tags' tips, baltip::show procedure and tested *baltip* in MacOS

  * [Csaba Nemethi](https://www.nemethi.de/) sent several bug fixes and advices, especially on listbox, treeview and menu tips

## Links

  * [Source at chiselapp](https://chiselapp.com/user/aplsimple/repository/baltip/download) (baltip.zip)

  * [Source at github](https://github.com/aplsimple/baltip)

  * [Reference](https://aplsimple.github.io/en/tcl/baltip/baltip.html)

  * [Demo of baltip v1.3.1](https://github.com/aplsimple/baltip/releases/download/baltip-1.3.1/baltip-1.3.1.mp4)

###########################################################
# Name:    baltip.tcl
# Author:  Alex Plotnikov  (aplsimple@gmail.com)
# Date:    12/01/2021
# Brief:   Handles Tcl/Tk tip widget.
# License: MIT.
###########################################################

package provide baltip 1.4.2

package require Tk

# ________________________ Variables _________________________ #

namespace eval ::baltip {

  namespace export configure cget tip update hide repaint \
    optionlist tippath clear sleep show
  namespace ensemble create

  namespace eval my {
    variable ttdata; array set ttdata [list]
    set ttdata(on) yes
    set ttdata(per10) 1600
    set ttdata(fade) 300

  variable my::ttdata
  array unset my::ttdata winGEO*
  if {[winfo exists $w] || $w eq {}} {
    if {$text in {-BALTIPGET -BALTIPSET}} {
      # "-BALTIPGET" is the same as "-BALTIPSET", just supposed not to include args
      if {![info exists my::ttdata(optvals,$w)]} {
        if {$text eq {-BALTIPGET}} {return {}}
        set my::ttdata(optvals,$w) [dict create]
      }
      set my::ttdata(optvals,$w) [dict replace $my::ttdata(optvals,$w) {*}$args]
      if {$text eq {-BALTIPGET}} {
        return $my::ttdata(optvals,$w)
      }
      if {[catch {set text [dict get $my::ttdata(optvals,$w) -text]}]} {

  # Disables tips for a while.
  #   msec - time to sleep, in msec
  # This is useful esp. before calling a popup menu on listbox/treeview.

  configure -on no
  after $msec "::baltip::configure -on yes"
}

#_______________________

proc ::baltip::show {tip args} {
  # Shows a tip under the pointer.
  #   tip - text of tip
  #   args - miscellaneous options of baltip
  # Can be used to show tips on clicking, timeout, processing etc.

  variable my::ttdata
  set w .
  lassign [winfo pointerxy $w] x y
  set geo +[expr {$x-int($my::ttdata(under)/2)}]+[expr {$y-$my::ttdata(under)}]
  tip $w $tip -geometry $geo -pause 0 -fade 0 {*}$args
}

# _____________________ Internals ____________________ #

proc ::baltip::my::CGet {args} {
  # Gets options' values, using local (args) and global (ttdata) settings.
  #   args - local settings ("name value" pairs)
  # Returns the full list of settings ("name value" pairs, "name" without "-") \

package ifneeded baltip 1.4.2 [list source [file join $dir baltip.tcl]]

namespace eval ::baltip {
  variable _ruff_preamble {
It's a Tcl/Tk tip widget inspired by:

  * [https://wiki.tcl-lang.org/page/Tklib+tooltip](https://wiki.tcl-lang.org/page/Tklib+tooltip)

To update a tip's text and options:

      ::baltip::update widgetpath text ?options?

When you click on a widget with its tip being displayed, the tip is hidden. It is the default behavior of *baltip*, but sometimes you need to re-display the hidden tip. If the widget is a button, you can include the following command in `-command` of the button:

      ::baltip::repaint widgetpath

To show a tip under the mouse pointer, e.g. on clicking, timeout, processing etc.:

      ::baltip::show text ?options?

## Some special tips

The "text" for *listbox* can contain %i wildcard - and in such cases the text means a callback receiving a current index of item to tip:

      proc ::lbxTip {idx} {
        set item [lindex $::lbxlist $idx]
        return "Tip for \"$item\"\nindex=$idx"
      }

Also, you can test *baltip* with *test2_pave.tcl* of [apave package](https://chiselapp.com/user/aplsimple/repository/pave/download).

## Acknowledgements

The *baltip* package has been developed with help of these kind people:

  * [Nicolas Bats](https://github.com/sl1200mk2) prompted to add canvas tags' tips, baltip::show procedure and tested *baltip* in MacOS

  * [Csaba Nemethi](https://www.nemethi.de/) sent several bug fixes and advices, especially on listbox, treeview and menu tips

## Links

  * [Source at chiselapp](https://chiselapp.com/user/aplsimple/repository/baltip/download) (baltip.zip)

      \nI feel $msg" -under 0 -force yes -image $img -compound $cmpd
    ::baltip update .l "It's okay. Come on!" \
      {*}[::baltip cget -fg -bg -font -padx -pady]  -per10 1500
  }
  if {$::ttt>7} {set ::ttt -2}
}
#_______________________
proc ::but1Comm {} {
  ::baltip show "This tip is displayed only on clicking!\nNo matter other tips are enabled or not." -pause 500 -fade 500 -per10 1000
  puts "::but1Comm to be continued..."
}
#_______________________

proc ::chbComm {}  {
    puts "all tips [if $::on {set _ enabled} {set _ disabled}]"
    ::baltip config -global yes -on $::on -fg $::fg -bg $::bg
    ::baltip update .cb "After clicking:\nnew tip & options" \
      -fg maroon -padding 2 -padx 15 -pady 15 -global 0
    if {$::on} {::baltip repaint .cb}

image create photo TEST_TCL_IMAGE1 -data $tclimg

image create photo TEST_TCL_IMAGE2 -data $warnimg

# _____________________________________ Widgets _____________________________________ #

button .b -text Hello -command ::butComm
ttk::button .b1 -text {On click} -command ::but1Comm

set geo +999999+85  ;# 999999 to get it the most right
set alpha 0.5
lassign [::baltip cget -fg -bg] - ::fg - ::bg
set ::fg0 $::fg
set ::bg0 $::bg
set ::fg1 white

set ::on 1
checkbutton .cb -text "Tips on" -variable ::on -command ::chbComm

label .status -relief sunken -anchor w -width 31

# _____________________________________ Pack _____________________________________ #

pack .b .b1 .l .b2
pack .t -expand 1 -fill x
pack .lb -expand 1 -fill x
pack .tre -expand 1 -fill both
pack .cb
pack .status -fill x
update
set ww [winfo width .]