iwidgets::menubar(1)

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

🌸 iwidgets::menubar(1) 🌸

okay bestie, this is the iwidgets::menubar page from [incr Widgets], and it's literally the blueprint for creating and manipulating menubar menu widgets. Part 1, let's go 💖

✨ NAME ✨

iwidgets::menubar — create and manipulate menubar menu widgets

🌸 SYNOPSIS 🌸

iwidgets::menubar pathName ?options?

💫 INHERITANCE 💫

itk::Widget <- iwidgets::Menubar

🫶 STANDARD OPTIONS 🫶

Here's the whole standard-option squad, no cap:

  • activeBackground
  • activeBorderWidth
  • activeForeground
  • anchor
  • background
  • borderWidth
  • cursor
  • disabledForeground
  • font
  • foreground
  • highlightBackground
  • hightlightColor
  • highligthThickness
  • justify
  • relief
  • padX
  • padY
  • wrapLength

See the options manual entry for details on the standard options.

💅 WIDGET-SPECIFIC OPTIONS 💅

🎀 helpVariable 🎀

  • Name: helpVariable
  • Class: HelpVariable
  • Command-Line Switch: -helpvariable

Specifies the global variable to update whenever the mouse is in motion over a menu entry. This global variable is updated with the current value of the active menu entry's helpStr. Other widgets can "watch" this variable with the trace command, or — as is the case with entry or label widgets — they can set their textVariable to the same global variable. This allows for a simple implementation of a help status bar. Whenever the mouse leaves a menu entry, the helpVariable is set to the empty string {}. The mainwindow(1) associates its helpstatus and its menubar in this fashion. 🫶

  • Name: menuButtons
  • Class: MenuButtons
  • Command-Line Switch: -menubuttons

The menuButton option is a string which specifies the arrangement of menubuttons on the menubar frame. Each menubutton entry is delimited by the newline character.

iwidgets::menubar .mb -menubuttons {
        menubutton file -text File
        menubutton edit -text Edit
        menubutton options -text Options
}

specifies that three menubuttons will be added to the menubar (file, edit, options). Each entry is translated into an add command call.

The menuButtons option can accept embedded variables, commands, and backslash quoting. Embedded variables and commands must be enclosed in curly braces ({}) to ensure proper parsing of the substituted values. 💅

📖 DESCRIPTION 📖

The iwidgets::menubar command creates a new window (given by the pathName argument) and makes it into a menubar menu widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the menubar such as its colors and font. The iwidgets::menubar command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist. no cap, that parent has to be there first.

A menubar is a widget that simplifies the task of creating menu hierarchies. It encapsulates a frame widget, as well as menubuttons, menus, and menu entries. The menubar allows menus to be specified and referenced in a more consistent manner than using Tk to build menus directly. it's giving organized.

Menubar allows a menu tree to be expressed in a hierarchical "language". The menubar accepts a menuButtons option that allows a list of menubuttons to be added to the menubar. In turn, each menubutton accepts a menu option that specifies a list of menu entries to be added to the menubutton's menu. Cascade entries also accept the menu option for specifying a list of menu entries to be added to the cascade's menu. 🌈

Additionally, the menubar allows each component of the menubar system to be referenced by a simple menuPathName syntax. The menubar also extends the set of options for menu entries to include a helpStr option. 👑

A menuPathName is a series of component names separated by the . character. Each menubar component can be referenced via these menuPathNames. menuPathNames are similar to widget pathNames in Tk. Some correspond directly to a widget pathName (components of type menu or menubutton), others correspond to a menu entry type. Every widget and entry in a menubar can be referenced with the menuPathName naming convention. A menubar can have four types of components:

  • frame. A menubar holds exactly one frame which manages menubuttons. The frame is always signified by the . character as the path name.
  • menubutton. A menubutton corresponds directly to a Tk menubutton. See menubutton(n).
  • menu. A menu is attached to a menubutton and corresponds directly to Tk's menu widget. A menu is always signified by the menuPathName ending with the keyword menu. See menu(n).
  • entry. An entry corresponds directly to Tk's menu widget entries. Menus consist of a column of one line entries. Entries may be of type: command, checkbutton, radiobutton, separator, or cascade. For a complete description of these types see the discussion on ENTRIES in menu(n).

