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

.. highlight:: python



.. _wx.lib.agw.buttonpanel.ButtonPanel:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.buttonpanel.ButtonPanel**
==========================================================================================================================================

A custom panel class with gradient background shading with the possibility to
add buttons and controls still respecting the gradient background.



|

|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>ButtonPanel</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.buttonpanel.ButtonPanel_inheritance.png" alt="Inheritance diagram of ButtonPanel" 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.Trackable.html" title="wx.Trackable" alt="" coords="20,5,121,35"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="72,83,183,112"/> <area shape="rect" id="node4" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="67,160,188,189"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="145,5,227,35"/> <area shape="rect" id="node6" href="wx.Window.html" title="wx.Window" alt="" coords="83,237,172,267"/> <area shape="rect" id="node5" href="wx.Panel.html" title="wx.Panel" alt="" coords="90,315,165,344"/> <area shape="rect" id="node7" href="wx.lib.agw.buttonpanel.ButtonPanel.html" title="wx.lib.agw.buttonpanel.ButtonPanel" alt="" coords="5,392,251,421"/> </map> 
   </p>

|


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

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.buttonpanel.buttonpanel.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.Panel`

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.__init__`                             Default class constructor.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.AddButton`                            Adds a button to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.AddControl`                           Adds a wxPython control to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.AddSeparator`                         Adds a separator line to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.AddSpacer`                            Adds a spacer (stretchable or fixed-size) to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.Clear`                                Clears the :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.DoGetBestSize`                        Gets the size which best suits :class:`ButtonPanel`: for a control, it would be
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.DoGiveHelp`                           Shows tooltips and long help strings in :class:`StatusBar`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.DoLayout`                             Do the Layout for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.FlexibleLayout`                       Layout the items when the main caption exists.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetAlignment`                         Returns the buttons alignment.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetBarText`                           Returns the main caption text.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetBPArt`                             Returns the associated :class:`BPArt` art provider.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetControls`                          Returns the wxPython controls that belongs to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetItemSize`                          Returns the size of an item in the main :class:`ButtonPanel` sizer.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetNonFlexibleChildren`               Returns all the :class:`ButtonPanel` main sizer's children that are not
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetStyle`                             Returns the :class:`ButtonPanel` window style.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.GetUseHelp`                           Returns whether or not short and long help strings should be displayed as tooltips
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.HasBarText`                           Returns whether :class:`ButtonPanel` has a main caption text or not.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.HitTest`                              HitTest method for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.IsStandard`                           Returns whether :class:`ButtonPanel` is aligned "Standard" (left/top) or not.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.IsVertical`                           Returns whether :class:`ButtonPanel` is vertically aligned or not.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.LayoutItems`                          Layout the items using a different algorithms depending on the existance
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnEraseBackground`                    Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnLeftDown`                           Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnLeftUp`                             Handles the ``wx.EVT_LEFT_UP`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnMouseEnterWindow`                   Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnMouseLeave`                         Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnMouseMove`                          Handles the ``wx.EVT_MOTION`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnPaint`                              Handles the ``wx.EVT_PAINT`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnSize`                               Handles the ``wx.EVT_SIZE`` event for :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.OnStatusBarTimer`                     Handles the timer expiring to delete the long help string in :class:`StatusBar`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.ReCreateSizer`                        Recreates the :class:`ButtonPanel` sizer accordingly to the alignment specified.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.RemoveAllButtons`                     Remove all the buttons from :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.RemoveAllSeparators`                  Remove all the separators from :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.RemoveHelp`                           Removes the tooltips and statusbar help (if any) for a button.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.RemoveText`                           Removes the main caption text.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.RepaintOldSelection`                  Repaints the old selected/hovered button.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SetAlignment`                         Sets the buttons alignment.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SetBarText`                           Sets the main caption text.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SetBPArt`                             Sets a new :class:`BPArt` art provider to :class:`ButtonPanel`.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SetStyle`                             Sets the :class:`ButtonPanel` window style.
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SetUseHelp`                           Sets whether or not short and long help strings should be displayed as tooltips
:meth:`~wx.lib.agw.buttonpanel.ButtonPanel.SizeLayout`                           Layout the items when no main caption exists.
================================================================================ ================================================================================


|


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


.. class:: ButtonPanel(wx.Panel)

   A custom panel class with gradient background shading with the possibility to
   add buttons and controls still respecting the gradient background.

   .. method:: __init__(self, parent, id=wx.ID_ANY, text="", agwStyle=BP_DEFAULT_STYLE, alignment=BP_ALIGN_LEFT, name="buttonPanel")

      Default class constructor.
      
      :param wx.Window `parent`: the parent window. Must not be ``None``;
      :param integer `id`: window identifier. If ``wx.ID_ANY``, will automatically create an identifier;
      :param string `text`: the main caption text for :class:`ButtonPanel`;
      :param integer `agwStyle`: the AGW-specific window style (one of ``BP_DEFAULT_STYLE``, ``BP_USE_GRADIENT``);
      :param integer `alignment`: alignment of buttons (left or right);
      :param string `name`: window class name.


   .. method:: AddButton(self, btnInfo)

      Adds a button to :class:`ButtonPanel`.
      
      :param `btnInfo`: an instance of :class:`ButtonInfo`.
      
      :note: Remember to pass a :class:`ButtonInfo` instance to this method, and not a
       standard :class:`Button` or a :class:`ToolBar` tool.


   .. method:: AddControl(self, control, proportion=0, flag=wx.ALIGN_CENTER|wx.ALL, border=None)

      Adds a wxPython control to :class:`ButtonPanel`.
      
      :param `control`: an instance of :class:`wx.Window`;
      :param integer `proportion`: the control proportion (0 for fixed-size, 1 or more for a
       stretchable one);
      :param integer `flag`: one of the :class:`BoxSizer` flags;
      :param integer `border`: the control border width (in pixels), if the `flag` parameter
       is set to include any border flag.


   .. method:: AddSeparator(self)

      Adds a separator line to :class:`ButtonPanel`. 


   .. method:: AddSpacer(self, size=(0, 0), proportion=1, flag=wx.EXPAND)

      Adds a spacer (stretchable or fixed-size) to :class:`ButtonPanel`.
      
      :param tuple `size`: the spacer size as a tuple;
      :param integer `proportion`: the spacer proportion (0 for fixed-size, 1 or more for a
       stretchable one);
      :param integer `flag`: one of the :class:`BoxSizer` flags.


   .. method:: Clear(self)

      Clears the :class:`ButtonPanel`.
      
      Can be used to reset the :class:`ButtonPanel` if you'd like have a new set of
      buttons on the panel.


   .. method:: DoGetBestSize(self)

      Gets the size which best suits :class:`ButtonPanel`: 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:`Panel`.


   .. method:: DoGiveHelp(self, hit)

      Shows tooltips and long help strings in :class:`StatusBar`.
      
      :param `hit`: an instance of :class:`ButtonInfo` where the mouse is hovering.


   .. method:: DoLayout(self)

      Do the Layout for :class:`ButtonPanel`.
      
      :note: Call this method every time you make a modification to the layout
       or to the customizable sizes of the pseudo controls.


   .. method:: FlexibleLayout(self, nonspacers, allchildren)

      Layout the items when the main caption exists.
      
      :param list `nonspacers`: a list of items which are not spacers;
      :param list `allchildren`: a list of all the children of :class:`ButtonPanel`.


   .. method:: GetAlignment(self)

      Returns the buttons alignment.
      
      :return: An integer specifying the buttons alignment.
      
      :see: :meth:`~ButtonPanel.SetAlignment` for a set of valid alignment bits.


   .. method:: GetBarText(self)

      Returns the main caption text.
      
      :return: A string representing the caption text.


   .. method:: GetBPArt(self)

      Returns the associated :class:`BPArt` art provider. 


   .. method:: GetControls(self)

      Returns the wxPython controls that belongs to :class:`ButtonPanel`.
      
      :return: A list of items inside :class:`ButtonPanel` that are wxPython controls.


   .. method:: GetItemSize(self, item, isVertical)

      Returns the size of an item in the main :class:`ButtonPanel` sizer.
      
      :param `item`: an instance of :class:`ButtonInfo`;
      :param bool `isVertical`: ``True`` if :class:`ButtonPanel` is in vertical orientation,
       ``False`` otherwise.
      
      :return: An instance of :class:`wx.Size`.


   .. method:: GetNonFlexibleChildren(self)

      Returns all the :class:`ButtonPanel` main sizer's children that are not
      flexible spacers.
      
      :return: A list of items inside :class:`ButtonPanel` that are not flexible spacers.


   .. method:: GetStyle(self)

      Returns the :class:`ButtonPanel` window style.
      
      :see: :meth:`~ButtonPanel.SetStyle` for a list of valid window styles.


   .. method:: GetUseHelp(self)

      Returns whether or not short and long help strings should be displayed as tooltips
      and :class:`StatusBar` items respectively.
      
      :return: ``True`` if the short and long help strings should be displayed as tooltips
       and :class:`StatusBar` items respectively, ``False`` otherwise.


   .. method:: HasBarText(self)

      Returns whether :class:`ButtonPanel` has a main caption text or not.
      
      :return: ``True`` if :class:`ButtonPanel` has a main caption text, ``False`` otherwise.


   .. method:: HitTest(self, pt)

      HitTest method for :class:`ButtonPanel`.
      
      :param `pt`: the mouse position, an instance of :class:`wx.Point`.
      
      :returns: an instance of :class:`ButtonInfo` and the hit flag ``BP_HT_BUTTON`` if a button
       client rectangle contains the input point `pt`, or ``wx.NOT_FOUND`` and ``BP_HT_NONE``.


   .. method:: IsStandard(self)

      Returns whether :class:`ButtonPanel` is aligned "Standard" (left/top) or not.
      
      :return: ``True`` if :class:`ButtonPanel` is aligned "standard", ``False`` otherwise.


   .. method:: IsVertical(self)

      Returns whether :class:`ButtonPanel` is vertically aligned or not.
      
      :return: ``True`` if :class:`ButtonPanel` is vertically aligned, ``False`` otherwise.


   .. method:: LayoutItems(self)

      Layout the items using a different algorithms depending on the existance
      of the main caption.


   .. method:: OnEraseBackground(self, event)

      Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`ButtonPanel`.
      
      :param `event`: a :class:`EraseEvent` event to be processed.
      
      :note: This is intentionally empty to reduce flicker.


   .. method:: OnLeftDown(self, event)

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


   .. method:: OnLeftUp(self, event)

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


   .. method:: OnMouseEnterWindow(self, event)

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


   .. method:: OnMouseLeave(self, event)

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


   .. method:: OnMouseMove(self, event)

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


   .. method:: OnPaint(self, event)

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


   .. method:: OnSize(self, event)

      Handles the ``wx.EVT_SIZE`` event for :class:`ButtonPanel`.
      
      :param `event`: a :class:`wx.SizeEvent` event to be processed.
      
      .. todo::
      
         Improve the chain of methods :meth:`~ButtonPanel.OnSize` ==> :meth:`~ButtonPanel.DoLayout` ==> :meth:`~ButtonPanel.LayoutItems`
         to avoid multiple calls to :meth:`~ButtonPanel.LayoutItems`.


   .. method:: OnStatusBarTimer(self)

      Handles the timer expiring to delete the long help string in :class:`StatusBar`. 


   .. method:: ReCreateSizer(self, text=None)

      Recreates the :class:`ButtonPanel` sizer accordingly to the alignment specified.
      
      :param string `text`: the text to display as main caption. If `text` is set to ``None``,
       the main caption will not be displayed.


   .. method:: RemoveAllButtons(self)

      Remove all the buttons from :class:`ButtonPanel`.
      
      :note: This function is for internal use only. If you are interested in
       manipulating a :class:`ButtonPanel` in real time (ie. removing things on it)
       have a look at the :meth:`~ButtonPanel.Clear` method.


   .. method:: RemoveAllSeparators(self)

      Remove all the separators from :class:`ButtonPanel`.
      
      :note: This function is for internal use only. If you are interested in
       manipulating a :class:`ButtonPanel` in real time (ie. removing things on it)
       have a look at the :meth:`~ButtonPanel.Clear` method.


   .. method:: RemoveHelp(self)

      Removes the tooltips and statusbar help (if any) for a button. 


   .. method:: RemoveText(self)

      Removes the main caption text. 


   .. method:: RepaintOldSelection(self)

      Repaints the old selected/hovered button. 


   .. method:: SetAlignment(self, alignment)

      Sets the buttons alignment.
      
      :param integer `alignment`: can be one of the following bits:
      
       ====================== ======= ==========================
       Alignment Flag          Value  Description
       ====================== ======= ==========================
       ``BP_ALIGN_RIGHT``           1 Buttons are aligned on the right
       ``BP_ALIGN_LEFT``            2 Buttons are aligned on the left
       ``BP_ALIGN_TOP``             4 Buttons are aligned at the top
       ``BP_ALIGN_BOTTOM``          8 Buttons are aligned at the bottom
       ====================== ======= ==========================


   .. method:: SetBarText(self, text)

      Sets the main caption text.
      
      :param string `text`: the main caption text label. An empty string erases the
       main caption text.
       


   .. method:: SetBPArt(self, art)

      Sets a new :class:`BPArt` art provider to :class:`ButtonPanel`.
      
      :param `art`: an instance of :class:`BPArt`.


   .. method:: SetStyle(self, agwStyle)

      Sets the :class:`ButtonPanel` window style.
      
      :param integer `agwStyle`: one of the following bits:
      
       ==================== =========== ==================================================
       Window Styles        Hex Value   Description
       ==================== =========== ==================================================
       ``BP_DEFAULT_STYLE``         0x1 :class:`ButtonPanel` has a plain solid background.
       ``BP_USE_GRADIENT``          0x2 :class:`ButtonPanel` has a gradient shading background.
       ==================== =========== ==================================================


   .. method:: SetUseHelp(self, useHelp=True)

      Sets whether or not short and long help strings should be displayed as tooltips
      and :class:`StatusBar` items respectively.
      
      :param bool `useHelp`: ``True`` to display short and long help strings as tooltips
       and :class:`StatusBar` items respectively, ``False`` otherwise.


   .. method:: SizeLayout(self, nonspacers, children)

      Layout the items when no main caption exists.
      
      :param list `nonspacers`: a list of items which are not spacers;
      :param list `children`: a list of all the children of :class:`ButtonPanel`.


