iwidgets::toolbar(1)

📦 version 4.1.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 iwidgets::toolbar — the manual, bestie edition 💅

okay so this is iwidgets::toolbar(1) from the [incr Widgets] manual, section 1. sit down, grab a strawberry 🍓, we're building tool bars.

🌸 NAME 🌸

iwidgets::toolbar — create and manipulate a tool bar. that's it, that's the name, it's giving "I make toolbars" and honestly? iconic.

✨ SYNOPSIS ✨

iwidgets::toolbar pathName ?options?

🦋 INHERITANCE 🦋

itk::Widget <- iwidgets::Toolbar

so it's an itk::Widget at heart, and it picked up the Toolbar genes along the way. 🧬

🎀 STANDARD OPTIONS 🎀

your toolbar comes pre-loaded with all the classic fits, no cap:

  • activeBackground
  • activeForeground
  • background
  • borderWidth
  • cursor
  • disabledForeground
  • font
  • foreground
  • highlightBackground
  • highlightColor
  • highlightThickness
  • insertBackground
  • insertForeground
  • orient
  • selectBackground
  • selectBorderWidth
  • selectForeground
  • state
  • troughColor

for the deets on the standard options, go read the "options" manual entry, bestie, it's all there.

and here's the cute part: for any widgets you add to the toolbar, these options get propagated to them if the widget actually supports that option. like, every widget that supports a font option will get changed when you configure the toolbar's font option. it's a group chat, everyone hears the news. 🫶

💅 WIDGET-SPECIFIC OPTIONS 💅

