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

.. module:: wx.lib.agw.buttonpanel

.. currentmodule:: wx.lib.agw.buttonpanel

.. highlight:: python



.. _wx.lib.agw.buttonpanel:

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

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


Description
===========

With :class:`ButtonPanel` class you have a panel with gradient colouring
on it and with the possibility to place some buttons on it. Using a
standard panel with normal :class:`Button` leads to an ugly result: the
buttons are placed correctly on the panel - but with grey area around
them. Gradient colouring is kept behind the images - this was achieved
due to the PNG format and the transparency of the bitmaps.

The image are functioning like a buttons and can be caught in your
code using the usual::

  self.Bind(wx.EVT_BUTTON, self.OnButton)

method.

The control is generic, and support theming (well, I tested it under
Windows with the three default themes: grey, blue, silver and the
classic look).


Usage
=====

:class:`ButtonPanel` supports 4 alignments: left, right, top, bottom, which have a
different meaning and behavior with respect to :class:`ToolBar`. The easiest
thing is to try the demo to understand, but I'll try to explain how it works.

**CASE 1**: :class:`ButtonPanel` has a main caption text.

- Left alignment means :class:`ButtonPanel` is horizontal, with the text aligned to the
  left. When you shrink the demo frame, if there is not enough room for all
  the controls to be shown, the controls closest to the text are hidden;

- Right alignment means :class:`ButtonPanel` is horizontal, with the text aligned to the
  right. Item layout as above;

- Top alignment means :class:`ButtonPanel` is vertical, with the text aligned to the top.
  Item layout as above;

- Bottom alignment means :class:`ButtonPanel` is vertical, with the text aligned to the
  bottom. Item layout as above.


**CASE 2**: :class:`ButtonPanel` has **no** main caption text.

- In this case, left and right alignment are the same (as top and bottom are the same),
  but the layout strategy changes: now if there is not enough room for all the controls
  to be shown, the last added items are hidden ("last" means on the far right for an
  horizontal :class:`ButtonPanel` and far bottom for a vertical :class:`ButtonPanel`).


Usage example::

    import wx
    import wx.lib.agw.buttonpanel as BP

    class MyFrame(wx.Frame):

        def __init__(self, parent, id=-1, title="ButtonPanel", pos=wx.DefaultPosition,
                     size=(800, 600), style=wx.DEFAULT_FRAME_STYLE):

            wx.Frame.__init__(self, parent, id, title, pos, size, style)

            mainPanel = wx.Panel(self, -1)
            self.logtext = wx.TextCtrl(mainPanel, -1, "", style=wx.TE_MULTILINE)

            vSizer = wx.BoxSizer(wx.VERTICAL)
            mainPanel.SetSizer(vSizer)

            titleBar = BP.ButtonPanel(mainPanel, -1, "A Simple Test & Demo")

            btn1 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png4.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn1)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn1)

            btn2 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png3.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn2)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn2)

            btn3 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png2.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn3)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn3)

            btn4 = BP.ButtonInfo(titleBar, wx.ID_ANY, wx.Bitmap("png1.png", wx.BITMAP_TYPE_PNG))
            titleBar.AddButton(btn4)
            self.Bind(wx.EVT_BUTTON, self.OnButton, btn4)

            vSizer.Add(titleBar, 0, wx.EXPAND)
            vSizer.Add((20, 20))
            vSizer.Add(self.logtext, 1, wx.EXPAND | wx.ALL, 5)

            titleBar.DoLayout()
            vSizer.Layout()


        def OnButton(self, event):
            ''' Handler for the ``wx.EVT_BUTTON`` event. '''

            obj = event.GetEventObject()

            # This will print the button label
            print(obj.GetText())


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()



Window Styles
=============

This class supports the following window styles:

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


Events Processing
=================

This class processes the following events:

================= ==================================================
Event Name        Description
================= ==================================================
``wx.EVT_BUTTON`` Process a `wxEVT_COMMAND_BUTTON_CLICKED` event, when a button is clicked.
================= ==================================================


License And Version
===================

:class:`ButtonPanel` is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.7.


|function_summary| Functions Summary
====================================

================================================================================ ================================================================================
:func:`~wx.lib.agw.buttonpanel.BrightenColour`                                   Brighten the input colour by a factor.
:func:`~wx.lib.agw.buttonpanel.MakeDisabledBitmap`                               Creates a disabled-looking bitmap starting from the input one.
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
:ref:`~wx.lib.agw.buttonpanel.BoxSizer`                                          Pseudo-class that imitates :class:`BoxSizer`.
:ref:`~wx.lib.agw.buttonpanel.BPArt`                                             :class:`BPArt` is an art provider class which does all of the drawing for :class:`ButtonPanel`.
:ref:`~wx.lib.agw.buttonpanel.ButtonInfo`                                        This class holds information about every button that is added to
:ref:`~wx.lib.agw.buttonpanel.ButtonPanel`                                       A custom panel class with gradient background shading with the possibility to
:ref:`~wx.lib.agw.buttonpanel.ButtonPanelText`                                   This class is used to hold data about the main caption in :class:`ButtonPanel`.
:ref:`~wx.lib.agw.buttonpanel.Control`                                           This class represents a base class for all pseudo controls used in
:ref:`~wx.lib.agw.buttonpanel.Separator`                                         This class holds all the information to size and draw a separator inside
:ref:`~wx.lib.agw.buttonpanel.Sizer`                                             This is a mix-in class to add pseudo support to :class:`wx.Sizer`. Just create
:ref:`~wx.lib.agw.buttonpanel.StatusBarTimer`                                    Timer used for deleting :class:`StatusBar` long help after ``_DELAY`` seconds.
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.buttonpanel.BoxSizer
   wx.lib.agw.buttonpanel.BPArt
   wx.lib.agw.buttonpanel.ButtonInfo
   wx.lib.agw.buttonpanel.ButtonPanel
   wx.lib.agw.buttonpanel.ButtonPanelText
   wx.lib.agw.buttonpanel.Control
   wx.lib.agw.buttonpanel.Separator
   wx.lib.agw.buttonpanel.Sizer
   wx.lib.agw.buttonpanel.StatusBarTimer





Functions
------------

.. function:: BrightenColour(colour, factor)

   Brighten the input colour by a factor.
   
   :param `colour`: a valid :class:`wx.Colour` instance;
   :param integer `factor`: the factor by which the input colour should be brightened.
   
   :return: An instance of :class:`wx.Colour`, a brightened version of the input `colour`.


.. function:: MakeDisabledBitmap(original)

   Creates a disabled-looking bitmap starting from the input one.
   
   :param `original`: an instance of :class:`wx.Bitmap` to be greyed-out.
   
   :return: A greyed-out representation of the input bitmap, an instance of :class:`wx.Bitmap`.