The suffix of a menuPathName may have the form of:

  • tkWidgetName — Specifies the name of the component, either a frame, menubutton, menu, or an entry. This is the normal naming of widgets. For example, .file references a menubutton named file.

The menuPathName is a series of segment names, each separated by the . character. Segment names may be one of the following forms:

  • number — Specifies the index of the component. For menubuttons, 0 corresponds to the left-most menubutton of the menu bar frame. As an example, .1 would correspond to the second menubutton on the menu bar frame.

For entries, 0 corresponds to the top-most entry of the menu. For example, .file.0 would correspond to the first entry on the menu attached to the menubutton named file.

  • end — Specifies the last component. For menubuttons, it specifies the right-most entry of the menu bar frame. For menu entries, it specifies the bottom-most entry of the menu.
  • last — Same as end.

Finally, menu components always end with the menu keyword. These components are automatically created via the -menu option on menubuttons and cascades or via the add or insert commands.

  • menu — Specifies the menu pane that is associated with the given menubutton prefix. For example, .file.menu specifies the menu pane attached to the .file menubutton.

For example, the path .file.new specifies the entry named new on the menu associated with the file menubutton located on the menu bar. The path .file.menu specifies the menu pane associated with the menubutton .file. The path .last specifies the last menu on the menu bar. The path .0.last would specify the first menu (file) and the last entry on that menu (quit), yielding .file.quit.

🚨 As a restriction, the last name segment of menuPathName cannot be one of the keywords last, menu, end, nor may it be a numeric value (integer).

💅 WIDGET-SPECIFIC METHODS 💅

Okay bestie, this is the good part. The iwidgets::menubar command makes a brand-new Tcl command, and its name is pathName. You use that command to do literally all the things to your widget. Here's the general shape of it:

pathName option ?arg arg ...?

option and the args decide exactly what the command does. Simple as that. 🫶

Also, real talk: lots of these menubar widget commands take a path name to a menu component as one of their arguments. Those path names are called menuPathNames. Go peep the MENUBAR PATH NAMES discussion above if you need the refresher. ✨

Here are all the commands you can throw at a menubar widget:

  • pathName add type menuPathName ?option value option value? — Adds either a menu to the menu bar, or a menu entry to a menu pane. 💫

If you pass extra arguments, they specify the options available to component type entry. Check the menu(1) man pages, in the section on ENTRIES, for those.

If type is one of cascade, checkbutton, command, radiobutton, or separator, it adds a brand-new entry to the bottom of the menu denoted by the prefix of menuPathName. If there are additional arguments, they specify options available to menu entry widgets. On top of that, the helpStr option gets added by the menubar widget to all components of type entry. 💖

  • -helpstr value — Specifies the string to associate with the entry. When the mouse moves over the associated entry, the variable denoted by helpVariable is set. Another widget can bind to the helpVariable and thus display status help. 🎀

If the type of the component you're adding is menubutton or cascade, then a menubutton or cascade gets added to the menubar. If there are additional arguments, they specify options available to menubutton or cascade widgets. On top of that, the menu option gets added by the menubar widget to all menubutton and cascade widgets.

  • -menu menuSpec — This one is only valid for menuPathNames of type menubutton or cascade. It specifies an option set and/or a set of entries to place on a menu and associate with the menubutton or cascade. The option keyword lets the menu widget be configured. Each item in the menuSpec is treated as an add command (each with the possibility of having other -menu options). And the way that works? A menu can be recursively built. 🌀

Heads up though: the last segment of menuPathName cannot be one of the keywords last, menu, or end. Also, it may not be a number. But the menuPathName itself can totally be referenced that way (see the discussion of COMPONENT PATH NAMES).

Also also: the same curly brace quoting rules apply to -menu option strings as did to -menubuttons option strings. Go back to the earlier discussion on umenubuttons in the "WIDGET-SPECIFIC OPTIONS" section. 🦋

  • pathName cget option — Returns the current value of the configuration option given by option. Classic. 👑
  • pathName configure ?options value option value? — Query or modify the configuration options of the widget. If no option is specified, it returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for info on the format of this list). If option is specified with no value, then the command returns a list describing that one named option (and this list will be identical to the corresponding sublist of the value returned when no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s) — and in that case the command returns an empty string. 💅
  • pathName delete menuPathName ?menuPathName2? — If menuPathName is of component type Menubutton or Menu, delete operates on menus. If menuPathName is of component type Entry, delete operates on menu entries. 🗑️

