.. wxPython Phoenix documentation

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

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

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.ribbon.bar

.. highlight:: python



.. _wx.lib.agw.ribbon.bar.RibbonBar:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.ribbon.bar.RibbonBar**
==========================================================================================================================================

Top-level control in a ribbon user interface. 



|

|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>RibbonBar</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.lib.agw.ribbon.bar.RibbonBar_inheritance.png" alt="Inheritance diagram of RibbonBar" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.ribbon.bar.RibbonBar.html" title="wx.lib.agw.ribbon.bar.RibbonBar" alt="" coords="31,469,261,499"/> <area shape="rect" id="node2" href="wx.lib.agw.ribbon.control.RibbonControl.html" title="wx.lib.agw.ribbon.control.RibbonControl" alt="" coords="5,392,287,421"/> <area shape="rect" id="node3" href="wx.Control.html" title="wx.Control" alt="" coords="100,315,192,344"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window" alt="" coords="97,237,195,267"/> <area shape="rect" id="node5" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="81,160,211,189"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="87,83,205,112"/> <area shape="rect" id="node7" href="wx.Object.html" title="wx.Object" alt="" coords="43,5,129,35"/> <area shape="rect" id="node8" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="154,5,261,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.ribbon.bar.ribbonbar.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.lib.agw.ribbon.bar.ribbonbar.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|




|super_classes| Known Superclasses
==================================

:class:`wx.lib.agw.ribbon.control.RibbonControl`

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.__init__`                                Default constructor.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.AddPage`                                 Adds a page to the :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.CommonInit`                              Common initialization procedures.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.DismissExpandedPanel`                    Dismiss the expanded panel of the currently active page.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.DoEraseBackground`                       Does the initial painting of stuff from the :meth:`~RibbonBar.OnPaint` event.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.DoGetBestSize`                           Gets the size which best suits the window: for a control, it would be the
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.DoMouseButtonCommon`                     Common methods for all the mouse move/click events.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.GetActivePage`                           Get the index of the active page.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.GetAGWWindowStyleFlag`                   Returns the :class:`RibbonBar` window style flag.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.GetDefaultBorder`                        Returns the default border style for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.GetPage`                                 Get a page by index.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.HasMultiplePages`                        This method should be overridden to return true if this window has multiple pages.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.HitTestTabs`                             Hit test method for :class:`RibbonBar`, testing where the given (in client coordinates)
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnEraseBackground`                       Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseDoubleClick`                      Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseLeave`                            Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseLeftDown`                         Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseLeftUp`                           Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseMiddleDown`                       Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseMiddleUp`                         Handles the ``wx.EVT_MIDDLE_UP`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseMove`                             Handles the ``wx.EVT_MOTION`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseRightDown`                        Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnMouseRightUp`                          Handles the ``wx.EVT_RIGHT_UP`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnPaint`                                 Handles the ``wx.EVT_PAINT`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OnSize`                                  Handles the ``wx.EVT_SIZE`` event for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.OrderPageTabInfoBySmallWidthAsc`         
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.Realize`                                 Perform initial layout and size calculations of the bar and its children.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.RecalculateMinSize`                      Recalculates the :class:`RibbonBar` minimum size.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.RecalculateTabSizes`                     Recalculates the :class:`RibbonBar` tab sizes.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.RefreshTabBar`                           Repaints the tab area in :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.RepositionPage`                          
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.ScrollTabBar`                            Scrolls the tab area left/right/up/down by the specified `amount`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetActivePage`                           See comments on :meth:`~RibbonBar.SetActivePageByIndex` and :meth:`~RibbonBar.SetActivePageByPage`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetActivePageByIndex`                    Set the active page by index, without triggering any events.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetActivePageByPage`                     Set the active page, without triggering any events.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetAGWWindowStyleFlag`                   Sets the window style for :class:`RibbonBar`.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetArtProvider`                          Set the art provider to be used be the ribbon bar.
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.SetTabCtrlMargins`                       Set the margin widths (in pixels) on the left and right sides of the tab bar
:meth:`~wx.lib.agw.ribbon.bar.RibbonBar.ShowPanels`                              Shows or hides the panels inside :class:`RibbonBar`.
================================================================================ ================================================================================


