.. 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



.. _wx.ribbon.RibbonPanel:

==========================================================================================================================================
|phoenix_title|  **wx.ribbon.RibbonPanel**
==========================================================================================================================================

Serves as a container for a group of (ribbon) controls.          

A :ref:`wx.ribbon.RibbonPage`  will typically have panels for children, with the controls for that page placed on the panels. 

A panel adds a border and label to a group of controls, and can be minimised (either automatically to conserve space, or manually by the user). 

Non ribbon controls can be placed on a panel using Sizers to manage layout. Panel size is governed by the sizer's minimum calculated size and the parent :ref:`wx.ribbon.RibbonPage`'s dimensions. For functional and aesthetic reasons it is recommended that ribbon and non ribbon controls are not mixed in one panel. 


^^  



.. _RibbonPanel-styles:

|styles| Window Styles
================================

This class supports the following styles: 

  

- ``wx.ribbon.RIBBON_PANEL_DEFAULT_STYLE``: Defined as no other flags set.  
- ``wx.ribbon.RIBBON_PANEL_NO_AUTO_MINIMISE``: Prevents the panel from automatically minimising to conserve screen space.  
- ``wx.ribbon.RIBBON_PANEL_EXT_BUTTON``: Causes an extension button to be shown in the panel's chrome (if the bar in which it is contained has ``wx.ribbon.RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS`` set). The behaviour of this button is application controlled, but typically will show an extended drop-down menu relating to the panel.  
- ``wx.ribbon.RIBBON_PANEL_MINIMISE_BUTTON``: Causes a (de)minimise button to be shown in the panel's chrome (if the bar in which it is contained has the ``wx.ribbon.RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS`` style set). This flag is typically combined with ``wx.ribbon.RIBBON_PANEL_NO_AUTO_MINIMISE`` to make a panel which the user always has manual control over when it minimises.  
- ``wx.ribbon.RIBBON_PANEL_STRETCH``: Stretches a single panel to fit the parent page.  
- ``wx.ribbon.RIBBON_PANEL_FLEXIBLE``: Allows the panel to size in both directions; currently only useful when a single :ref:`wx.ribbon.RibbonToolBar`  is the child of the panel, particularly in vertical orientation where the number of rows is dependent on the amount of horizontal space available. Set the minimum and maximum toolbar rows to take full advantage of this wrapping behaviour. ^^ 

^^






.. _RibbonPanel-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive a :ref:`wx.ribbon.RibbonPanelEvent` parameter.


- EVT_RIBBONPANEL_EXTBUTTON_ACTIVATED: Triggered when the user activate the panel extension button. ^^ 








.. seealso:: :ref:`wx.ribbon.RibbonPage`  







|

|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>RibbonPanel</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.ribbon.RibbonPanel_inheritance.png" alt="Inheritance diagram of RibbonPanel" 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.ribbon.RibbonPanel.html" title="Serves as a container for a group of (ribbon) controls." alt="" coords="23,392,187,421"/> <area shape="rect" id="node2" href="wx.ribbon.RibbonControl.html" title="wx.ribbon.RibbonControl  serves as a base class for all controls which share the ribbon characteristics of having a ribbon art provider, and (optionally) non-continuous resizing." alt="" coords="18,315,193,344"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="61,237,149,267"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="61,160,150,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,88,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> </map> 
   </p>
   </div>

|


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

