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

.. currentmodule:: wx.lib.agw.shapedbutton

.. highlight:: python



.. _wx.lib.agw.shapedbutton:

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

:class:`~wx.lib.agw.shapedbutton.SButton` tries to fill the lack of "custom shaped" controls in wxPython
and it can be used to build round or elliptic-shaped buttons.


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

`ShapedButton` tries to fill the lack of "custom shaped" controls in wxPython
(that depends on the same lack in wxWidgets). It can be used to build round
buttons or elliptic buttons.

I have stolen some code from :mod:`lib.buttons` in order to recreate the same
classes (`GenButton`, `GenBitmapButton`, `GenBitmapTextButton`, `GenToggleButton`,
`GenBitmapToggleButton`, `GenBitmapTextToggleButton`). Here you have the same
classes (with "Gen" replaced by "S"), with the same event handling, but they
are rounded/elliptical buttons.

`ShapedButton` is based on a :class:`wx.Window`, in which 2 images are drawn depending
on the button state (pressed or not pressed). The 2 images have been stolen
from Audacity (written with wxWidgets) and rearranged/reshaped/restyled
using adobe PhotoShop.
Changing the button colour in runtime was more difficult, but using some
intelligent instruction from the PIL library it can be done.

`ShapedButton` reacts on mouse events *only* if the mouse event occurred inside
the circle/ellipse, even if `ShapedButton` is built on a rectangular window.
This behavior is a lot different with respect to Audacity round buttons.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.shapedbutton as SB

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init__(self, parent, -1, "ShapedButton Demo")

            panel = wx.Panel(self)

            # Create 2 bitmaps for the button
            upbmp = wx.Bitmap("play.png", wx.BITMAP_TYPE_PNG)
            disbmp = wx.Bitmap("playdisabled.png", wx.BITMAP_TYPE_PNG)

            play = SB.SBitmapToggleButton(panel, -1, upbmp, (100, 50))
            play.SetUseFocusIndicator(False)
            play.SetBitmapDisabled(disbmp)


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()


The `ShapedButton` construction and usage is quite similar to the :mod:`lib.buttons`
implementation.


Methods and Settings
====================

With `ShapedButton` you can:

- Create rounded/elliptical buttons/togglebuttons;
- Set images for the enabled/disabled/focused/selected state of the button;
- Draw the focus indicator (or disable it);
- Set label colour and font;
- Apply a rotation to the `ShapedButton` label;
- Change `ShapedButton` shape and text orientation in runtime.


.. note:: `ShapedButton` **requires** PIL (Python Imaging Library) library to be installed,
 which can be downloaded from http://www.pythonware.com/products/pil/ .


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

`No particular window styles are available for this class.`


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

This class processes the following events:

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


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

`ShapedButton` is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 16 Jul 2012, 15.00 GMT

Version 0.5


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

================================================================================ ================================================================================
:func:`~wx.lib.agw.shapedbutton.opj`                                             Convert paths to the platform-specific separator.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
`~wx.lib.agw.shapedbutton.__SToggleMixin`                                        A mixin that allows to transform any of :class:`SButton`, :class:`SBitmapButton` and
`~wx.lib.agw.shapedbutton.SBitmapButton`                                         Subclass of :class:`SButton` which displays a bitmap, acting like a
`~wx.lib.agw.shapedbutton.SBitmapTextButton`                                     Subclass of :class:`SButton` which displays a bitmap and a label.
`~wx.lib.agw.shapedbutton.SBitmapTextToggleButton`                               A `ShapedButton` toggle bitmap button with a text label.
`~wx.lib.agw.shapedbutton.SBitmapToggleButton`                                   A `ShapedButton` toggle bitmap button.
`~wx.lib.agw.shapedbutton.SButton`                                               This is the main implementation of `ShapedButton`.
`~wx.lib.agw.shapedbutton.SButtonEvent`                                          Event sent from the generic buttons when the button is activated.
`~wx.lib.agw.shapedbutton.SToggleButton`                                         A `ShapedButton` toggle button.
================================================================================ ================================================================================


|


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

   wx.lib.agw.shapedbutton.__SToggleMixin
   wx.lib.agw.shapedbutton.SBitmapButton
   wx.lib.agw.shapedbutton.SBitmapTextButton
   wx.lib.agw.shapedbutton.SBitmapTextToggleButton
   wx.lib.agw.shapedbutton.SBitmapToggleButton
   wx.lib.agw.shapedbutton.SButton
   wx.lib.agw.shapedbutton.SButtonEvent
   wx.lib.agw.shapedbutton.SToggleButton





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

.. function:: opj(path)

   Convert paths to the platform-specific separator.
   
   :param `path`: the path to convert.