.. 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.ribbon.RibbonControl:

==========================================================================================================================================
|phoenix_title|  **wx.ribbon.RibbonControl**
==========================================================================================================================================

:ref:`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.          

Despite what the name may imply, it is not the top-level control for creating a ribbon interface - that is :ref:`wx.ribbon.RibbonBar`. 

Ribbon controls often have a region which is "transparent", and shows the contents of the ribbon page or panel behind it. If implementing a new ribbon control, then it may be useful to realise that this effect is done by the art provider when painting the background of the control, and hence in the paint handler for the new control, you should call a draw background method on the art provider (:meth:`wx.ribbon.RibbonArtProvider.DrawButtonBarBackground`   and :meth:`wx.ribbon.RibbonArtProvider.DrawToolBarBackground`   typically just redraw what is behind the rectangle being painted) if you want transparent regions. 









|

|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>RibbonControl</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.RibbonControl_inheritance.png" alt="Inheritance diagram of RibbonControl" 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.Control.html" title="wx.Control" alt="" coords="60,237,148,267"/> <area shape="rect" id="node6" href="wx.ribbon.RibbonControl.html" title="wx.ribbon.RibbonControl" alt="" coords="17,315,191,344"/> <area shape="rect" id="node2" href="wx.Window.html" title="wx.Window" alt="" coords="59,160,148,189"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,87,35"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="48,83,159,112"/> <area shape="rect" id="node4" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="112,5,213,35"/> </map> 
   </p>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.ribbon.RibbonBar`, :ref:`wx.ribbon.RibbonButtonBar`, :ref:`wx.ribbon.RibbonGallery`, :ref:`wx.ribbon.RibbonPage`, :ref:`wx.ribbon.RibbonPanel`, :ref:`wx.ribbon.RibbonToolBar`

|


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

