.. wxPython Phoenix documentation

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

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

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.ribbon.panel

.. highlight:: python



.. _wx.lib.agw.ribbon.panel.RibbonPanel:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.ribbon.panel.RibbonPanel**
==========================================================================================================================================

This is the main implementation of :class:`RibbonPanel`. 



|

|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.lib.agw.ribbon.panel.RibbonPanel_inheritance.png" alt="Inheritance diagram of RibbonPanel" 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.lib.agw.ribbon.panel.RibbonPanel.html" title="wx.lib.agw.ribbon.panel.RibbonPanel" alt="" coords="16,469,263,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,275,421"/> <area shape="rect" id="node3" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="32,5,133,35"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="84,83,195,112"/> <area shape="rect" id="node8" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="79,160,200,189"/> <area shape="rect" id="node5" href="wx.Object.html" title="wx.Object" alt="" coords="157,5,239,35"/> <area shape="rect" id="node6" href="wx.Control.html" title="wx.Control" alt="" coords="96,315,184,344"/> <area shape="rect" id="node7" href="wx.Window.html" title="wx.Window" alt="" coords="95,237,184,267"/> </map> 
   </p>

|


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

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.ribbon.panel.ribbonpanel.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/../no_appearance.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.panel.RibbonPanel.__init__`                            Default class constructor.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.AddChild`                            
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.CanAutoMinimise`                     Query if the panel can automatically minimise itself at small sizes.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.CommonInit`                          
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.DoGetBestSize`                       Gets the size which best suits the window: for a control, it would be the
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.DoGetNextLargerSize`                 Implementation of :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.DoGetNextSmallerSize`                Implementation of :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.DoSetSize`                           Sets the size of the window in pixels.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetBestSizeForParentSize`            Finds the best width and height given the parent's width and height.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetDefaultBorder`                    Returns the default border style for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetExpandedDummy`                    Get the dummy panel of an expanded panel.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetExpandedPanel`                    Get the expanded panel of a dummy panel.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetExpandedPosition`                 
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetFlags`                            Returns the AGW-specific window style for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetMinimisedIcon`                    Get the bitmap to be used in place of the panel children when it is minimised.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetMinNotMinimisedSize`              
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetMinSize`                          Returns the minimum size of the window, an indication to the sizer layout mechanism
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetPanelSizerBestSize`               
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.GetPanelSizerMinSize`                
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.HasExtButton`                        
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.HideExpanded`                        Hide the panel's external expansion.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsExtButtonHovered`                  
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsHovered`                           Query is the mouse is currently hovered over the panel.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsMinimised`                         Query if the panel would be minimised at a given size.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsMinimised1`                        Query if the panel is currently minimised.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsMinimised2`                        Query if the panel would be minimised at a given size.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.IsSizingContinuous`                  Returns ``True`` if this window can take any size (greater than its minimum size),
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.Layout`                              
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnChildKillFocus`                    Handles the ``wx.EVT_KILL_FOCUS`` event for children of :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnEraseBackground`                   Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnKillFocus`                         Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMotion`                            Handles the ``wx.EVT_MOTION`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMouseClick`                        Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMouseEnter`                        Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMouseEnterChild`                   Handles the ``wx.EVT_ENTER_WINDOW`` event for children of :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMouseLeave`                        Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnMouseLeaveChild`                   Handles the ``wx.EVT_LEAVE_WINDOW`` event for children of :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnPaint`                             Handles the ``wx.EVT_PAINT`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.OnSize`                              Handles the ``wx.EVT_SIZE`` event for :class:`RibbonPanel`.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.Realize`                             Realize all children of the panel.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.RemoveChild`                         
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.SetArtProvider`                      Set the art provider to be used.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.ShouldSendEventToDummy`              
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.ShowExpanded`                        Show the panel externally expanded.
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.TestPositionForHover`                
:meth:`~wx.lib.agw.ribbon.panel.RibbonPanel.TryAfter`                            
================================================================================ ================================================================================


|


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


.. class:: RibbonPanel(RibbonControl)

   This is the main implementation of :class:`RibbonPanel`. 

   .. method:: __init__(self, parent, id=wx.ID_ANY, label="", minimised_icon=wx.NullBitmap, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=RIBBON_PANEL_DEFAULT_STYLE, name="RibbonPanel")

      Default class constructor.
      
      :param `parent`: pointer to a parent window, typically a :class:`~wx.lib.agw.ribbon.page.RibbonPage`, though
       it can be any window;
      :param `id`: window identifier. If ``wx.ID_ANY``, will automatically create
       an identifier;
      :param `label`: label of the new button;
      :param `minimised_icon`: the bitmap to be used in place of the panel children
       when it is minimised;
      :param `pos`: window position. ``wx.DefaultPosition`` indicates that wxPython
       should generate a default position for the window;
      :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;
      :param `agwStyle`: the AGW-specific window style. This can be one of the following
       bits:
      
       ================================= =========== =================================
       Window Styles                     Hex Value   Description
       ================================= =========== =================================
       ``RIBBON_PANEL_DEFAULT_STYLE``            0x0 Defined as no other flags set.
       ``RIBBON_PANEL_NO_AUTO_MINIMISE``         0x1 Prevents the panel from automatically minimising to conserve screen space.
       ``RIBBON_PANEL_EXT_BUTTON``               0x8 Causes an extension button to be shown in the panel's chrome (if the bar in which it is contained has ``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.
       ``RIBBON_PANEL_MINIMISE_BUTTON``         0x10 Causes a (de)minimise button to be shown in the panel's chrome (if the bar in which it is contained has the ``RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS`` style set). This flag is typically combined with ``RIBBON_PANEL_NO_AUTO_MINIMISE`` to make a panel which the user always has manual control over when it minimises.
       ``RIBBON_PANEL_STRETCH``                 0x20 Allows a single panel to stretch to fill the parent page.
       ``RIBBON_PANEL_FLEXIBLE``                0x40 Allows toolbars to wrap, taking up the optimum amount of space when used in a vertical palette.
       ================================= =========== =================================
      
      :param `name`: the window name.


   .. method:: AddChild(self, child)


   .. method:: CanAutoMinimise(self)

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


   .. method:: CommonInit(self, label, icon, agwStyle)


   .. 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:: DoGetNextLargerSize(self, direction, relative_to)

      Implementation of :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.
      
      Controls which have non-continuous sizing must override this virtual function
      rather than :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.


   .. method:: DoGetNextSmallerSize(self, direction, relative_to)

      Implementation of :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.
      
      Controls which have non-continuous sizing must override this virtual function
      rather than :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.


   .. method:: DoSetSize(self, x, y, width, height, sizeFlags=wx.SIZE_AUTO)

      Sets the size of the window in pixels.
      
      :param integer `x`: required `x` position in pixels, or ``wx.DefaultCoord`` to
       indicate that the existing value should be used;
      :param integer `y`: required `y` position in pixels, or ``wx.DefaultCoord`` to
       indicate that the existing value should be used;
      :param integer `width`: required width in pixels, or ``wx.DefaultCoord`` to
       indicate that the existing value should be used;
      :param integer `height`: required height in pixels, or ``wx.DefaultCoord`` to
       indicate that the existing value should be used;
      :param integer `sizeFlags`: indicates the interpretation of other parameters.
       It is a bit list of the following:
      
       * ``wx.SIZE_AUTO_WIDTH``: a ``wx.DefaultCoord`` width value is taken to indicate a
         wxPython-supplied default width.
       * ``wx.SIZE_AUTO_HEIGHT``: a ``wx.DefaultCoord`` height value is taken to indicate a
         wxPython-supplied default height.
       * ``wx.SIZE_AUTO``: ``wx.DefaultCoord`` size values are taken to indicate a wxPython-supplied
         default size.
       * ``wx.SIZE_USE_EXISTING``: existing dimensions should be used if ``wx.DefaultCoord`` values are supplied.
       * ``wx.SIZE_ALLOW_MINUS_ONE``: allow negative dimensions (i.e. value of ``wx.DefaultCoord``)
         to be interpreted as real dimensions, not default values.
       * ``wx.SIZE_FORCE``: normally, if the position and the size of the window are already
         the same as the parameters of this function, nothing is done. but with this flag a window
         resize may be forced even in this case (supported in wx 2.6.2 and later and only implemented
         for MSW and ignored elsewhere currently).


   .. method:: GetBestSizeForParentSize(self, parentSize)

      Finds the best width and height given the parent's width and height. 


   .. method:: GetDefaultBorder(self)

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


   .. method:: GetExpandedDummy(self)

      Get the dummy panel of an expanded panel.
      
      :note: 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.
      
      :see: :meth:`~RibbonPanel.ShowExpanded`, :meth:`~RibbonPanel.GetExpandedPanel`


   .. method:: GetExpandedPanel(self)

      Get the expanded panel of a dummy panel.
      
      :note: 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.
      
      :see: :meth:`~RibbonPanel.ShowExpanded`, :meth:`~RibbonPanel.GetExpandedDummy`


   .. method:: GetExpandedPosition(self, panel, expanded_size, direction)


   .. method:: GetFlags(self)

      Returns the AGW-specific window style for :class:`RibbonPanel`. 


   .. method:: GetMinimisedIcon(self)

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


   .. method:: GetMinNotMinimisedSize(self)


   .. method:: GetMinSize(self)

      Returns the minimum size of the window, an indication to the sizer layout mechanism
      that this is the minimum required size.
      
      This method normally just returns the value set by `SetMinSize`, but it can be
      overridden to do the calculation on demand.


   .. method:: GetPanelSizerBestSize(self)


   .. method:: GetPanelSizerMinSize(self)


   .. method:: HasExtButton(self)


   .. method:: HideExpanded(self)

      Hide the panel's external expansion.
      
      :returns: ``True`` if the panel was un-expanded, ``False`` if it was not
       (normally due to it not being expanded in the first place).
      
      :see: :meth:`~RibbonPanel.HideExpanded`, :meth:`~RibbonPanel.GetExpandedPanel`


   .. method:: IsExtButtonHovered(self)


   .. method:: IsHovered(self)

      Query is the mouse is currently hovered over the panel.
      
      :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, at_size=None)

      Query if the panel would be minimised at a given size.
      
      :param `at_size`: an instance of :class:`wx.Size`, giving the size at which the
       panel should be tested for minimisation.


   .. method:: IsMinimised1(self)

      Query if the panel is currently minimised. 


   .. method:: IsMinimised2(self, at_size)

      Query if the panel would be minimised at a given size.
      
      :param `at_size`: an instance of :class:`wx.Size`, giving the size at which the
       panel should be tested for minimisation.


   .. method:: IsSizingContinuous(self)

      Returns ``True`` if this window can take any size (greater than its minimum size),
      ``False`` if it can only take certain sizes.
      
      :see: :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`,
       :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`


   .. method:: Layout(self)


   .. method:: OnChildKillFocus(self, event)

      Handles the ``wx.EVT_KILL_FOCUS`` event for children of :class:`RibbonPanel`.
      
      :param `event`: a :class:`FocusEvent` event to be processed.


   .. method:: OnEraseBackground(self, event)

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


   .. method:: OnKillFocus(self, event)

      Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`RibbonPanel`.
      
      :param `event`: a :class:`FocusEvent` event to be processed.


   .. method:: OnMotion(self, event)

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


   .. method:: OnMouseClick(self, event)

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


   .. method:: OnMouseEnter(self, event)

      Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonPanel`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseEnterChild(self, event)

      Handles the ``wx.EVT_ENTER_WINDOW`` event for children of :class:`RibbonPanel`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseLeave(self, event)

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


   .. method:: OnMouseLeaveChild(self, event)

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


   .. method:: OnPaint(self, event)

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


   .. method:: OnSize(self, event)

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


   .. method:: Realize(self)

      Realize all children of the panel.
      
      :note: Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.


   .. method:: RemoveChild(self, child)


   .. method:: SetArtProvider(self, art)

      Set the art provider to be used.
      
      Normally called automatically by :class:`~wx.lib.agw.ribbon.page.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.
      
      Reimplemented from :class:`~wx.lib.agw.ribbon.control.RibbonControl`.
      
      :param `art`: an art provider.


   .. method:: ShouldSendEventToDummy(self, event)


   .. 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 refered to as being (externally) expanded.
      
      :returns: ``True`` if the panel was expanded, ``False`` if it was not (possibly
       due to it not being minimised, or already being expanded).
      
      :note: When a panel is expanded, there exist two panels - the original panel
       (which is refered 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.
      
      :see: :meth:`~RibbonPanel.HideExpanded`, :meth:`~RibbonPanel.GetExpandedPanel`


   .. method:: TestPositionForHover(self, pos)


   .. method:: TryAfter(self, event)


