Pmw/Pmw_1_2/doc/MainMenuBar.html

   1
   2     <html>
   3     <head>
   4     <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python">
   5     <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter">
   6     <title>Pmw.MainMenuBar reference manual</title>
   7     </head>
   8
   9     <body bgcolor="#ffffff" text="#000000" link="#0000ee"
  10         vlink="551a8b" alink="ff0000">
  11
  12     <h1 ALIGN="CENTER">Pmw.MainMenuBar</h1>
  13
  14 <center><IMG SRC=MainMenuBar.gif ALT="" WIDTH=474 HEIGHT=29></center>
  15 <dl>
  16 <dt> <h3>Name</h3></dt><dd>
  17 <p>Pmw.MainMenuBar() -
  18     manager for toplevel native menus
  19 </p>
  20
  21
  22 </dd>
  23 <dt> <h3>Inherits</h3></dt><dd>
  24 <a href="MegaArchetype.html">Pmw.MegaArchetype</a><br>
  25 </dd>
  26 <dt> <h3>Description</h3></dt><dd>
  27 <p>
  28     This class is a wrapper for the Tkinter.Menu class.  It should be
  29     used as the main menu of toplevel windows. The class is similar
  30     to <a href="MenuBar.html">Pmw.MenuBar</a>, but should be used when native menus are required.
  31     See the Tkinter.Menu documentation for full details.</p>
  32
  33 <p>    This class should be created as the child of a Tkinter.Toplevel
  34     and should then be specified as the menu associated with the
  35     toplevel, using the toplevel's <code>configure()</code> method.  For example:</p>
  36 <dl><dd><pre> # Create a Pmw.MegaToplevel.
  37  megaToplevel = Pmw.MegaToplevel()
  38  # Get the Tkinter.Toplevel from Pmw.MegaToplevel.
  39  toplevel = megaToplevel.interior()
  40  # Create the menu bar for the toplevel.
  41  menuBar = Pmw.MainMenuBar(toplevel)
  42  # Configure the toplevel to use the menuBar.
  43  toplevel.configure(menu = menuBar)</pre></dd></dl>
  44
  45
  46 <p>    There are methods to add menus, both as toplevel menus and
  47     sub-menus, and for adding menu items to the menus.  Each menu item
  48     may have help text to be displayed by a <a href="Balloon.html">Pmw.Balloon</a>.  Each menu and
  49     cascaded menu (sub-menu) is referenced by name which is supplied
  50     on creation.</p>
  51
  52 <p>    This megawidget is derived from <a href="MegaArchetype.html">Pmw.MegaArchetype</a> (not <a href="MegaWidget.html">Pmw.MegaWidget</a>
  53     like most other megawidgets), with the hull class being
  54     Tkinter.Menu.</p>
  55
  56 <p>    (Note that due to bugs in Tk's menubar functionality, balloon help
  57     has not been implemented and status help does not work properly.)</p>
  58
  59 <p></p>
  60
  61
  62 </dd>
  63 <dt> <h3>Options</h3></dt><dd>
  64 Options for this megawidget and its base
  65 classes are described below.<p></p>
  66 <a name=option.balloon></a>
  67 <dl><dt> <strong>balloon
  68 </strong></dt><dd>
  69 Specifies a <a href="Balloon.html">Pmw.Balloon</a> to display the help text for menu items.  If
  70     <strong>None</strong>, no help is displayed.  If the balloon has an associated
  71     <a href="MessageBar.html">Pmw.MessageBar</a>, the help text will also be displayed there.</p>
  72 <p>    Due to a bug in some versions of Tk (8.0 and possible others),
  73     help text will not be displayed by the balloon.  However, help
  74     text will be displayed in the balloon's associated messagebar. The default is <strong>None</strong>.</p>
  75
  76
  77
  78 </dd></dl>
  79 <a name=option.hotkeys></a>
  80 <dl><dt> <strong>hotkeys
  81 </strong></dt><dd>
  82 Initialisation option. If true, keyboard accelerators will be assigned to each menu item.
  83     Keyboard accelerators can be used to access the menus without
  84     using the mouse.  The accelerator character is always one of the
  85     alphanumeric characters in the text label of the menu item and is
  86     indicated by an underline.</p>
  87 <p>    To select a menu, simultaneously press the <strong>&lt;Alt&gt;</strong> key and the
  88     accelerator character indicated on a toplevel menu item.  The
  89     arrows keys can then be used to select other menus and menu items.
  90     To invoke a menu item, press <strong>&lt;Return&gt;</strong> or press the accelerator
  91     character indicated on the menu item.</p>
  92
  93 <p>    Each accelerator character will be assigned automatically unless
  94     <em>traverseSpec</em> is supplied to the <code>addmenu()</code>, <code>addmenuitem()</code> or
  95     <code>addcascademenu()</code> methods.  The automatically selected
  96     accelerator character for a menu item is the first character in
  97     the label text that has not already been used as an accelerator in
  98     the menu containing the menu item.</p>
  99
 100 <p>    If <em>traverseSpec</em> is given, it must be either an integer or a
 101     character.  If an integer, it specifies the index of the character
 102     in the label text to use as the accelerator character.  If a
 103     character, it specifies the character to use as the accelerator
 104     character. The default is <strong>1</strong>.</p>
 105
 106
 107
 108 </dd></dl>
 109 </dd>
 110 <dt> <h3>Components</h3></dt><dd>
 111 Components created by this megawidget and its base
 112 classes are described below.<p></p>
 113 <a name=component.hull></a>
 114 <dl><dt> <strong>hull
 115 </strong></dt><dd>
 116 The toplevel menu widget. By default, this component is a Tkinter.Menu.</p>
 117
 118
 119 </dd></dl>
 120 </dd>
 121 <dt> <h3>Dynamic components</h3></dt><dd>
 122 <p>
 123         Menu components are created dynamically by the <code>addmenu()</code> and
 124         <code>addcascademenu()</code> methods.  By default, these are of type
 125         Tkinter.Menu and are created with a component group of <strong>Menu</strong>.</p>
 126 <p>        </p>
 127
 128
 129
 130 </dd>
 131 <a name=methods></a>
 132 <dt> <h3>Methods</h3></dt><dd>
 133 Only methods specific to this megawidget are described below.
 134 For a description of its inherited methods, see the
 135 manual for its base class
 136 <strong><a href="MegaArchetype.html#methods">Pmw.MegaArchetype</a></strong>.
 137 In addition, methods from the
 138 <strong>Tkinter.Menu</strong> class
 139 are forwarded by this megawidget to the
 140 <strong>hull</strong> component.
 141 <p></p>
 142 <a name=method.addcascademenu></a>
 143 <dl><dt> <strong>addcascademenu</strong>(<em>parentMenuName</em>, <em>menuName</em>, <em>statusHelp</em> = <strong>''</strong>, <em>traverseSpec</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd>
 144 Add a cascade menu (sub-menu) to the menu <em>parentMenuName</em>.  The
 145     <em>menuName</em> argument must not be the same as any menu already
 146     created using the <code>addmenu()</code> or <code>addcascademenu()</code> methods.</p>
 147 <p>    A menu item in the parent menu is created (with the
 148     <code>add_cascade()</code> method of the parent menu) using all keyword
 149     arguments except <strong>tearoff</strong> and <strong>name</strong>.</p>
 150
 151 <p>    If the <strong>label</strong> keyword argument is not given, the <strong>label</strong> option
 152     of the menu item defaults to <em>menuName</em>.  If the <strong>underline</strong>
 153     keyword argument is not given (and the <strong>hotkeys</strong> megawidget option
 154     is true) the <strong>underline</strong> option is determined as described under
 155     <strong>hotkeys</strong> and is used to specify the keyboard accelerator.</p>
 156
 157 <p>    The <em>statusHelp</em> argument is used as the help string for the menu
 158     item.  This is displayed using the <code>showstatus()</code> method of the
 159     balloon.</p>
 160
 161 <p>    The <strong>tearoff</strong> and <strong>name</strong> keyword arguments, if present, are passed
 162     to the constructor of the menu.  See Tkinter.Menu for details of
 163     these options.  The menu is created as a component named
 164     <em>menuName</em>.</p>
 165
 166
 167
 168 </dd></dl>
 169 <a name=method.addmenu></a>
 170 <dl><dt> <strong>addmenu</strong>(<em>menuName</em>, <em>balloonHelp</em>, <em>statusHelp</em> = <strong>None</strong>, <em>traverseSpec</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd>
 171 Add a cascade menu to the toplevel menu.  The <em>menuName</em> argument
 172     must not be the same as any menu already created using the
 173     <code>addmenu()</code> or <code>addcascademenu()</code> methods.</p>
 174 <p>    A menu item in the toplevel menu is created (with the
 175     <code>add_cascade()</code> method) using all keyword arguments except
 176     <strong>tearoff</strong> and <strong>name</strong>.</p>
 177
 178 <p>    If the <strong>label</strong> keyword argument is not given, the <strong>label</strong> option
 179     of the menu button defaults to <em>menuName</em>.  If the <strong>underline</strong>
 180     keyword argument is not given (and the <strong>hotkeys</strong> megawidget option
 181     is true) the <strong>underline</strong> option is determined as described under
 182     <strong>hotkeys</strong> and is used to specify the keyboard accelerator.</p>
 183
 184 <p>    The <em>statusHelp</em> argument is used as the help string for the menu
 185     item.  This is displayed using the <code>showstatus()</code> method of the
 186     balloon.  Currently <em>balloonHelp</em> is not used, due to a bug in Tk
 187     version 8.0.</p>
 188
 189 <p>    The <strong>tearoff</strong> and <strong>name</strong> keyword arguments, if present, are passed
 190     to the constructor of the menu.  See Tkinter.Menu for details of
 191     these options.  The menu is created as a component named
 192     <em>menuName</em>.</p>
 193
 194
 195
 196 </dd></dl>
 197 <a name=method.addmenuitem></a>
 198 <dl><dt> <strong>addmenuitem</strong>(<em>menuName</em>, <em>itemType</em>, <em>statusHelp</em> = <strong>''</strong>, <em>traverseSpec</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd>
 199 Add a menu item to the menu <em>menuName</em>.  The kind of menu item is
 200     given by <em>itemType</em> and may be one of <strong>command</strong>, <strong>separator</strong>,
 201     <strong>checkbutton</strong>, <strong>radiobutton</strong> or <strong>cascade</strong> (although cascade menus
 202     are better added using the <code>addcascademenu()</code> method).  Any
 203     keyword arguments present will be passed to the menu when creating
 204     the menu item.  See Tkinter.Menu for the valid options for each
 205     item type.  In addition, a keyboard accelerator may be
 206     automatically given to the item, as described under <strong>hotkeys</strong>. </p>
 207 <p>    When the mouse is moved over the menu item, the <em>helpString</em> will
 208     be displayed by the <strong>balloon</strong>'s <strong>statuscommand</strong>.</p>
 209
 210
 211
 212 </dd></dl>
 213 <a name=method.deletemenu></a>
 214 <dl><dt> <strong>deletemenu</strong>(<em>menuName</em>)</dt><dd>
 215 Delete the menu <em>menuName</em> and all its items.  The menu may either
 216     be a toplevel menu or a cascade menu.</p>
 217
 218
 219 </dd></dl>
 220 <a name=method.deletemenuitems></a>
 221 <dl><dt> <strong>deletemenuitems</strong>(<em>menuName</em>, <em>start</em>, <em>end</em> = <strong>None</strong>)</dt><dd>
 222 Delete menu items from the menu <em>menuName</em>.  If <em>end</em> is not
 223     given, the <em>start</em> item is deleted.  Otherwise all items from
 224     <em>start</em> to <em>end</em> are deleted.</p>
 225
 226
 227 </dd></dl>
 228 <a name=method.disableall></a>
 229 <dl><dt> <strong>disableall</strong>()</dt><dd>
 230 Disable all toplevel menus.</p>
 231
 232
 233 </dd></dl>
 234 <a name=method.enableall></a>
 235 <dl><dt> <strong>enableall</strong>()</dt><dd>
 236 Enable all toplevel menus.</p>
 237
 238
 239 </dd></dl>
 240 </dd>
 241 <dt> <h3>Example</h3></dt><dd>
 242 The image at the top of this manual is a snapshot
 243 of the window (or part of the window) produced
 244 by the following code.<p></p>
 245 <pre>
 246 class Demo:
 247     def __init__(self, parent):
 248         # Create button to launch the toplevel with main menubar.
 249         w = Tkinter.Button(parent, text = 'Show Pmw.MainMenuBar demo',
 250                 command = lambda parent=parent: MainMenuBarToplevel(parent))
 251         w.pack(padx = 8, pady = 8)
 252
 253 class MainMenuBarToplevel:
 254     def __init__(self, parent):
 255         # Create the toplevel to contain the main menubar.
 256         megaToplevel = Pmw.MegaToplevel(parent, title = title)
 257         toplevel = megaToplevel.interior()
 258
 259         # Create the Balloon for this toplevel.
 260         self.balloon = Pmw.Balloon(toplevel)
 261
 262         # Create and install the MenuBar.
 263         menuBar = Pmw.MainMenuBar(toplevel,
 264                 balloon = self.balloon)
 265         toplevel.configure(menu = menuBar)
 266         self.menuBar = menuBar
 267
 268         # Add some buttons to the MainMenuBar.
 269         menuBar.addmenu('File', 'Close this window or exit')
 270         menuBar.addmenuitem('File', 'command', 'Close this window',
 271                 command = PrintOne('Action: close'),
 272                 label = 'Close')
 273         menuBar.addmenuitem('File', 'separator')
 274         menuBar.addmenuitem('File', 'command', 'Exit the application',
 275                 command = PrintOne('Action: exit'),
 276                 label = 'Exit')
 277
 278         menuBar.addmenu('Edit', 'Cut, copy or paste')
 279         menuBar.addmenuitem('Edit', 'command', 'Delete the current selection',
 280                 command = PrintOne('Action: delete'),
 281                 label = 'Delete')
 282
 283         menuBar.addmenu('Options', 'Set user preferences')
 284         menuBar.addmenuitem('Options', 'command', 'Set general preferences',
 285                 command = PrintOne('Action: general options'),
 286                 label = 'General...')
 287
 288         # Create a checkbutton menu item.
 289         self.toggleVar = Tkinter.IntVar()
 290         # Initialise the checkbutton to 1:
 291         self.toggleVar.set(1)
 292         menuBar.addmenuitem('Options', 'checkbutton', 'Toggle me on/off',
 293                 label = 'Toggle',
 294                 command = self._toggleMe,
 295                 variable = self.toggleVar)
 296         self._toggleMe()
 297
 298         menuBar.addcascademenu('Options', 'Size',
 299                 'Set some other preferences', traverseSpec = 'z', tearoff = 1)
 300         for size in ('tiny', 'small', 'average', 'big', 'huge'):
 301             menuBar.addmenuitem('Size', 'command', 'Set size to ' + size,
 302                     command = PrintOne('Action: size ' + size),
 303                     label = size)
 304
 305         menuBar.addmenu('Help', 'User manuals', name = 'help')
 306         menuBar.addmenuitem('Help', 'command', 'About this application',
 307                 command = PrintOne('Action: about'),
 308                 label = 'About...')
 309
 310         # Create and pack the main part of the window.
 311         self.mainPart = Tkinter.Label(toplevel,
 312                 text = 'This is the\nmain part of\nthe window',
 313                 background = 'black',
 314                 foreground = 'white',
 315                 padx = 30,
 316                 pady = 30)
 317         self.mainPart.pack(fill = 'both', expand = 1)
 318
 319         # Create and pack the MessageBar.
 320         self.messageBar = Pmw.MessageBar(toplevel,
 321                 entry_width = 40,
 322                 entry_relief='groove',
 323                 labelpos = 'w',
 324                 label_text = 'Status:')
 325         self.messageBar.pack(fill = 'x', padx = 10, pady = 10)
 326         self.messageBar.message('state',
 327             'Balloon/status help not working properly - Tk menubar bug')
 328
 329         buttonBox = Pmw.ButtonBox(toplevel)
 330         buttonBox.pack(fill = 'x')
 331         buttonBox.add('Disable\nall', command = menuBar.disableall)
 332         buttonBox.add('Enable\nall', command = menuBar.enableall)
 333         buttonBox.add('Create\nmenu', command = self.add)
 334         buttonBox.add('Delete\nmenu', command = self.delete)
 335         buttonBox.add('Create\nitem', command = self.additem)
 336         buttonBox.add('Delete\nitem', command = self.deleteitem)
 337
 338         # Configure the balloon to displays its status messages in the
 339         # message bar.
 340         self.balloon.configure(statuscommand = self.messageBar.helpmessage)
 341
 342         self.testMenuList = []
 343
 344     def _toggleMe(self):
 345         print 'Toggle value:', self.toggleVar.get()
 346
 347     def add(self):
 348         if len(self.testMenuList) == 0:
 349             num = 0
 350         else:
 351             num = self.testMenuList[-1]
 352         num = num + 1
 353         name = 'Menu%d' % num
 354         self.testMenuList.append(num)
 355
 356         self.menuBar.addmenu(name, 'This is ' + name)
 357
 358     def delete(self):
 359         if len(self.testMenuList) == 0:
 360             self.menuBar.bell()
 361         else:
 362             num = self.testMenuList[0]
 363             name = 'Menu%d' % num
 364             del self.testMenuList[0]
 365             self.menuBar.deletemenu(name)
 366
 367     def additem(self):
 368         if len(self.testMenuList) == 0:
 369             self.menuBar.bell()
 370         else:
 371             num = self.testMenuList[-1]
 372             menuName = 'Menu%d' % num
 373             menu = self.menuBar.component(menuName)
 374             if menu.index('end') is None:
 375                 label = 'item X'
 376             else:
 377                 label = menu.entrycget('end', 'label') + 'X'
 378             self.menuBar.addmenuitem(menuName, 'command', 'Help for ' + label,
 379                     command = PrintOne('Action: ' + menuName + ': ' + label),
 380                     label = label)
 381
 382     def deleteitem(self):
 383         if len(self.testMenuList) == 0:
 384             self.menuBar.bell()
 385         else:
 386             num = self.testMenuList[-1]
 387             menuName = 'Menu%d' % num
 388             menu = self.menuBar.component(menuName)
 389             if menu.index('end') is None:
 390                 self.menuBar.bell()
 391             else:
 392                 self.menuBar.deletemenuitems(menuName, 0)
 393
 394 class PrintOne:
 395     def __init__(self, text):
 396         self.text = text
 397
 398     def __call__(self):
 399         print self.text
 400
 401 </pre>
 402 </dd>
 403 </dl>
 404
 405     <center><P ALIGN="CENTER">
 406     <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
 407     </p></center>
 408
 409
 410     <font size=-1>
 411     <center><P ALIGN="CENTER">
 412     Pmw 1.2 -
 413      5 Aug 2003
 414      - <a href="index.html">Home</a>
 415     <br>Manual page last reviewed: 22 April 2000
 416     </p></center>
 417     </font>
 418
 419     </body>
 420     </html>
 421