|


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


.. class:: RibbonBar(RibbonControl)

   Top-level control in a ribbon user interface. 

   .. method:: __init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=RIBBON_BAR_DEFAULT_STYLE, validator=wx.DefaultValidator, name="RibbonBar")

      Default constructor.
      
      :param `parent`: pointer to a parent window, must not be ``None``;
      :type `parent`: :class:`wx.Window`
      :param integer `id`: window identifier. If ``wx.ID_ANY``, will automatically create
       an identifier;
      :param `pos`: window position. ``wx.DefaultPosition`` indicates that wxPython
       should generate a default position for the window;
      :type `pos`: tuple or :class:`wx.Point`
      :param `size`: window size. ``wx.DefaultSize`` indicates that wxPython should
       generate a default size for the window. If no suitable size can be found, the
       window will be sized to 20x20 pixels so that the window is visible but obviously
       not correctly sized;
      :type `size`: tuple or :class:`wx.Size`
      :param `agwStyle`: the AGW-specific window style. This can be a combination of the
       following bits:
      
       ========================================== =========== ==========================================
       Window Styles                              Hex Value   Description
       ========================================== =========== ==========================================
       ``RIBBON_BAR_DEFAULT_STYLE``                       0x9 Defined as ``RIBBON_BAR_FLOW_HORIZONTAL`` | ``RIBBON_BAR_SHOW_PAGE_LABELS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``
       ``RIBBON_BAR_FOLDBAR_STYLE``                      0x1e Defined as ``RIBBON_BAR_FLOW_VERTICAL`` | ``RIBBON_BAR_SHOW_PAGE_ICONS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` | ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``
       ``RIBBON_BAR_SHOW_PAGE_LABELS``                    0x1 Causes labels to be shown on the tabs in the ribbon bar.
       ``RIBBON_BAR_SHOW_PAGE_ICONS``                     0x2 Causes icons to be shown on the tabs in the ribbon bar.
       ``RIBBON_BAR_FLOW_HORIZONTAL``                     0x0 Causes panels within pages to stack horizontally.
       ``RIBBON_BAR_FLOW_VERTICAL``                       0x4 Causes panels within pages to stack vertically.
       ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``              0x8 Causes extension buttons to be shown on panels (where the panel has such a button).
       ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``        0x10 Causes minimise buttons to be shown on panels (where the panel has such a button).
       ``RIBBON_BAR_ALWAYS_SHOW_TABS``                   0x20 Always shows the tabs area even when only one tab is added.
       ========================================== =========== ==========================================
      
      :param `validator`: the window validator;
      :type `validator`: :class:`wx.Validator`
      :param string `name`: the window name.


   .. method:: AddPage(self, page)

      Adds a page to the :class:`RibbonBar`.
      
      :param `page`: an instance of :class:`~wx.lib.agw.ribbon.page.RibbonPage`.


   .. method:: CommonInit(self, agwStyle)

      Common initialization procedures.
      
      :param integer `agwStyle`: the AGW-specific window style.
      
      :see: :meth:`~RibbonBar.SetAGWWindowStyleFlag` for a list of valid window styles.


   .. method:: DismissExpandedPanel(self)

      Dismiss the expanded panel of the currently active page.
      
      Calls and returns the value from :meth:`RibbonPage.DismissExpandedPanel() <lib.agw.ribbon.page.RibbonPage.DismissExpandedPanel>` for the
      currently active page, or ``False`` if there is no active page.


   .. method:: DoEraseBackground(self, dc)

      Does the initial painting of stuff from the :meth:`~RibbonBar.OnPaint` event.
      
      :param `dc`: an instance of :class:`wx.DC`.


   .. method:: DoGetBestSize(self)

      Gets the size which best suits the window: for a control, it would be the
      minimal size which doesn't truncate the control, for a panel - the same size
      as it would have after a call to `Fit()`.
      
      :return: An instance of :class:`wx.Size`.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: DoMouseButtonCommon(self, event, tab_event_type)

      Common methods for all the mouse move/click events.
      
      :param `event`: a :class:`MouseEvent` event to be processed;
      :param integer `tab_event_type`: one of the :class:`RibbonBar` events.


   .. method:: GetActivePage(self)

      Get the index of the active page.
      
      In the rare case of no page being active, -1 is returned.


   .. method:: GetAGWWindowStyleFlag(self)

      Returns the :class:`RibbonBar` window style flag.
      
      :see: :meth:`~RibbonBar.SetAGWWindowStyleFlag` for a list of valid window styles.


   .. method:: GetDefaultBorder(self)

      Returns the default border style for :class:`RibbonBar`. 


   .. method:: GetPage(self, n)

      Get a page by index.
      
      ``None`` will be returned if the given index is out of range.
      
      :param integer `n`: the zero-based index indicating the page position.


   .. method:: HasMultiplePages(self)

      This method should be overridden to return true if this window has multiple pages.
      
      All standard class with multiple pages such as :class:`Notebook`, :class:`Listbook` and :class:`Treebook`
      already override it to return true and user-defined classes with similar behaviour should also
      do so, to allow the library to handle such windows appropriately.


   .. method:: HitTestTabs(self, position)

      Hit test method for :class:`RibbonBar`, testing where the given (in client coordinates)
      point lies.
      
      :param `position`: an instance of :class:`wx.Point` in client coordinates.
      
      :return: a tuple containing the tab index and the :class:`~wx.lib.agw.ribbon.page.RibbonPage` if the :meth:`~RibbonBar.HitTestTabs`
       successfully found such combination, or a tuple `(-1, None)` if no tab has been hit.


   .. method:: OnEraseBackground(self, event)

      Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`EraseEvent` event to be processed.


   .. method:: OnMouseDoubleClick(self, event)

      Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseLeave(self, event)

      Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseLeftDown(self, event)

      Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseLeftUp(self, event)

      Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseMiddleDown(self, event)

      Handles the ``wx.EVT_MIDDLE_DOWN`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseMiddleUp(self, event)

      Handles the ``wx.EVT_MIDDLE_UP`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseMove(self, event)

      Handles the ``wx.EVT_MOTION`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseRightDown(self, event)

      Handles the ``wx.EVT_RIGHT_DOWN`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseRightUp(self, event)

      Handles the ``wx.EVT_RIGHT_UP`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnPaint(self, event)

      Handles the ``wx.EVT_PAINT`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`PaintEvent` event to be processed.


   .. method:: OnSize(self, event)

      Handles the ``wx.EVT_SIZE`` event for :class:`RibbonBar`.
      
      :param `event`: a :class:`wx.SizeEvent` event to be processed.


   .. method:: OrderPageTabInfoBySmallWidthAsc(self, first, second)


   .. method:: Realize(self)

      Perform initial layout and size calculations of the bar and its children.
      
      This must be called after all of the bar's children have been created (and their
      children created, etc.) - if it is not, then windows may not be laid out or
      sized correctly. Also calls :meth:`RibbonPage.Realize() <lib.agw.ribbon.page.RibbonPage.Realize>`
      on each child page.
      
      :note: Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.


   .. method:: RecalculateMinSize(self)

      Recalculates the :class:`RibbonBar` minimum size. 


   .. method:: RecalculateTabSizes(self)

      Recalculates the :class:`RibbonBar` tab sizes. 


   .. method:: RefreshTabBar(self)

      Repaints the tab area in :class:`RibbonBar`. 


   .. method:: RepositionPage(self, page)


   .. method:: ScrollTabBar(self, amount)

      Scrolls the tab area left/right/up/down by the specified `amount`.
      
      :param integer `amount`: the amount by which the tab area is scrolled, in pixels.


   .. method:: SetActivePage(self, page)

      See comments on :meth:`~RibbonBar.SetActivePageByIndex` and :meth:`~RibbonBar.SetActivePageByPage`. 


   .. method:: SetActivePageByIndex(self, page)

      Set the active page by index, without triggering any events.
      
      :param integer `page`: The zero-based index of the page to activate.
      
      :returns: ``True`` if the specified page is now active, ``False`` if it could
       not be activated (for example because the page index is invalid).


   .. method:: SetActivePageByPage(self, page)

      Set the active page, without triggering any events.
      
      :param `page`: the page to activate, an instance of :class:`~wx.lib.agw.ribbon.page.RibbonPage`.
      
      :returns: ``True`` if the specified page is now active, ``False`` if it could
       not be activated (for example because the given page is not a child of the
       ribbon bar).


   .. method:: SetAGWWindowStyleFlag(self, agwStyle)

      Sets the window style for :class:`RibbonBar`.
      
      :param integer `agwStyle`: can be a combination of the following bits:
      
       ========================================== =========== ==========================================
       Window Styles                              Hex Value   Description
       ========================================== =========== ==========================================
       ``RIBBON_BAR_DEFAULT_STYLE``                       0x9 Defined as ``RIBBON_BAR_FLOW_HORIZONTAL`` | ``RIBBON_BAR_SHOW_PAGE_LABELS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``
       ``RIBBON_BAR_FOLDBAR_STYLE``                      0x1e Defined as ``RIBBON_BAR_FLOW_VERTICAL`` | ``RIBBON_BAR_SHOW_PAGE_ICONS`` | ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` | ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``
       ``RIBBON_BAR_SHOW_PAGE_LABELS``                    0x1 Causes labels to be shown on the tabs in the ribbon bar.
       ``RIBBON_BAR_SHOW_PAGE_ICONS``                     0x2 Causes icons to be shown on the tabs in the ribbon bar.
       ``RIBBON_BAR_FLOW_HORIZONTAL``                     0x0 Causes panels within pages to stack horizontally.
       ``RIBBON_BAR_FLOW_VERTICAL``                       0x4 Causes panels within pages to stack vertically.
       ``RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS``              0x8 Causes extension buttons to be shown on panels (where the panel has such a button).
       ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS``        0x10 Causes minimise buttons to be shown on panels (where the panel has such a button).
       ``RIBBON_BAR_ALWAYS_SHOW_TABS``                   0x20 Always shows the tabs area even when only one tab is added.
       ========================================== =========== ==========================================
      
      :note: Please note that some styles cannot be changed after the window creation
       and that `Refresh()` might need to be be called after changing the others for
       the change to take place immediately.


   .. method:: SetArtProvider(self, art)

      Set the art provider to be used be the ribbon bar.
      
      Also sets the art provider on all current :class:`~wx.lib.agw.ribbon.page.RibbonPage` children, and any
      :class:`~wx.lib.agw.ribbon.page.RibbonPage` children added in the future.
      
      Note that unlike most other ribbon controls, the ribbon bar creates a default
      art provider when initialised, so an explicit call to :meth:`~RibbonBar.SetArtProvider` is
      not required if the default art provider is sufficient. Also unlike other
      ribbon controls, the ribbon bar takes ownership of the given pointer, and
      will delete it when the art provider is changed or the bar is destroyed.
      
      If this behaviour is not desired, then clone the art provider before setting
      it.
      
      :param `art`: an art provider.
      
      :note: Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.


   .. method:: SetTabCtrlMargins(self, left, right)

      Set the margin widths (in pixels) on the left and right sides of the tab bar
      region of the ribbon bar.
      
      These margins will be painted with the tab background, but tabs and scroll
      buttons will never be painted in the margins. The left margin could be used for
      rendering something equivalent to the "Office Button", though this is not
      currently implemented. The right margin could be used for rendering a help
      button, and/or MDI buttons, but again, this is not currently implemented.
      
      :param integer `left`: the left margin (in pixels);
      :param integer `right`: the right margin (in pixels).


   .. method:: ShowPanels(self, show=True)

      Shows or hides the panels inside :class:`RibbonBar`.
      
      :param bool `show`: ``True`` to show the panels, ``False`` to hide them.


