.. 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
.. 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>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.lib.agw.buttonpanel.ButtonPanel.html" title="A custom panel class with gradient background shading with the possibility to" alt="" coords="5,392,269,421"/> <area shape="rect" id="node2" href="wx.Panel.html" title="A panel is a window on which controls are placed." alt="" coords="97,315,178,344"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window is the base class for all windows and represents any visible object on screen." alt="" coords="89,237,186,267"/> <area shape="rect" id="node4" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="72,160,203,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="78,83,197,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="32,5,120,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="145,5,255,35"/> </map>
</p>
</div>
|
|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.
.. seealso:: :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.
.. seealso:: :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`.