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

.. highlight:: python



.. _wx.lib.agw.shapedbutton.SButton:

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

This is the main implementation of `ShapedButton`. 



|

|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>SButton</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.shapedbutton.SButton_inheritance.png" alt="Inheritance diagram of SButton" 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.lib.agw.shapedbutton.SButton.html" title="wx.lib.agw.shapedbutton.SButton" alt="" coords="5,315,237,344"/> <area shape="rect" id="node2" href="wx.Window.html" title="wx.Window" alt="" coords="77,237,165,267"/> <area shape="rect" id="node3" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="13,5,115,35"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="65,83,176,112"/> <area shape="rect" id="node6" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="61,160,181,189"/> <area shape="rect" id="node5" href="wx.Object.html" title="wx.Object" alt="" coords="139,5,220,35"/> </map> 
   </p>

|


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

:class:`wx.lib.agw.shapedbutton.SBitmapButton`, :class:`wx.lib.agw.shapedbutton.SToggleButton`

|


|super_classes| Known Superclasses
==================================

:class:`wx.Window`

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.shapedbutton.SButton.__init__`                                Default class constructor.
:meth:`~wx.lib.agw.shapedbutton.SButton.AcceptsFocus`                            Can this window be given focus by mouse click?
:meth:`~wx.lib.agw.shapedbutton.SButton.ConvertPILToWX`                          Converts a PIL image into a :class:`wx.Image`.
:meth:`~wx.lib.agw.shapedbutton.SButton.ConvertWXToPIL`                          Converts a :class:`wx.Image` into a PIL image.
:meth:`~wx.lib.agw.shapedbutton.SButton.DoGetBestSize`                           Overridden base class virtual. Determines the best size of the button
:meth:`~wx.lib.agw.shapedbutton.SButton.DrawFocusIndicator`                      Draws the focus indicator. This is a circle/ellipse inside the button
:meth:`~wx.lib.agw.shapedbutton.SButton.DrawLabel`                               Draws the label on the button.
:meth:`~wx.lib.agw.shapedbutton.SButton.DrawMainButton`                          Draws the main button, in whichever state it is.
:meth:`~wx.lib.agw.shapedbutton.SButton.Enable`                                  Enables/disables the button.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetAngleOfRotation`                      Returns angle of button label rotation, in degrees.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetButtonColour`                         Returns the button colour.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetEllipseAxis`                          Returns the ellipse axes.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetLabel`                                Returns the button label.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetLabelColour`                          Returns the button label colour.
:meth:`~wx.lib.agw.shapedbutton.SButton.GetUseFocusIndicator`                    Returns focus indicator flag.
:meth:`~wx.lib.agw.shapedbutton.SButton.InitColours`                             Calculates a new set of focus indicator colour and indicator pen
:meth:`~wx.lib.agw.shapedbutton.SButton.IsEnabled`                               Returns wheter the button is enabled or not.
:meth:`~wx.lib.agw.shapedbutton.SButton.IsOutside`                               Checks if a mouse events occurred inside the circle/ellipse or not.
:meth:`~wx.lib.agw.shapedbutton.SButton.MakePalette`                             Creates a palette to be applied on an image based on input colour.
:meth:`~wx.lib.agw.shapedbutton.SButton.Notify`                                  Notifies an event and let it be processed.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnGainFocus`                             Handles the ``wx.EVT_SET_FOCUS`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnKeyDown`                               Handles the ``wx.EVT_KEY_DOWN`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnKeyUp`                                 Handles the ``wx.EVT_KEY_UP`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnLeftDown`                              Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnLeftUp`                                Handles the ``wx.EVT_LEFT_UP`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnLoseFocus`                             Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnMotion`                                Handles the ``wx.EVT_MOTION`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnPaint`                                 Handles the ``wx.EVT_PAINT`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.OnSize`                                  Handles the ``wx.EVT_SIZE`` event for :class:`SButton`.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetAngleOfRotation`                      Sets angle of button label rotation.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetBestSize`                             Given the current font settings, calculate and set a good size.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetButtonColour`                         Sets the button colour, for all button states.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetDefault`                              Sets the button as default item.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetEllipseAxis`                          Sets the ellipse axis. What it is important is not their absolute values
:meth:`~wx.lib.agw.shapedbutton.SButton.SetLabel`                                Sets the button label.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetLabelColour`                          Sets the button label colour.
:meth:`~wx.lib.agw.shapedbutton.SButton.SetUseFocusIndicator`                    Specifies if a focus indicator (dotted line) should be used.
:meth:`~wx.lib.agw.shapedbutton.SButton.ShouldInheritColours`                    Overridden base class virtual. Buttons usually do not inherit
================================================================================ ================================================================================


|


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


.. class:: SButton(wx.Window)

   This is the main implementation of `ShapedButton`. 

   .. method:: __init__(self, parent, id=wx.ID_ANY, label="", pos=wx.DefaultPosition, size=wx.DefaultSize)

      Default class constructor.
      
      :param `parent`: the :class:`SButton` parent. Must not be ``None``;
      :param `id`: window identifier. A value of -1 indicates a default value;
      :param `label`: the button text label;
      :param `pos`: the control position. A value of (-1, -1) indicates a default position,
       chosen by either the windowing system or wxPython, depending on platform;
      :param `size`: the control size. A value of (-1, -1) indicates a default size,
       chosen by either the windowing system or wxPython, depending on platform.


   .. method:: AcceptsFocus(self)

      Can this window be given focus by mouse click?
      
      :note: Overridden from :class:`wx.Window`.


   .. method:: ConvertPILToWX(self, pil, alpha=True)

      Converts a PIL image into a :class:`wx.Image`.
      
      :param `pil`: a PIL image;
      :param `alpha`: ``True`` if the image contains alpha transparency, ``False``
       otherwise.


   .. method:: ConvertWXToPIL(self, bmp)

      Converts a :class:`wx.Image` into a PIL image.
      
      :param `bmp`: an instance of :class:`wx.Image`.


   .. method:: DoGetBestSize(self)

      Overridden base class virtual. Determines the best size of the button
      based on the label size.
      
      :note: Overridden from :class:`wx.Window`.


   .. method:: DrawFocusIndicator(self, dc, width, height)

      Draws the focus indicator. This is a circle/ellipse inside the button
      drawn with a dotted-style pen, to let the user know which button has
      the focus.
      
      :param `dc`: an instance of :class:`wx.DC`;
      :param `width`: the button width;
      :param `height`: the button height.


   .. method:: DrawLabel(self, dc, width, height, dw=0, dh=0)

      Draws the label on the button.
      
      :param `dc`: an instance of :class:`wx.DC`;
      :param `width`: the button width;
      :param `height`: the button height;
      :param `dw`: width differential, to show a 3D effect;
      :param `dh`: height differential, to show a 3D effect.


   .. method:: DrawMainButton(self, dc, width, height)

      Draws the main button, in whichever state it is.
      
      :param `dc`: an instance of :class:`wx.DC`;
      :param `width`: the button width;
      :param `height`: the button height.


   .. method:: Enable(self, enable=True)

      Enables/disables the button.
      
      :param `enable`: ``True`` to enable the button, ``False`` to disable it.
      
      :note: Overridden from :class:`wx.Window`.


   .. method:: GetAngleOfRotation(self)

      Returns angle of button label rotation, in degrees. 


   .. method:: GetButtonColour(self)

      Returns the button colour. 


   .. method:: GetEllipseAxis(self)

      Returns the ellipse axes. 


   .. method:: GetLabel(self)

      Returns the button label. 


   .. method:: GetLabelColour(self)

      Returns the button label colour. 


   .. method:: GetUseFocusIndicator(self)

      Returns focus indicator flag. 


   .. method:: InitColours(self)

      Calculates a new set of focus indicator colour and indicator pen
      based on button colour and label colour.


   .. method:: IsEnabled(self)

      Returns wheter the button is enabled or not. 


   .. method:: IsOutside(self, x, y)

      Checks if a mouse events occurred inside the circle/ellipse or not.
      
      :param `x`: the mouse x position;
      :param `y`: the mouse y position.


   .. method:: MakePalette(self, tr, tg, tb)

      Creates a palette to be applied on an image based on input colour.
      
      :param `tr`: the red intensity of the input colour;
      :param `tg`: the green intensity of the input colour;
      :param `tb`: the blue intensity of the input colour.


   .. method:: Notify(self)

      Notifies an event and let it be processed. 


   .. method:: OnGainFocus(self, event)

      Handles the ``wx.EVT_SET_FOCUS`` event for :class:`SButton`.
      
      :param `event`: a :class:`FocusEvent` event to be processed.


   .. method:: OnKeyDown(self, event)

      Handles the ``wx.EVT_KEY_DOWN`` event for :class:`SButton`.
      
      :param `event`: a :class:`KeyEvent` event to be processed.


   .. method:: OnKeyUp(self, event)

      Handles the ``wx.EVT_KEY_UP`` event for :class:`SButton`.
      
      :param `event`: a :class:`KeyEvent` event to be processed.


   .. method:: OnLeftDown(self, event)

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


   .. method:: OnLeftUp(self, event)

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


   .. method:: OnLoseFocus(self, event)

      Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`SButton`.
      
      :param `event`: a :class:`FocusEvent` event to be processed.


   .. method:: OnMotion(self, event)

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


   .. method:: OnPaint(self, event)

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


   .. method:: OnSize(self, event)

      Handles the ``wx.EVT_SIZE`` event for :class:`SButton`.
      
      :param `event`: a :class:`wx.SizeEvent` event to be processed.


   .. method:: SetAngleOfRotation(self, angle=None)

      Sets angle of button label rotation.
      
      :param `angle`: the label rotation, in degrees.


   .. method:: SetBestSize(self, size=None)

      Given the current font settings, calculate and set a good size.
      
      :param `size`: if not ``None``, an instance of :class:`wx.Size` to pass to
       `SetInitialSize`.


   .. method:: SetButtonColour(self, colour=None)

      Sets the button colour, for all button states.
      
      :param `colour`: an instance of :class:`wx.Colour`.
      
      :note: The original button images are greyscale with a lot of pixels with
       different colours. Changing smoothly the button colour in order to
       give the same 3D effect can be efficiently done only with PIL.


   .. method:: SetDefault(self)

      Sets the button as default item. 


   .. method:: SetEllipseAxis(self, main=None, secondary=None)

      Sets the ellipse axis. What it is important is not their absolute values
      but their ratio.
      
      :param `main`: a floating point number representing the absolute dimension
       of the main ellipse axis;
      :param `secondary`: a floating point number representing the absolute dimension
       of the secondary ellipse axis.


   .. method:: SetLabel(self, label=None)

      Sets the button label.
      
      :param `label`: the new button label.


   .. method:: SetLabelColour(self, colour=None)

      Sets the button label colour.
      
      :param `colour`: an instance of :class:`wx.Colour`.


   .. method:: SetUseFocusIndicator(self, flag)

      Specifies if a focus indicator (dotted line) should be used.
      
      :param `flag`: ``True`` to use the focus indicator, ``False`` otherwise.


   .. method:: ShouldInheritColours(self)

      Overridden base class virtual. Buttons usually do not inherit
      parent's colours.


