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

.. highlight:: python



.. _wx.lib.agw.aquabutton.AquaButton:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.aquabutton.AquaButton**
==========================================================================================================================================

This is the main class implementation of :class:`AquaButton`. 



|

|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>AquaButton</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.aquabutton.AquaButton_inheritance.png" alt="Inheritance diagram of AquaButton" 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="19,5,120,35"/> <area shape="rect" id="node2" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="71,83,181,112"/> <area shape="rect" id="node6" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="66,160,187,189"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="144,5,225,35"/> <area shape="rect" id="node4" href="wx.Control.html" title="wx.Control" alt="" coords="83,315,171,344"/> <area shape="rect" id="node7" href="wx.lib.agw.aquabutton.AquaButton.html" title="wx.lib.agw.aquabutton.AquaButton" alt="" coords="5,392,248,421"/> <area shape="rect" id="node5" href="wx.Window.html" title="wx.Window" alt="" coords="82,237,171,267"/> </map> 
   </p>

|


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

|

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


|




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

:class:`wx.lib.agw.aquabutton.AquaToggleButton`

|


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

:class:`wx.Control`

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.aquabutton.AquaButton.__init__`                               Default class constructor.
:meth:`~wx.lib.agw.aquabutton.AquaButton.AcceptsFocus`                           Can this window be given focus by mouse click?
:meth:`~wx.lib.agw.aquabutton.AquaButton.DoEnable`                               Overridden base class virtual.
:meth:`~wx.lib.agw.aquabutton.AquaButton.DoGetBestSize`                          Overridden base class virtual. Determines the best size of the
:meth:`~wx.lib.agw.aquabutton.AquaButton.Enable`                                 Enables/disables the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetBackgroundColour`                    Returns the button colour when the mouse is not hovering on the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetDefaultAttributes`                   Overridden base class virtual. By default we should use
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetDisabledColour`                      Returns the button colour when it is disabled.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetFocusColour`                         Returns the button colour when the button has focus.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetForegroundColour`                    Returns the text colour for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetHoverColour`                         Returns the button colour when the mouse is hovering on the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetPath`                                Returns a rounded :class:`GraphicsPath` rectangle.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetPulseOnFocus`                        Returns whether the pulsing effect is active.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetRectColour`                          Returns the button rectangular background colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.GetShadowColour`                        Returns the button shadow colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.Invalidate`                             Invalidate the saved bitmap and refresh the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.LightColour`                            Return light contrast of `colour`. The colour returned is from the scale of
:meth:`~wx.lib.agw.aquabutton.AquaButton.Notify`                                 Actually sends a ``wx.EVT_BUTTON`` event to the listener (if any).
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnGainFocus`                            Handles the ``wx.EVT_SET_FOCUS`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnKeyDown`                              Handles the ``wx.EVT_KEY_DOWN`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnKeyUp`                                Handles the ``wx.EVT_KEY_UP`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnLeftDown`                             Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnLeftUp`                               Handles the ``wx.EVT_LEFT_UP`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnLoseFocus`                            Handles the ``wx.EVT_KILL_FOCUS`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnMouseEnter`                           Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnMouseLeave`                           Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnPaint`                                Handles the ``wx.EVT_PAINT`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnPulseTimer`                           Handles the ``wx.EVT_TIMER`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.OnSize`                                 Handles the ``wx.EVT_SIZE`` event for :class:`AquaButton`.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetBackgroundColour`                    Sets the :class:`AquaButton` background colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetBitmapLabel`                         Sets the bitmap label for the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetDefault`                             This sets the :class:`AquaButton` to be the default item for the panel or dialog box.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetDisabledColour`                      Sets the button colour when it is disabled.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetFocusColour`                         Sets the button colour when the button has focus.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetForegroundColour`                    Sets the :class:`AquaButton` foreground (text) colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetHoverColour`                         Sets the button colour when the mouse is hovering on the button.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetInitialSize`                         Given the current font and bezel width settings, calculate
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetPulseOnFocus`                        Sets whether to enable the pulsing effect on gaining focus or not.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetRectColour`                          Sets the button rectangular background colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.SetShadowColour`                        Sets the button shadow colour.
:meth:`~wx.lib.agw.aquabutton.AquaButton.ShouldInheritColours`                   Overridden base class virtual. Buttons usually don't inherit
================================================================================ ================================================================================