This command deletes all components between menuPathName and menuPathName2, inclusive. If menuPathName2 is omitted then it defaults to menuPathName. Returns an empty string.

If menuPathName is of type menubar, then all menus and the menu bar frame will be destroyed. In that case menuPathName2 is ignored. 💀

  • pathName index menuPathName — If menuPathName is of type menubutton or menu, it returns the position of the menu/menubutton on the menubar frame. 🌈

If menuPathName is of type command, separator, radiobutton, checkbutton, or cascade, it returns the menu widget's numerical index for the entry corresponding to menuPathName. If the path is not found, or the path is equal to ., a value of -1 is returned. 🙈

  • pathName insert menuPathName type name ?option value? — Insert a new component named name before the component specified by menuPathName. ⭐

If menuPathName is of type Menubutton or Menu, the new component inserted is of type Menu and gets the name name. In this case, the valid option value pairs are those accepted by menubuttons.

If menuPathName is of type Entry, the new component inserted is of type entry and gets the name name. In this case, the valid option value pairs are those accepted by menu entries. And ngl, name cannot be one of the keywords last, menu, or end. It also may not be a number. But the menuPathName can be referenced that way (see the discussion of COMPONENT PATH NAMES). 🧚

  • pathName invoke menuPathName — Invoke the action of the menu entry denoted by menuPathName. See the sections on the individual entries in the menu(1) man pages. If the menu entry is disabled then nothing happens (iconic, honestly — it's resting). If the entry has a command associated with it, then the result of that command is returned as the result of the invoke widget command. Otherwise the result is an empty string. 🔥

If menuPathName is not a menu entry, an error is issued. 😭

  • pathName menucget menuPathName option — Returns the current value of the configuration option given by option. The component type of menuPathName determines the valid available options. ✨
  • pathName menuconfigure menuPathName ?option value? — Query or modify the configuration options of the component of the menubar specified by menuPathName. If no option is specified, it returns a list describing all of the available options for menuPathName (see Tk_ConfigureInfo for info on the format of this list). If option is specified with no value, then the command returns a list describing that one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s) — and in this case the command returns an empty string. The component type of menuPathName determines the valid available options. 🫶
  • pathName path ?mode? pattern — Returns a fully formed menuPathName that matches pattern. If no match is found it returns -1. The mode argument tells you how the search is to be matched against pattern, and it must be one of these values:
    • -glob — pattern is a glob-style pattern which is matched against each component path using the same rules as the string match command. 🌸
    • -regexp — pattern is treated as a regular expression and matched against each component of the menuPathName using the same rules as the regexp command. 💜

The default mode is -glob. 💫

  • pathName type menuPathName — Returns the type of the component specified by menuPathName. For menu entries, this is the type argument you passed to the add/insert widget command when the entry was created — something like command or separator. Otherwise it's either a menubutton or a menu. 👑
  • pathName yposition menuPathName — Returns a decimal string giving the y-coordinate within the menu window of the topmost pixel in the entry specified by menuPathName. If the menuPathName is not an entry, an error is issued. 📐

🌈 EXAMPLE ONE: USING GRAMMAR 🌈

okay bestie, real talk, here's what the actual code looks like. This one builds a menubar with File, Edit and Options menubuttons. Every single one of those menubuttons has an associated menu riding along with it. Then the File menu has menu entries, and so does the Edit menu, and so does the Options menu. The Options menu is a tearoff menu with selectColor (that's the one for radiobuttons, iykyk) set to blue. On top of that, the Options menu has a cascade titled More, with several menu entries attached to it as well. And there's an entry widget in there just vibing to display the help status. periodt.