these are the options that are hers, the ones that make a toolbar a toolbar:

  • -ballooonbackground (Name: balloonBackground, Class: BalloonBackground) — sets the background color of the balloon help that pops up at the bottom center of a widget on the toolbar when that widget has a non-empty string for its balloonStr option. default color is yellow. yes the command-line switch really has three o's, we do not question the ancestors. 🙈
  • -balloondelay1 (Name: balloonDelay1, Class: BalloonDelay1) — how long, in milliseconds, to wait before it first posts a balloon help hint window. this delay is in effect whenever 1) the mouse leaves the toolbar, or 2) a toolbar item gets selected with the mouse button. ⏱️
  • -balloondelay2 (Name: balloonDelay2, Class: BalloonDelay2) — how long, in milliseconds, to wait before it keeps posting balloon help hint windows. this one kicks in after the first time a balloon hint window activates, and stays in effect until 1) the mouse leaves the toolbar, or 2) a toolbar item gets selected with the mouse button. so delay1 is the first-date nerves, delay2 is the comfortable texting rhythm. 💬
  • -balloonfont (Name: balloonFont, Class: BalloonFont) — the font for the balloon help text shown at the bottom center of a widget on the toolbar that has a non-empty string for its balloonStr option. default font is 6x10. tiny but mighty. 🐜
  • -ballooonforeground (Name: balloonForeground, Class: BalloonForeground) — the foreground color of the balloon help shown at the bottom center of a widget on the toolbar that has a non-empty string for its balloonStr option. default color is black. (again: three o's. -ballooonforeground. love that for us. 💀)
  • -helpvariable (Name: helpVariable, Class: HelpVariable) — the global variable to update whenever the mouse is in motion over a toolbar widget. it gets updated with the current value of the active widget's helpStr. other widgets can "watch" this variable with the trace command, or — like with entry or label widgets — they can set their textVariable to that same global variable. that's a whole help status bar, DIY edition, no extra widgets required. ✨ and whenever the mouse leaves a menu entry, helpVariable gets set to the empty string {}. poof. 🌬️
  • -orient (Name: orient, Class: Orient) — the orientation of the toolbar. must be either horizontal or vertical. those are your two options, there is no third, don't try it. 🚫

🌈 DESCRIPTION 🌈

so iwidgets::toolbar creates a brand new window (the one you hand it as the pathName argument) and turns it into a toolbar widget. you can pass extra options — the ones we just listed above — on the command line or in the option database to configure stuff like its colors, font, and orientation. iwidgets::toolbar returns its pathName argument, like a good friend returning your hoodie. 🧥

⚠️ important vibe check: at the time this command is invoked, there must not already exist a window named pathName — but pathName's parent does have to exist. no duplicates, no orphans. periodt.

a toolbar is a widget that displays a collection of widgets arranged either in a row or a column, depending on the value of the -orient option. this little collection is usually there for user convenience, giving folks access to a set of commands or settings. any widget can be placed on a toolbar — no gatekeeping here — but command or value-oriented widgets (like button, radiobutton, etc.) are usually the most useful kind to appear on one. they just fit the vibe best. 👑

on top of all that, the toolbar adds two new options to every widget that gets added to it: the helpStr and balloonStr options. for the full discussion on those, see the writeup for the widget command add below. 👇

~ to be continued, bestie, we're only getting started ~

💅 WIDGET-SPECIFIC METHODS 💅

okay bestie, so the iwidgets::toolbar command spins up a brand new Tcl command and its name is pathName. that command is your little remote control for the widget — you use it to run alllll the various operations. general form goes like this:

pathName option ?arg arg ...?

the option and args you hand it decide exactly what the command does. no notes. 💅

a lot of the toolbar's widget commands take an argument that says which widget item you're operating on. that indicator is called an index, and it can come in any of these flavors:

  • number — picks the widget numerically. 0 = the first widget in the notebook, 1 = the second, and so on forever. (for a horizontal toolbar, 0 is the leftmost; for a vertical one, 0 is the topmost.) 💖
  • end — the last widget in the toolbar's index. if the toolbar is empty, this returns -1. rude but okay.
  • last — literally the same thing as end. twins fr.
  • pattern — if your index doesn't match any of the above, this form kicks in. pattern gets pattern-matched against the widgetName of every widget in the toolbar, in order from first to last, until something matches. and an exact match must occur — no vibes-based fuzzy matching here, sorry bestie.

so these are the commands a toolbar widget can do 🫶

  • pathName add widgetCommand widgetName ?option value? — adds a widget to the toolbar, using the command widgetCommand and giving it the name widgetName. if widgetCommand is radiobutton or checkbutton, its packing gets slightly padded so it matches the geometry of button widgets. on top of that, the indicatorOn option defaults to false and selectColor defaults to the toolbar's background. this is the whole trick that lets you drop Radiobutton and Checkbutton widgets in as icons — you just set their bitmap or image options and you're done, iconic. ✨

if there are extra arguments hanging around, those are the set of available options that the widget type of widgetCommand supports. and in addition they may also be one of these:

  • -helpstr value — specifies the help string to associate with the widget. when the mouse moves over the widget, the variable denoted by helpVariable gets set to helpStr. another widget can bind to that helpVariable and thus track status help. 👀
  • -balloonstr value — specifies the string to display in a balloon window for this widget. a balloon window is a small popup window centered at the bottom of the widget. usually the balloonStr value is the name of the item on the toolbar. it's sometimes known as a hint window.

when the mouse moves into an item on the toolbar, a timer is set based on the value of balloonDelay1. if the mouse stays inside the item for balloonDelay1, the balloon window pops up displaying the balloonStr value. once the balloon window is posted, a new timer based on balloonDelay2 gets set — this one's typically shorter. if the mouse moves to another item, the window is unposted and a new window will be posted over the item if the shorter delay time is satisfied.

while the balloon window is posted, it can also be unposted if the item is selected. in that case the timer is reset to balloonDelay1. and whenever the mouse leaves the toolbar, the timer is also reset to balloonDelay1. 🔁

this whole posting/unposting model is the same model used in the Windows95 environment. yes, really. retro of it.

  • pathName cget option — returns the current value of the configuration option given by option. simple, clean, slay.
  • pathName configure ?option value? — query or modify the configuration options of the widget. if you don't pass an option, it returns a list describing all the available options for pathName (peep Tk_ConfigureInfo for info on the format of that list). if you pass option with no value, you get back a list describing just that one named option — and that list will be identical to the corresponding sublist of the value you'd get with no option at all. if you pass one or more option-value pairs, then it modifies the given widget option(s) to have the given value(s), and in that case the command returns an empty string.
  • pathName delete index ?index2? — deletes all the items between index and index2, inclusive. if index2 is omitted, it defaults to index. returns an empty string. bye babes 💀
  • pathName index index — returns the widget's numerical index for the entry corresponding to index. if index is not found, -1 comes back at you.
  • pathName insert beforeIndex widgetCommand widgetName ?option value? — inserts a new item named widgetName, with the command widgetCommand, before the item specified by beforeIndex. if widgetCommand is radiobutton or checkbutton, its packing is slightly padded to match the geometry of button widgets. plus the indicatorOn option is false by default and the selectColor is that of the toolbar background by default — which is exactly what lets Radiobutton and Checkbutton widgets be added as icons just by setting their bitmap or image options. the set of available options is the same as specified in the ad command. 💫
  • pathName itemcget index option — returns the current value of the configuration option given by option for index. the item type of index determines which options are valid and available.
  • pathName itemconfigure index ?option value? — query or modify the configuration options of the widget of the toolbar specified by index. if no option is specified, it returns a list describing all of the available options for index (again, see Tk_ConfigureInfo for the format of that list). if option is specified with no value, the command returns a list describing that one named option (identical to the corresponding sublist of the value you'd get with no option specified). if one or more option-value pairs are specified, the command modifies the given widget option(s) to have the given value(s) — and in that case it returns an empty string. the item type of index determines the valid available options, and the set of available options is the same as specified in the ad command.

🌈 EXAMPLE 🌈

here's the whole thing in action, bestie. copy it, run it, live your truth:

        package require Iwidgets 4.0
        iwidgets::toolbar .tb -helpvariable statusVar

        .tb add button item1 \
           -helpstr "Save It" -bitmap @./icons/Tool_32_box.xbm \
           -balloonstr "Save" -command {puts 1}
        .tb add button item2 \
           -helpstr "Save It" -bitmap @./icons/Tool_32_brush.xbm \
           -balloonstr "Save" -command {puts 1}
        .tb add button item3 \
           -helpstr "Save It" -bitmap @./icons/Tool_32_cut.xbm \
           -balloonstr "Save" -command {puts 1}
        .tb add button item4 \
           -helpstr "Save It" -bitmap @./icons/Tool_32_draw.xbm \
           -balloonstr "Save" -command {puts 1}
        .tb add button item5 \
           -bitmap @./icons/Tool_32_erase.xbm -helpstr "Play It" \
           -command {puts 2}
        .tb add frame filler \
           -borderwidth 1 -width 10 -height 10
        .tb add radiobutton item6 \
           -bitmap @./icons/Tool_32_oval.xbm -command {puts 4} \
           -variable result -value OPEN -helpstr "Radio Button # 1" \
           -balloonstr "Radio"
        .tb add radiobutton item7 \
           -bitmap @./icons/Tool_32_line.xbm -command {puts 5} \
           -variable result -value CLOSED
        .tb add checkbutton item8 \
           -bitmap @./icons/Tool_32_text.xbm -command {puts 6} \
           -variable checkit -onvalue yes -offvalue no
        .tb add checkbutton check2 \
           -bitmap @./icons/Tool_32_points.xbm -command {puts 7} \
            -variable checkit2 -onvalue yes -offvalue no

        pack .tb -side top -anchor nw

look at all those buttons and radiobuttons and checkbuttons living their best lives. that frame filler with -borderwidth 1 -width 10 -height 10 is just there holding space like a true main character. 👑

👑 AUTHOR 👑

Bill Scott. periodt. 💜

🌸 KEYWORDS 🌸

toolbar, button, radiobutton, checkbutton, iwidgets, widget

and that's a wrap on the whole page, bestie! this one's from Tk, and it's the iwidgets::toolbar(1) manual page — go forth and build the cutest little toolbars the world has ever seen. no cap, you've got this. 🦋✨💖

📦 where this page comes from