|


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


.. class:: AquaButton(wx.Control)

   This is the main class implementation of :class:`AquaButton`. 

   .. method:: __init__(self, parent, id=wx.ID_ANY, bitmap=None, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.NO_BORDER, validator=wx.DefaultValidator, name="aquabutton")

      Default class constructor.
      
      :param wx.Window `parent`: parent window. Must not be ``None``;
      :param integer `id`: window identifier. A value of -1 indicates a default value;
      :param wx.Bitmap `bitmap`: the button bitmap (if any);
      :param string `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;
      :type `pos`: tuple or :class:`wx.Point`
      :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;
      :type `size`: tuple or :class:`wx.Size`
      :param integer `style`: the button style (unused);
      :param wx.Validator `validator`: the validator associated to the button;
      :param string `name`: the button name.


   .. method:: AcceptsFocus(self)

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


   .. method:: DoEnable(self, enable)

      Overridden base class virtual.
      
      Need to Refresh otherwise Enable state change done from a
      `wx.EVT_UPDATE_UI` will not show.


   .. method:: DoGetBestSize(self)

      Overridden base class virtual. Determines the best size of the
      button based on the label and bezel size.
      
      :return: An instance of :class:`wx.Size`.
      
      :note: Overridden from :class:`wx.Control`.


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

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


   .. method:: GetBackgroundColour(self)

      Returns the button colour when the mouse is not hovering on the button.
      
      :return: An instance of :class:`wx.Colour`.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: GetDefaultAttributes(self)

      Overridden base class virtual. By default we should use
      the same font/colour attributes as the native :class:`Button`.
      
      :return: an instance of :class:`VisualAttributes`.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: GetDisabledColour(self)

      Returns the button colour when it is disabled.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetFocusColour(self)

      Returns the button colour when the button has focus.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetForegroundColour(self)

      Returns the text colour for :class:`AquaButton`.
      
      :return: An instance of :class:`wx.Colour`.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: GetHoverColour(self)

      Returns the button colour when the mouse is hovering on the button.
      
      :return: An instance of :class:`wx.Colour`.


   .. method:: GetPath(self, gc, rc, r)

      Returns a rounded :class:`GraphicsPath` rectangle.
      
      :param `gc`: an instance of :class:`GraphicsContext`;
      :param wx.Rect `rc`: a client rectangle;
      :param float `r`: the radius of the rounded part of the rectangle.
      
      :return: A rounded rectangle, an instance of :class:`GraphicsPath`.


   .. method:: GetPulseOnFocus(self)

      Returns whether the pulsing effect is active.
      
      :return: ``True`` if the pulsing effect is active, ``False`` otherwise.


   .. method:: GetRectColour(self)

      Returns the button rectangular background colour.
      
      :return: An instance of :class:`wx.Colour`.
      
      .. versionadded:: 0.9.7


   .. method:: GetShadowColour(self)

      Returns the button shadow colour.
      
      :return: An instance of :class:`wx.Colour`.
      
      .. versionadded:: 0.9.7


   .. method:: Invalidate(self)

      Invalidate the saved bitmap and refresh the button. 


   .. method:: LightColour(self, colour, percent)

      Return light contrast of `colour`. The colour returned is from the scale of
      `colour` ==> white.
      
      :param `colour`: the input colour to be brightened, a valid instance of :class:`wx.Colour`;
      :param integer `percent`: determines how light the colour will be. `percent` = ``100``
       returns white, `percent` = ``0`` returns `colour`.
      
      :return: A light contrast of the input `colour`, an instance of :class:`wx.Colour`.


   .. method:: Notify(self)

      Actually sends a ``wx.EVT_BUTTON`` event to the listener (if any). 


   .. method:: OnGainFocus(self, event)

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


   .. method:: OnKeyDown(self, event)

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


   .. method:: OnKeyUp(self, event)

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


   .. method:: OnLeftDown(self, event)

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


   .. method:: OnLeftUp(self, event)

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


   .. method:: OnLoseFocus(self, event)

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


   .. method:: OnMouseEnter(self, event)

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


   .. method:: OnMouseLeave(self, event)

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


   .. method:: OnPaint(self, event)

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


   .. method:: OnPulseTimer(self, event)

      Handles the ``wx.EVT_TIMER`` event for :class:`AquaButton`.
      
      :param `event`: a :class:`TimerEvent` event to be processed.
      
      :note: This method is only invoked when `pulseOnFocus` is ``True``.


   .. method:: OnSize(self, event)

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


   .. method:: SetBackgroundColour(self, colour)

      Sets the :class:`AquaButton` background colour.
      
      :param `colour`: a valid :class:`wx.Colour` object.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: SetBitmapLabel(self, bitmap)

      Sets the bitmap label for the button.
      
      :param `bitmap`: the bitmap label to set, an instance of :class:`wx.Bitmap`.


   .. method:: SetDefault(self)

      This sets the :class:`AquaButton` to be the default item for the panel or dialog box.
      
      :note: Under Windows, only dialog box buttons respond to this function. As normal
       under Windows and Motif, pressing return causes the default button to be depressed
       when the return key is pressed. See also :meth:`wx.Window.SetFocus` which sets the
       keyboard focus for windows and text panel items, and :meth:`TopLevelWindow.SetDefaultItem`.
      
      :note: Note that under Motif, calling this function immediately after creation of a button
       and before the creation of other buttons will cause misalignment of the row of buttons,
       since default buttons are larger. To get around this, call :meth:`SetDefault` after you
       have created a row of buttons: wxPython will then set the size of all buttons currently
       on the panel to the same size.


   .. method:: SetDisabledColour(self, colour)

      Sets the button colour when it is disabled.
      
      :param `colour`: a valid :class:`wx.Colour` object.


   .. method:: SetFocusColour(self, colour)

      Sets the button colour when the button has focus.
      
      :param `colour`: a valid :class:`wx.Colour` object.


   .. method:: SetForegroundColour(self, colour)

      Sets the :class:`AquaButton` foreground (text) colour.
      
      :param `colour`: a valid :class:`wx.Colour` object.
      
      :note: Overridden from :class:`wx.Control`.


   .. method:: SetHoverColour(self, colour)

      Sets the button colour when the mouse is hovering on the button.
      
      :param `colour`: a valid :class:`wx.Colour` object.


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

      Given the current font and bezel width settings, calculate
      and set a good size.
      
      :param `size`: an instance of :class:`wx.Size` or ``None``, in which case the wxWidgets
       :class:`DefaultSize` is used instead.


   .. method:: SetPulseOnFocus(self, pulse)

      Sets whether to enable the pulsing effect on gaining focus or not.
      
      :param bool `pulse`: ``True`` to enable pulsing when the :class:`AquaButton` gains focus,
       ``False`` to disable this effect.


   .. method:: SetRectColour(self, colour)

      Sets the button rectangular background colour.
      
      :param `colour`: a valid :class:`wx.Colour` object.
      
      .. versionadded:: 0.9.7


   .. method:: SetShadowColour(self, colour)

      Sets the button shadow colour.
      
      :param `colour`: a valid :class:`wx.Colour` object.
      
      .. versionadded:: 0.9.7


   .. method:: ShouldInheritColours(self)

      Overridden base class virtual. Buttons usually don't inherit
      the parent's colours.
      
      :note: Overridden from :class:`wx.Control`.


