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