================================================================================ ================================================================================
:meth:`~wx.ribbon.RibbonPanel.__init__`                                          Default constructor.
:meth:`~wx.ribbon.RibbonPanel.CanAutoMinimise`                                   Query if the panel can automatically minimise itself at small sizes.
:meth:`~wx.ribbon.RibbonPanel.Create`                                            Create a ribbon panel in two-step ribbon panel construction.
:meth:`~wx.ribbon.RibbonPanel.GetClassDefaultAttributes`                         
:meth:`~wx.ribbon.RibbonPanel.GetExpandedDummy`                                  Get the dummy panel of an expanded panel.
:meth:`~wx.ribbon.RibbonPanel.GetExpandedPanel`                                  Get the expanded panel of a dummy panel.
:meth:`~wx.ribbon.RibbonPanel.GetMinimisedIcon`                                  Get the bitmap to be used in place of the panel children when it is minimised.
:meth:`~wx.ribbon.RibbonPanel.HasExtButton`                                      Test if the panel has an extension button.
:meth:`~wx.ribbon.RibbonPanel.HideExpanded`                                      Hide the panel's external expansion.
:meth:`~wx.ribbon.RibbonPanel.IsExtButtonHovered`                                Query if the mouse is currently hovered over the extension button.
:meth:`~wx.ribbon.RibbonPanel.IsHovered`                                         Query is the mouse is currently hovered over the panel.
:meth:`~wx.ribbon.RibbonPanel.IsMinimised`                                       Query if the panel is currently minimised.
:meth:`~wx.ribbon.RibbonPanel.Realize`                                           Realize all children of the panel.
:meth:`~wx.ribbon.RibbonPanel.SetArtProvider`                                    Set the art provider to be used.
:meth:`~wx.ribbon.RibbonPanel.ShowExpanded`                                      Show the panel externally expanded.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.ribbon.RibbonPanel.ExpandedDummy`                                     See :meth:`~wx.ribbon.RibbonPanel.GetExpandedDummy`
:attr:`~wx.ribbon.RibbonPanel.ExpandedPanel`                                     See :meth:`~wx.ribbon.RibbonPanel.GetExpandedPanel`
:attr:`~wx.ribbon.RibbonPanel.MinimisedIcon`                                     See :meth:`~wx.ribbon.RibbonPanel.GetMinimisedIcon`
================================================================================ ================================================================================


|


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


.. class:: wx.ribbon.RibbonPanel(RibbonControl)

   **Possible constructors**::

       RibbonPanel()
       
       RibbonPanel(parent, id=ID_ANY, label="", minimised_icon=NullBitmap,
                   pos=DefaultPosition, size=DefaultSize, style=RIBBON_PANEL_DEFAULT_STYLE)
       
   
   Serves as a container for a group of (ribbon) controls.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      With this constructor, :meth:`Create`   should be called in order to create the ribbon panel.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, label="", minimised_icon=NullBitmap, pos=DefaultPosition, size=DefaultSize, style=RIBBON_PANEL_DEFAULT_STYLE)`
      
      Constructs a ribbon panel.                  
      
      
      
      
      :param `parent`: Pointer to a parent window, which is typically a :ref:`wx.ribbon.RibbonPage`, though it can be any window.   
      :type `parent`: wx.Window
      :param `id`: Window identifier.   
      :type `id`: wx.WindowID
      :param `label`: Label to be used in the :ref:`wx.ribbon.RibbonPanel`'s chrome.   
      :type `label`: string
      :param `minimised_icon`: Icon to be used in place of the panel's children when the panel is minimised.   
      :type `minimised_icon`: wx.Bitmap
      :param `pos`: The initial position of the panel. Not relevant when the parent is a ribbon page, as the position and size of the panel will be dictated by the page.   
      :type `pos`: wx.Point
      :param `size`: The initial size of the panel. Not relevant when the parent is a ribbon page, as the position and size of the panel will be dictated by the page.   
      :type `size`: wx.Size
      :param `style`: Style flags for the panel.   
      :type `style`: long
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: CanAutoMinimise(self)

      Query if the panel can automatically minimise itself at small sizes.                  

      :rtype: `bool`








   .. method:: Create(self, parent, id=ID_ANY, label="", icon=NullBitmap, pos=DefaultPosition, size=DefaultSize, style=RIBBON_PANEL_DEFAULT_STYLE)

      Create a ribbon panel in two-step ribbon panel construction.                  

      Should only be called when the default constructor is used, and arguments have the same meaning as in the full constructor.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `label`: 
      :type `label`: string
      :param `icon`: 
      :type `icon`: wx.Bitmap
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long




      :rtype: `bool`








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: `VisualAttributes`     








   .. method:: GetExpandedDummy(self)

      Get the dummy panel of an expanded panel.                  

      Note that this should be called on an expanded panel to get the dummy associated with it - it will return ``None`` when called on the dummy itself. 

                

      :rtype: :ref:`wx.ribbon.RibbonPanel`







      .. seealso:: :meth:`ShowExpanded`     







      .. seealso:: :meth:`GetExpandedPanel`     








   .. method:: GetExpandedPanel(self)

      Get the expanded panel of a dummy panel.                  

      Note that this should be called on a dummy panel to get the expanded panel associated with it - it will return ``None`` when called on the expanded panel itself. 

                

      :rtype: :ref:`wx.ribbon.RibbonPanel`







      .. seealso:: :meth:`ShowExpanded`     







      .. seealso:: :meth:`GetExpandedDummy`     








   .. method:: GetMinimisedIcon(self)

      Get the bitmap to be used in place of the panel children when it is minimised.                  

      :rtype: `Bitmap`     








   .. method:: HasExtButton(self)

      Test if the panel has an extension button.                  

      Such button is shown in the top right corner of the panel if  ``RIBBON_PANEL_EXT_BUTTON``   style is used for it. 

                

      :rtype: `bool`







      :returns: 

         ``True`` if the panel and its :ref:`wx.ribbon.RibbonBar`  allow it in their styles.   







      .. versionadded:: 2.9.4 
    








   .. method:: HideExpanded(self)

      Hide the panel's external expansion.                  

                

      :rtype: `bool`







      :returns: 

         ``True`` if the panel was un-expanded, ``False`` if it was not (normally due to it not being expanded in the first place).  







      .. seealso:: :meth:`HideExpanded`     







      .. seealso:: :meth:`GetExpandedPanel`     








   .. method:: IsExtButtonHovered(self)

      Query if the mouse is currently hovered over the extension button.                  

      Extension button is only shown for panels with  ``RIBBON_PANEL_EXT_BUTTON``   style. 

                

      :rtype: `bool`







      .. versionadded:: 2.9.4 
     








   .. method:: IsHovered(self)

      Query is the mouse is currently hovered over the panel.                  

                

      :rtype: `bool`







      :returns: 

         ``True`` if the cursor is within the bounds of the panel (i.e. hovered over the panel or one of its children), ``False`` otherwise.   








   .. method:: IsMinimised(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **IsMinimised** `(self)`
      
      Query if the panel is currently minimised.                  
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **IsMinimised** `(self, at_size)`
      
      Query if the panel would be minimised at a given size.                  
      
      
      :param `at_size`: 
      :type `at_size`: wx.Size
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Realize(self)

      Realize all children of the panel.                  

      :rtype: `bool`








   .. method:: SetArtProvider(self, art)

      Set the art provider to be used.                  

      Normally called automatically by :ref:`wx.ribbon.RibbonPage`  when the panel is created, or the art provider changed on the page. 

      The new art provider will be propagated to the children of the panel.                  


      :param `art`: 
      :type `art`: wx.ribbon.RibbonArtProvider







   .. method:: ShowExpanded(self)

      Show the panel externally expanded.                  

      When a panel is minimised, it can be shown full-size in a pop-out window, which is referred to as being (externally) expanded. Note that when a panel is expanded, there exist two panels - the original panel (which is referred to as the dummy panel) and the expanded panel. The original is termed a dummy as it sits in the ribbon bar doing nothing, while the expanded panel holds the panel children. 

                

      :rtype: `bool`







      :returns: 

         ``True`` if the panel was expanded, ``False`` if it was not (possibly due to it not being minimised, or already being expanded).  







      .. seealso:: :meth:`HideExpanded`     







      .. seealso:: :meth:`GetExpandedPanel`     








   .. attribute:: ExpandedDummy

      See :meth:`~wx.ribbon.RibbonPanel.GetExpandedDummy`


   .. attribute:: ExpandedPanel

      See :meth:`~wx.ribbon.RibbonPanel.GetExpandedPanel`


   .. attribute:: MinimisedIcon

      See :meth:`~wx.ribbon.RibbonPanel.GetMinimisedIcon`