================================================================================ ================================================================================
:meth:`~wx.ribbon.RibbonControl.__init__`                                        Constructor.
:meth:`~wx.ribbon.RibbonControl.DoGetNextLargerSize`                             Implementation of :meth:`~RibbonControl.GetNextLargerSize` .
:meth:`~wx.ribbon.RibbonControl.DoGetNextSmallerSize`                            Implementation of :meth:`~RibbonControl.GetNextSmallerSize` .
:meth:`~wx.ribbon.RibbonControl.GetAncestorRibbonBar`                            Get the first ancestor which is a :ref:`wx.ribbon.RibbonBar`  (or derived) or ``None`` if not having such parent.
:meth:`~wx.ribbon.RibbonControl.GetArtProvider`                                  Get the art provider to be used.
:meth:`~wx.ribbon.RibbonControl.GetBestSizeForParentSize`                        Finds the best width and height given the parent's width and height.
:meth:`~wx.ribbon.RibbonControl.GetNextLargerSize`                               If sizing is not continuous, then return a suitable size for the control which is larger than the current size.
:meth:`~wx.ribbon.RibbonControl.GetNextSmallerSize`                              If sizing is not continuous, then return a suitable size for the control which is smaller than the current size.
:meth:`~wx.ribbon.RibbonControl.IsSizingContinuous`                              
:meth:`~wx.ribbon.RibbonControl.Realise`                                         Alias for :meth:`~RibbonControl.Realize` .
:meth:`~wx.ribbon.RibbonControl.Realize`                                         Perform initial size and layout calculations after children have been added, and/or realize children.
:meth:`~wx.ribbon.RibbonControl.SetArtProvider`                                  Set the art provider to be used.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.ribbon.RibbonControl.AncestorRibbonBar`                               See :meth:`~wx.ribbon.RibbonControl.GetAncestorRibbonBar`
:attr:`~wx.ribbon.RibbonControl.ArtProvider`                                     See :meth:`~wx.ribbon.RibbonControl.GetArtProvider` and :meth:`~wx.ribbon.RibbonControl.SetArtProvider`
================================================================================ ================================================================================


|


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


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

   **Possible constructors**::

       RibbonControl()
       
       RibbonControl(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
                     style=0, validator=DefaultValidator, name=ControlNameStr)
       
   
   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.



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



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      Constructor.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr)`
      
      Constructor.                  
      
      If `parent`  is a :ref:`wx.ribbon.RibbonControl`  with a non-NULL art provider, then the art provider of new control is set to that of `parent`.                  
      
      
      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: wx.Validator
      :param `name`: 
      :type `name`: string
      
      
      
      
      
      
      **~~~**






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

      Implementation of :meth:`GetNextLargerSize` .                  

      Controls which have non-continuous sizing must override this virtual function rather than :meth:`GetNextLargerSize` .                  


      :param `direction`: 
      :type `direction`: wx.Orientation
      :param `relative_to`: 
      :type `relative_to`: wx.Size




      :rtype: :ref:`Size`








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

      Implementation of :meth:`GetNextSmallerSize` .                  

      Controls which have non-continuous sizing must override this virtual function rather than :meth:`GetNextSmallerSize` .                  


      :param `direction`: 
      :type `direction`: wx.Orientation
      :param `relative_to`: 
      :type `relative_to`: wx.Size




      :rtype: :ref:`Size`








   .. method:: GetAncestorRibbonBar(self)

      Get the first ancestor which is a :ref:`wx.ribbon.RibbonBar`  (or derived) or ``None`` if not having such parent.                  

                

      :rtype: :ref:`wx.ribbon.RibbonBar`







      .. versionadded:: 2.9.4 
     








   .. method:: GetArtProvider(self)

      Get the art provider to be used.                  

      Note that until an art provider has been set in some way, this function may return ``None``.                  

      :rtype: :ref:`wx.ribbon.RibbonArtProvider`








   .. method:: GetBestSizeForParentSize(self, parentSize)

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

      Used to implement the ``wx.ribbon.RIBBON_PANEL_FLEXIBLE`` panel style.                  


      :param `parentSize`: 
      :type `parentSize`: wx.Size




      :rtype: :ref:`Size`








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



      |overload| Overloaded Implementations:

      **~~~**

      
      **GetNextLargerSize** `(self, direction)`
      
      If sizing is not continuous, then return a suitable size for the control which is larger than the current size.                  
      
      
      
      
      :param `direction`: The direction(s) in which the size should increase.   
      :type `direction`: wx.Orientation
      
      
      
      
      
      
      :rtype: :ref:`Size`
      
      
      
                        
      
      
      
      :returns: 
      
         The current size if there is no larger size, otherwise a suitable size which is larger in the given direction(s), and the same as the current size in the other direction (if any).  
      
      
      
      
      
      
      
      .. seealso:: :meth:`IsSizingContinuous`     
      
      
      
      
      
      
      
      **~~~**

      
      **GetNextLargerSize** `(self, direction, relative_to)`
      
      If sizing is not continuous, then return a suitable size for the control which is larger than the given size.                  
      
      
      
      
      :param `direction`: The direction(s) in which the size should increase.   
      :type `direction`: wx.Orientation
      :param `relative_to`: The size for which a larger size should be found.   
      :type `relative_to`: wx.Size
      
      
      
      
      
      
      
      
      :rtype: :ref:`Size`
      
      
      
                        
      
      
      
      :returns: 
      
         `relative_to`  if there is no larger size, otherwise a suitable size which is larger in the given direction(s), and the same as `relative_to`  in the other direction (if any).  
      
      
      
      
      
      
      
      .. seealso:: :meth:`IsSizingContinuous`     
      
      
      
      
      
      
      
      .. seealso:: :meth:`DoGetNextLargerSize`     
      
      
      
      
      
      
      
      **~~~**






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



      |overload| Overloaded Implementations:

      **~~~**

      
      **GetNextSmallerSize** `(self, direction)`
      
      If sizing is not continuous, then return a suitable size for the control which is smaller than the current size.                  
      
      
      
      
      :param `direction`: The direction(s) in which the size should reduce.   
      :type `direction`: wx.Orientation
      
      
      
      
      
      
      :rtype: :ref:`Size`
      
      
      
                        
      
      
      
      :returns: 
      
         The current size if there is no smaller size, otherwise a suitable size which is smaller in the given direction(s), and the same as the current size in the other direction (if any).  
      
      
      
      
      
      
      
      .. seealso:: :meth:`IsSizingContinuous`     
      
      
      
      
      
      
      
      **~~~**

      
      **GetNextSmallerSize** `(self, direction, relative_to)`
      
      If sizing is not continuous, then return a suitable size for the control which is smaller than the given size.                  
      
      
      
      
      :param `direction`: The direction(s) in which the size should reduce.   
      :type `direction`: wx.Orientation
      :param `relative_to`: The size for which a smaller size should be found.   
      :type `relative_to`: wx.Size
      
      
      
      
      
      
      
      
      :rtype: :ref:`Size`
      
      
      
                        
      
      
      
      :returns: 
      
         `relative_to`  if there is no smaller size, otherwise a suitable size which is smaller in the given direction(s), and the same as `relative_to`  in the other direction (if any).  
      
      
      
      
      
      
      
      .. seealso:: :meth:`IsSizingContinuous`     
      
      
      
      
      
      
      
      .. seealso:: :meth:`DoGetNextSmallerSize`     
      
      
      
      
      
      
      
      **~~~**






   .. method:: IsSizingContinuous(self)



                

      :rtype: `bool`







      :returns: 

         ``True`` if this window can take any size (greater than its minimum size), ``False`` if it can only take certain sizes.  







      .. seealso:: :meth:`GetNextSmallerSize`     







      .. seealso:: :meth:`GetNextLargerSize`     








   .. method:: Realise(self)

      Alias for :meth:`Realize` .                  

      :rtype: `bool`








   .. method:: Realize(self)

      Perform initial size and layout calculations after children have been added, and/or realize children.                  

      :rtype: `bool`








   .. method:: SetArtProvider(self, art)

      Set the art provider to be used.                  

      In many cases, setting the art provider will also set the art provider on all child windows which extend :ref:`wx.ribbon.RibbonControl`. 

      In most cases, controls will not take ownership of the given pointer, with the notable exception being :meth:`wx.ribbon.RibbonBar.SetArtProvider` .                  


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







   .. attribute:: AncestorRibbonBar

      See :meth:`~wx.ribbon.RibbonControl.GetAncestorRibbonBar`


   .. attribute:: ArtProvider

      See :meth:`~wx.ribbon.RibbonControl.GetArtProvider` and :meth:`~wx.ribbon.RibbonControl.SetArtProvider`