.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.MenuBar:

==========================================================================================================================================
|phoenix_title|  **wx.MenuBar**
==========================================================================================================================================

A menu bar is a series of menus accessible from the top of a frame.          


If you have a toolbar which uses the same identifiers as your ``EVT_MENU`` entries, events from the toolbar will also be processed by your ``EVT_MENU`` event handlers.  

Tip: under Windows, if you discover that menu shortcuts (for example, Alt-F to show the file menu) are not working, check any ``EVT_CHAR`` events you are handling in child windows. If you are not calling event.Skip() for events that you don't process in these event handlers, menu shortcuts may cease to work. 







         



.. note:: 

   To respond to a menu selection, provide a handler for ``EVT_MENU``, in the frame that contains the menu bar.  







.. seealso:: :ref:`wx.Menu`, :ref:`Events and Event Handling <events and event handling>`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>MenuBar</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.MenuBar_inheritance.png" alt="Inheritance diagram of MenuBar" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,87,35"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="48,83,159,112"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window" alt="" coords="59,160,148,189"/> <area shape="rect" id="node3" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="112,5,213,35"/> <area shape="rect" id="node5" href="wx.MenuBar.html" title="wx.MenuBar" alt="" coords="55,237,153,267"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.MenuBar.__init__`                                                     Construct an empty menu bar.
:meth:`~wx.MenuBar.Append`                                                       Adds the item to the end of the menu bar.
:meth:`~wx.MenuBar.Attach`                                                       
:meth:`~wx.MenuBar.Check`                                                        Checks or unchecks a menu item.
:meth:`~wx.MenuBar.Detach`                                                       
:meth:`~wx.MenuBar.Enable`                                                       Enables or disables (greys out) a menu item.
:meth:`~wx.MenuBar.EnableTop`                                                    Enables or disables a whole menu.
:meth:`~wx.MenuBar.FindItem`                                                     Finds the menu item object associated with the given menu item identifier.
:meth:`~wx.MenuBar.FindItemById`                                                 FindItemById(id) . MenuItem
:meth:`~wx.MenuBar.FindMenu`                                                     Returns the index of the menu with the given `title`  or  ``NOT_FOUND``   if no such menu exists in this menubar.
:meth:`~wx.MenuBar.FindMenuItem`                                                 Finds the menu item id for a menu name/menu item string pair.
:meth:`~wx.MenuBar.GetFrame`                                                     
:meth:`~wx.MenuBar.GetHelpString`                                                Gets the help string associated with the menu item identifier.
:meth:`~wx.MenuBar.GetLabel`                                                     Gets the label associated with a menu item.
:meth:`~wx.MenuBar.GetLabelTop`                                                  Returns the label of a top-level menu.
:meth:`~wx.MenuBar.GetMenu`                                                      Returns the menu at `menuIndex`  (zero-based).
:meth:`~wx.MenuBar.GetMenuCount`                                                 Returns the number of menus in this menubar.
:meth:`~wx.MenuBar.GetMenuLabel`                                                 Returns the label of a top-level menu.
:meth:`~wx.MenuBar.GetMenuLabelText`                                             Returns the label of a top-level menu.
:meth:`~wx.MenuBar.GetMenus`                                                     GetMenus() . (menu, label)
:meth:`~wx.MenuBar.Insert`                                                       Inserts the menu at the given position into the menu bar.
:meth:`~wx.MenuBar.IsAttached`                                                   
:meth:`~wx.MenuBar.IsChecked`                                                    Determines whether an item is checked.
:meth:`~wx.MenuBar.IsEnabled`                                                    Determines whether an item is enabled.
:meth:`~wx.MenuBar.IsEnabledTop`                                                 Returns ``True`` if the menu with the given index is enabled.
:meth:`~wx.MenuBar.MacGetCommonMenuBar`                                          Enables you to get the global menubar on Mac, that is, the menubar displayed when the app is running without any frames open.
:meth:`~wx.MenuBar.MacSetCommonMenuBar`                                          Enables you to set the global menubar on Mac, that is, the menubar displayed when the app is running without any frames open.
:meth:`~wx.MenuBar.OSXGetAppleMenu`                                              Returns the Apple menu.
:meth:`~wx.MenuBar.Refresh`                                                      Redraw the menu bar.
:meth:`~wx.MenuBar.Remove`                                                       Removes the menu from the menu bar and returns the menu object - the caller is responsible for deleting it.
:meth:`~wx.MenuBar.Replace`                                                      Replaces the menu at the given position with another one.
:meth:`~wx.MenuBar.SetHelpString`                                                Sets the help string associated with a menu item.
:meth:`~wx.MenuBar.SetLabel`                                                     Sets the label of a menu item.
:meth:`~wx.MenuBar.SetLabelTop`                                                  Sets the label of a top-level menu.
:meth:`~wx.MenuBar.SetMenuLabel`                                                 Sets the label of a top-level menu.
:meth:`~wx.MenuBar.SetMenus`                                                     SetMenus()
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.MenuBar.Menus`                                                        See :meth:`~wx.MenuBar.GetMenus` and :meth:`~wx.MenuBar.SetMenus`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.MenuBar(Window)

   **Possible constructors**::

       MenuBar(style=0)
       
   
   A menu bar is a series of menus accessible from the top of a frame.



   .. method:: __init__(self, style=0)

      Construct an empty menu bar.                  




      :param `style`: If ``wx.MB_DOCKABLE`` the menu bar can be detached (wxGTK only).   
      :type `style`: long




                  





   .. method:: Append(self, menu, title)

      Adds the item to the end of the menu bar.                  




      :param `menu`: The menu to add. Do not deallocate this menu after calling :meth:`Append` .   
      :type `menu`: wx.Menu
      :param `title`: The title of the menu, must be non-empty.  
      :type `title`: string








      :rtype: `bool`



                  



      :returns: 

         ``True`` on success, ``False`` if an error occurred.  







      .. seealso:: :meth:`Insert`     








   .. method:: Attach(self, frame)




      :param `frame`: 
      :type `frame`: wx.Frame







   .. method:: Check(self, id, check)

      Checks or unchecks a menu item.                  




      :param `id`: The menu item identifier.   
      :type `id`: int
      :param `check`: If ``True``, checks the menu item, otherwise the item is unchecked.  
      :type `check`: bool






                  



      .. note:: 

         Only use this when the menu bar has been associated with a frame; otherwise, use the :ref:`wx.Menu`  equivalent call.   








   .. method:: Detach(self)






   .. method:: Enable(self, id, enable)

      Enables or disables (greys out) a menu item.                  




      :param `id`: The menu item identifier.   
      :type `id`: int
      :param `enable`: ``True`` to enable the item, ``False`` to disable it.  
      :type `enable`: bool






                  



      .. note:: 

         Only use this when the menu bar has been associated with a frame; otherwise, use the :ref:`wx.Menu`  equivalent call.   








   .. method:: EnableTop(self, pos, enable)

      Enables or disables a whole menu.                  




      :param `pos`: The position of the menu, starting from zero.   
      :type `pos`: int
      :param `enable`: ``True`` to enable the menu, ``False`` to disable it.  
      :type `enable`: bool






                  



      .. note:: 

         Only use this when the menu bar has been associated with a frame.   








   .. method:: FindItem(self, id)

      Finds the menu item object associated with the given menu item identifier.                  




      :param `id`: Menu item identifier.   
      :type `id`: int








      :rtype: `tuple`



      




   .. method:: FindItemById(self, id)

                              FindItemById(id) . MenuItem

                              Finds the menu item object associated with the given menu item identifier. 

      :rtype: :ref:`wx.MenuItem`








   .. method:: FindMenu(self, title)

      Returns the index of the menu with the given `title`  or  ``NOT_FOUND``   if no such menu exists in this menubar.                   

      The `title`  parameter may specify either the menu title (with accelerator characters, i.e.  ``"&File"`` ) or just the menu label ( ``"File"`` ) indifferently.                   


      :param `title`: 
      :type `title`: string




      :rtype: `int`








   .. method:: FindMenuItem(self, menuString, itemString)

      Finds the menu item id for a menu name/menu item string pair.                  




      :param `menuString`: Menu title to find.   
      :type `menuString`: string
      :param `itemString`: Item to find.  
      :type `itemString`: string








      :rtype: `int`



                  



      :returns: 

         The menu item identifier, or ``wx.NOT_FOUND`` if none was found.  







      .. note:: 

         Any special menu codes are stripped out of source and target strings before matching.   








   .. method:: GetFrame(self)



      :rtype: :ref:`wx.Frame`








   .. method:: GetHelpString(self, id)

      Gets the help string associated with the menu item identifier.                  




      :param `id`: The menu item identifier.  
      :type `id`: int






      :rtype: `string`



                  



      :returns: 

         The help string, or the empty string if there was no help string or the menu item was not found.  







      .. seealso:: :meth:`SetHelpString`     








   .. method:: GetLabel(self, id)

      Gets the label associated with a menu item.                  




      :param `id`: The menu item identifier.  
      :type `id`: int






      :rtype: `string`



                  



      :returns: 

         The menu item label, or the empty string if the item was not found.  







      .. note:: 

         Use only after the menubar has been associated with a frame.   








   .. method:: GetLabelTop(self, pos)

      Returns the label of a top-level menu.                  

      Note that the returned string does not include the accelerator characters which could have been specified in the menu title string during its construction. 




      :param `pos`: Position of the menu on the menu bar, starting from zero.  
      :type `pos`: int






      :rtype: `string`





                 



      :returns: 

         The menu label, or the empty string if the menu was not found.  







      .. wxdeprecated:: 
         This function is deprecated in favour of :meth:`GetMenuLabel`   and :meth:`GetMenuLabelText` .   







      .. note:: 

         Use only after the menubar has been associated with a frame.  







      .. seealso:: :meth:`SetLabelTop`     








   .. method:: GetMenu(self, menuIndex)

      Returns the menu at `menuIndex`  (zero-based).                  


      :param `menuIndex`: 
      :type `menuIndex`: int




      :rtype: :ref:`wx.Menu`








   .. method:: GetMenuCount(self)

      Returns the number of menus in this menubar.                  

      :rtype: `int`








   .. method:: GetMenuLabel(self, pos)

      Returns the label of a top-level menu.                  

      Note that the returned string includes the accelerator characters that have been specified in the menu title string during its construction. 




      :param `pos`: Position of the menu on the menu bar, starting from zero.  
      :type `pos`: int






      :rtype: `string`



                  



      :returns: 

         The menu label, or the empty string if the menu was not found.  







      .. note:: 

         Use only after the menubar has been associated with a frame.  







      .. seealso:: :meth:`GetMenuLabelText` , :meth:`SetMenuLabel`     








   .. method:: GetMenuLabelText(self, pos)

      Returns the label of a top-level menu.                  

      Note that the returned string does not include any accelerator characters that may have been specified in the menu title string during its construction. 




      :param `pos`: Position of the menu on the menu bar, starting from zero.  
      :type `pos`: int






      :rtype: `string`



                  



      :returns: 

         The menu label, or the empty string if the menu was not found.  







      .. note:: 

         Use only after the menubar has been associated with a frame.  







      .. seealso:: :meth:`GetMenuLabel` , :meth:`SetMenuLabel`     








   .. method:: GetMenus(self)

      
      Return a list of (menu, label) items for the menus in the :class:`MenuBar`.



   .. method:: Insert(self, pos, menu, title)

      Inserts the menu at the given position into the menu bar.                  

      Inserting menu at position 0 will insert it in the very beginning of it, inserting at position :meth:`GetMenuCount`   is the same as calling :meth:`Append` . 




      :param `pos`: The position of the new menu in the menu bar   
      :type `pos`: int
      :param `menu`: The menu to add. :ref:`wx.MenuBar`  owns the menu and will free it.   
      :type `menu`: wx.Menu
      :param `title`: The title of the menu.  
      :type `title`: string










      :rtype: `bool`



                  



      :returns: 

         ``True`` on success, ``False`` if an error occurred.  







      .. seealso:: :meth:`Append`     








   .. method:: IsAttached(self)



      :rtype: `bool`








   .. method:: IsChecked(self, id)

      Determines whether an item is checked.                  




      :param `id`: The menu item identifier.  
      :type `id`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the item was found and is checked, ``False`` otherwise.   








   .. method:: IsEnabled(self, id)

      Determines whether an item is enabled.                  




      :param `id`: The menu item identifier.  
      :type `id`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the item was found and is enabled, ``False`` otherwise.   








   .. method:: IsEnabledTop(self, pos)

      Returns ``True`` if the menu with the given index is enabled.                  




      :param `pos`: The menu position (0-based)  
      :type `pos`: int






      :rtype: `bool`



                  



      .. versionadded:: 2.9.4 
     








   .. staticmethod:: MacGetCommonMenuBar()

      Enables you to get the global menubar on Mac, that is, the menubar displayed when the app is running without any frames open.                  




      :rtype: :ref:`wx.MenuBar`







      :returns: 

         The global menubar.  







      .. note:: 

         Only exists on Mac, other platforms do not have this method.  







      .. availability:: Only available for OSX.  








   .. staticmethod:: MacSetCommonMenuBar(menubar)

      Enables you to set the global menubar on Mac, that is, the menubar displayed when the app is running without any frames open.                  




      :param `menubar`: The menubar to set.  
      :type `menubar`: wx.MenuBar









      .. note:: 

         Only exists on Mac, other platforms do not have this method.  







      .. availability:: Only available for OSX.  








   .. method:: OSXGetAppleMenu(self)

      Returns the Apple menu.                  

      This is the leftmost menu with application's name as its title. You shouldn't remove any items from it, but it is safe to insert extra menu items or submenus into it. 



      :rtype: :ref:`wx.Menu`







      .. versionadded:: 3.0.1 
     







      .. availability:: Only available for OSX.  








   .. method:: Refresh(self, eraseBackground=True, rect=None)

      Redraw the menu bar.                  


      :param `eraseBackground`: 
      :type `eraseBackground`: bool
      :param `rect`: 
      :type `rect`: wx.Rect







   .. method:: Remove(self, pos)

      Removes the menu from the menu bar and returns the menu object - the caller is responsible for deleting it.                  

      This function may be used together with :meth:`Insert`   to change the menubar dynamically. 

                


      :param `pos`: 
      :type `pos`: int




      :rtype: :ref:`wx.Menu`







      .. seealso:: :meth:`Replace`     








   .. method:: Replace(self, pos, menu, title)

      Replaces the menu at the given position with another one.                  




      :param `pos`: The position of the new menu in the menu bar   
      :type `pos`: int
      :param `menu`: The menu to add.   
      :type `menu`: wx.Menu
      :param `title`: The title of the menu.  
      :type `title`: string










      :rtype: :ref:`wx.Menu`



                  



      :returns: 

         The menu which was previously at position pos. The caller is responsible for deleting it.  







      .. seealso:: :meth:`Insert` , :meth:`Remove`     








   .. method:: SetHelpString(self, id, helpString)

      Sets the help string associated with a menu item.                  




      :param `id`: Menu item identifier.   
      :type `id`: int
      :param `helpString`: Help string to associate with the menu item.  
      :type `helpString`: string






                  



      .. seealso:: :meth:`GetHelpString`     








   .. method:: SetLabel(self, id, label)

      Sets the label of a menu item.                  




      :param `id`: Menu item identifier.   
      :type `id`: int
      :param `label`: Menu item label.  
      :type `label`: string






                  



      .. note:: 

         Use only after the menubar has been associated with a frame.  







      .. seealso:: :meth:`GetLabel`     








   .. method:: SetLabelTop(self, pos, label)

      Sets the label of a top-level menu.                  




      :param `pos`: The position of a menu on the menu bar, starting from zero.   
      :type `pos`: int
      :param `label`: The menu label.  
      :type `label`: string








                 



      .. wxdeprecated:: 
         This function has been deprecated in favour of :meth:`SetMenuLabel` .   







      .. note:: 

         Use only after the menubar has been associated with a frame.  







      .. seealso:: :meth:`GetLabelTop`     








   .. method:: SetMenuLabel(self, pos, label)

      Sets the label of a top-level menu.                  




      :param `pos`: The position of a menu on the menu bar, starting from zero.   
      :type `pos`: int
      :param `label`: The menu label.  
      :type `label`: string






                  



      .. note:: 

         Use only after the menubar has been associated with a frame.   








   .. method:: SetMenus(self, items)

      SetMenus()
      
      Clear and add new menus to the :class:`MenuBar` from a list of (menu, label) items.



   .. attribute:: Menus

      See :meth:`~wx.MenuBar.GetMenus` and :meth:`~wx.MenuBar.SetMenus`