package require Iwidgets 4.0
iwidgets::menubar .mb -helpvariable helpVar -menubuttons {
    menubutton file -text File -menu {
        options -tearoff false
        command new -label New \
            -helpstr "Open new document" \
            -command {puts NEW}
        command close -label Close \
            -helpstr "Close current document" \
            -command {puts CLOSE}
        separator sep1
        command exit -label Exit -command {exit} \
            -helpstr "Exit application"
    }
    menubutton edit -text Edit -menu {
        options -tearoff false
        command undo -label Undo -underline 0 \
            -helpstr "Undo last command" \
            -command {puts UNDO}
        separator sep2
        command cut -label Cut -underline 1 \
            -helpstr "Cut selection to clipboard" \
            -command {puts CUT}
        command copy -label Copy -underline 1 \
            -helpstr "Copy selection to clipboard" \
            -command {puts COPY}
        command paste -label Paste -underline 0 \
            -helpstr "Paste clipboard contents" \
            -command {puts PASTE}
    }
    menubutton options -text Options -menu {
        options -tearoff false -selectcolor blue
        radiobutton byName -variable viewMode \
            -value NAME -label "by Name" \
            -helpstr "View files by name order" \
            -command {puts NAME}
        radiobutton byDate -variable viewMode \
            -value DATE -label "by Date" \
            -helpstr "View files by date order" \
            -command {puts DATE}
        cascade prefs -label Preferences -menu {
            command colors -label Colors... \
                -helpstr "Change text colors" \
                -command {puts COLORS}
            command fonts -label Fonts... \
                -helpstr "Change text font" \
                -command {puts FONT}
        }
    }

} frame .fr -width 300 -height 300 entry .ef -textvariable helpVar pack
.mb -anchor nw -fill x -expand yes pack .fr -fill both -expand yes pack
.ef -anchor sw -fill x -expand yes

✨ EXAMPLE TWO: USING METHODS ✨

alternatively bestie, the same menu could be created by using the add and configure methods instead. same energy, different route 💅

package require Iwidgets 4.0
iwidgets::menubar .mb
.mb configure -menubuttons {
       menubutton file -text File -menu {
               command new -label New
               command close -label Close
               separator sep1
               command        quit -label Quit
       }
       menubutton edit -text Edit
}
.mb add command .edit.undo -label Undo -underline 0
.mb add separator .edit.sep2
.mb add command .edit.cut -label Cut -underline 1
.mb add command .edit.copy -label Copy -underline 1
.mb add command .edit.paste -label Paste -underline 0

.mb add menubutton .options -text Options -menu {
       radiobutton byName -variable viewMode \
                -value NAME -label "by Name"
       radiobutton byDate -variable viewMode \
                -value DATE -label "by Date"
}

.mb add cascade .options.prefs -label Preferences -menu {
               command colors -label Colors...
               command fonts -label Fonts...
}
pack .mb -side left -anchor nw -fill x -expand yes

🚨 CAVEATS 🚨

okay this part is important, don't skip it. The -menubuttons option as well as the -menu option is evaluated by menubar with the subst command. The positive side of this is that the option string may contain variables, commands, and/or backslash substitutions. That's the slay part.

But 😭 — substitutions might expand into more than a single word. These expansions can be protected by enclosing candidate substitutions in curly braces ({}). This ensures, for example, a value for an option will still be treated as a single value and not multiple values. Here's the case illustrated:

set fileMenuName "File Menu"
set var {}
iwidgets::menubar .mb -menubuttons {
        menubutton file -text {$fileMenuName}
        menubutton edit -text Edit -menu {
                checkbutton check \
                        -label Check \
                        -variable {[scope var]} \
                        -onvalue 1 \
                        -offvalue 0
        }
        menubutton options -text Options
}

The variable fileMenuName will expand to "File Menu" when the subst command is used on the menubutton specification. In addition, the [scope...] command will expand to @scope :: var. By enclosing these inside {} they stay as a single value.

⚠️ Note that only {} work for this. [list...], "" etc. will not protect these from the subst command. no cap, that's the whole trap.

🫶 ACKNOWLEDGMENTS 🫶

giving credit where credit is due, always:

  • Bret Schumaker
    • 1994 - Early work on a menubar widget.
  • Mark Ulferts, Mark Harrison, John Sigler
    • Invaluable feedback on grammar and usability of the menubar widget

👑 AUTHOR 👑

Bill W. Scott — the main character who wrote this whole thing. iconic.

🔑 KEYWORDS 🔑

frame, menu, menubutton, entries, help

and that's the whole page bestie 🎀 the footer down there says Tk on one side and iwidgets::menubar(1) on the other, and the date slot is honestly just empty — mysterious, we love a blank date, very demure. go forth and build the prettiest menubar the world has ever seen 💖✨🦋

📦 where this page comes from