'\" '\" Generated from file 'menubar\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Tom Krehbiel All rights reserved\&. '\" .TH "menubar" 3tk 0\&.5 tklib "Create and manipulate menubars" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, .\" and indent is equivalent to second arg of .IP (shouldn't ever be .\" needed; use .AS below instead) .\" .\" .AS ?type? ?name? .\" Give maximum sizes of arguments for setting tab stops. Type and .\" name are examples of largest possible arguments that will be passed .\" to .AP later. If args are omitted, default tab stops are used. .\" .\" .BS .\" Start box enclosure. From here until next .BE, everything will be .\" enclosed in one large box. .\" .\" .BE .\" End of box enclosure. .\" .\" .CS .\" Begin code excerpt. .\" .\" .CE .\" End code excerpt. .\" .\" .VS ?version? ?br? .\" Begin vertical sidebar, for use in marking newly-changed parts .\" of man pages. The first argument is ignored and used for recording .\" the version when the .VS was added, so that the sidebars can be .\" found and removed when they reach a certain age. If another argument .\" is present, then a line break is forced before starting the sidebar. .\" .\" .VE .\" End of vertical sidebar. .\" .\" .DS .\" Begin an indented unfilled display. .\" .\" .DE .\" End of indented unfilled display. .\" .\" .SO ?manpage? .\" Start of list of standard options for a Tk widget. The manpage .\" argument defines where to look up the standard options; if .\" omitted, defaults to "options". The options follow on successive .\" lines, in three columns separated by tabs. .\" .\" .SE .\" End of list of standard options for a Tk widget. .\" .\" .OP cmdName dbName dbClass .\" Start of description of a specific option. cmdName gives the .\" option's name as specified in the class command, dbName gives .\" the option's name in the option database, and dbClass gives .\" the option's class in the option database. .\" .\" .UL arg1 arg2 .\" Print arg1 underlined, then print arg2 normally. .\" .\" .QW arg1 ?arg2? .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). .\" .\" .PQ arg1 ?arg2? .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b .\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. .\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out .\" # BS - start boxed text .\" # ^y = starting y location .\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. .\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. .\" # VS - start vertical sidebar .\" # ^Y = starting y location .\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. .\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. .\" # Special macro to handle page bottom: finish off current .\" # box/sidebar if in box/sidebar mode, then invoked standard .\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. .\" # DS - begin display .de DS .RS .nf .sp .. .\" # DE - end display .de DE .fi .RE .sp .. .\" # SO - start of list of standard options .de SO 'ie '\\$1'' .ds So \\fBoptions\\fR 'el .ds So \\fB\\$1\\fR .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. .\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\*(So manual entry for details on the standard options. .. .\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. .\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. .\" # CE - end code excerpt .de CE .fi .RE .. .\" # UL - underline word .de UL \\$1\l'|0\(ul'\\$2 .. .\" # QW - apply quotation marks to word .de QW .ie '\\*(lq'"' ``\\$1''\\$2 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\$2 .. .\" # PQ - apply parens and quotation marks to word .de PQ .ie '\\*(lq'"' (``\\$1''\\$2)\\$3 .\"" fix emacs highlighting .el (\\*(lq\\$1\\*(rq\\$2)\\$3 .. .\" # QR - quoted range .de QR .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 .. .\" # MT - "empty" string .de MT .QW "" .. .BS .SH NAME menubar \- Creates an instance of the \fImenubar\fR Class\&. .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp package require \fBTk 8\&.6\fR .sp package require \fBmenubar ?0\&.5?\fR .sp \fBmenubar new\fR ?options? .sp \fImBarInst\fR \fBdefine\fR \fIbody\fR .sp \fImBarInst\fR \fBinstall\fR \fIpathName body\fR .sp \fImBarInst\fR \fBmenu\&.configure\fR \fIoption tag-settings ?option tag-settings \&.\&.\&.?\fR .sp \fImBarInst\fR \fBmenu\&.namespace\fR \fItag namespace\fR .sp \fImBarInst\fR \fBmenu\&.hide\fR \fItag\fR .sp \fImBarInst\fR \fBmenu\&.show\fR \fItag\fR .sp \fImBarInst\fR \fBtag\&.add\fR \fItag value\fR .sp \fImBarInst\fR \fBtag\&.configure\fR \fIpathName tag ?option value \&.\&.\&.option value?\fR .sp \fImBarInst\fR \fBtag\&.cget\fR \fIpathName tag ?option?\fR .sp \fImBarInst\fR \fBgroup\&.add\fR \fItag label ?cmd? ?accel? ?sequence? ?state?\fR .sp \fImBarInst\fR \fBgroup\&.delete\fR \fItag label\fR .sp \fImBarInst\fR \fBgroup\&.move\fR \fIdirection tag label\fR .sp \fImBarInst\fR \fBgroup\&.configure\fR \fItag label ?option value \&.\&.\&.option value?\fR .sp \fImBarInst\fR \fBgroup\&.serialize\fR \fItag\fR .sp \fImBarInst\fR \fBgroup\&.deserialize\fR \fItag stream\fR .sp \fImBarInst\fR \fBnotebook\&.addTabStore\fR \fIpathname\fR .sp \fImBarInst\fR \fBnotebook\&.deleteTabStore\fR \fIpathname\fR .sp \fImBarInst\fR \fBnotebook\&.setTabValue\fR \fIpathname tag\fR .sp \fImBarInst\fR \fBnotebook\&.restoreTabValues\fR \fIpathname\fR .sp .BE .SH DESCRIPTION .TP \fBmenubar new\fR ?options? .PP .PP Create and return a new instance of the menubar class\&. The menubar class encapsulates the definition, installation and dynamic behavior of a menubar\&. The class doesn't depend on a widget framework and therefore can be used with or without a framework (e\&.g\&. Bwidget, IWidget, Snit, etc\&.)\&. Unlike other Tk widget commands, the menubar command doesn't have a \fIpathName\fR argument because menubars are handled by the window manager (i\&.e\&. wm) and not the application\&. .SH OPTIONS The following options can be passed to the \fImenubar new\fR command\&. .PP These options are inherited from the Tk menu command, their effect is platform specific\&. .TP \fB\fI-activebackground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activebackground]\fR .TP \fB\fI-activeborderwidth\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activeborderwidth]\fR .TP \fB\fI-activeforeground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-activeforeground]\fR .TP \fB\fI-background\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-background]\fR .TP \fB\fI-borderwidth\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-borderwidth]\fR .TP \fB\fI-cursor\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-cursor]\fR .TP \fB\fI-disabledforeground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-disabledforeground]\fR .TP \fB\fI-font\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-font]\fR .TP \fB\fI-foreground\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-foreground]\fR .TP \fB\fI-relief\fR [http://docs\&.activestate\&.com/activetcl/8\&.5/tcl/TkCmd/options\&.htm#M-relief]\fR .PP .SH INTRODUCTION .PP An instance of the menubar class provides methods for compiling a description of the menubar, configuring menu items and installing the menubar in toplevel windows\&. .PP A menubar can be thought of as a tree of cascading menus\&. Users define a menubar using a language that results in a human readable description of a menubar\&. The description of the menubar is then compiled by an instance of the menubar class after which it can be installed in one or more toplevel windows\&. .PP The menubar class provides many unique capabilities that are not found in other tcl/tk menubar implementation\&. Some of these are: .IP \(bu A tagging system that simplifies access to menu entries in the menu tree\&. .IP \(bu Support for user defined tags that depend on the toplevel window context\&. .IP \(bu A simplified and uniform interface for all callback commands\&. .IP \(bu Namespace support for all callback commands so callback commands can be easily grouped into namespaces\&. .IP \(bu Support for hiding and exposing menus on the menubar\&. .IP \(bu A simplified method for creating radiobutton groups\&. .IP \(bu Automatic management of state variables for checkbuttons and radiobuttons\&. .IP \(bu Scope control for the state variables of checkbuttons and radiobuttons\&. .IP \(bu Tear-off menu management that ensures only one tearoff menu is created\&. .IP \(bu Support for dynamic menu extension to simplify the creation of recent document menus\&. .IP \(bu Support for saving and restoring dynamic menu extensions\&. .PP .SH TERMINOLOGY .TP MENUBAR The visible rendering of a menubar in a toplevel window is a horizontally group of cascading Tk menus\&. .TP MENU A menu is an ordered list of items that is rendered vertically\&. Menus are not visible until a user preforms some action (normally a event)\&. A menu may contain any number of child menus that are rendered as cascading menus\&. Cascading menus are rendered next to the parent menu when they are activated\&. .TP MENU ENTRY A menu contains an ordered list of items called entries\&. Menu entries have a type and the menubar class supports the following 6 entry types: \fICommand\fR, \fICheckbutton\fR, \fIRadiobutton\fR, \fISeparator\fR, \fIGroup\fR and \fIMenu\fR\&. .TP ENTRY LABEL Each menu entry has a visible string that is called the entry label\&. .TP TAG A tag is name that is normally used to referr to an item in a menu tree\&. A tag name is an alphanumeric character string that may include the underscore character\&. Menu tree tags are defined for all nodes and leafs in a menu tree\&. This provides a flat abstraction of the tree and simplifies item referencing in menubar methods\&. Without this abstraction it would be necessary to reference menu elements using a tree path which could change at run-time\&. The menubar class also has a method that can create a user defined tag\&. User defined tags store values that change based on the currently active toplevel window\&. User defined tags can be used to store widget pathnames use by callback code so that output can be routed to the appropriate toplevel window\&. .PP .SH METHODS .TP \fImBarInst\fR \fBdefine\fR \fIbody\fR Compiles \fIbody\fR into a tree of menu entries which define the visual layout of the menubar\&. The \fIbody\fR argument describes the layout using the following syntax, where the elements of the syntax are described below\&. .sp \fIbody == definitions\fR .CS definitions ::= { | | } ignore ::= { | | # } definition ::= { | | | | | } command ::=