***********
wx.CheckBox
***********

Inheritance diagram for `wx.CheckBox`:

|

.. inheritance-diagram:: wx.CheckBox

|

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

A checkbox is a labelled box which by default is either on (checkmark is visible) or off (no checkmark). Optionally 
(when the ``wx.CHK_3STATE`` style flag is set) it can have a third state, called the mixed or undetermined state. 
Often this is used as a "Does Not Apply" state.

.. seealso:: `wx.RadioButton <wx.RadioButton.html>`_, `wx.CommandEvent <../Events/wx.CommandEvent.html>`_


Derived From
^^^^^^^^^^^^^

* `wx.Control <wx.Control.html>`_ 
* `wx.Window <wx.Window.html>`_ 
* `wx.EvtHandler <wx.EvtHandler.html>`_ 
* `wx.Object <wx.Object.html>`_ 


Window Styles
^^^^^^^^^^^^^

==================================================  ==================================================  
Window Style                                        Description
==================================================  ==================================================  
``wx.CHK_2STATE``                                   Create a 2-state checkbox. This is the default.
``wx.CHK_3STATE``                                   Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and wxGTK built against GTK+ 1.2.
``wx.CHK_ALLOW_3RD_STATE_FOR_USER``                 By default a user can't set a 3-state checkbox to the third state. It can only be done from code. Using this flags allows the user to set the checkbox to the third state by clicking.
``wx.ALIGN_RIGHT``                                  Makes the text appear on the left of the checkbox.
==================================================  ==================================================  


Event Handling
^^^^^^^^^^^^^^

==================================================  ==================================================  
Event Name                                          Description
==================================================  ==================================================  
wx.EVT_CHECKBOX(id, func)                           Process a ``wx.wxEVT_COMMAND_CHECKBOX_CLICKED`` event, when the checkbox is clicked.
==================================================  ==================================================  

|

Control Appearance
^^^^^^^^^^^^^^^^^^

|

.. figure:: ../images/wxWidgets/wxmsw/checkbox.png 
   :alt: wxMSW
   :figclass: floatleft
   
   **wxMSW**


.. figure:: ../images/wxWidgets/wxmac/checkbox.png 
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: ../images/wxWidgets/wxgtk/checkbox.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|

Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `Get3StateValue <#Get3StateValue>`_ 
* `GetValue <#GetValue>`_ 
* `Is3State <#Is3State>`_ 
* `Is3rdStateAllowedForUser <#Is3rdStateAllowedForUser>`_ 
* `IsChecked <#IsChecked>`_ 
* `Set3StateValue <#Set3StateValue>`_ 
* `SetValue <#SetValue>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `ThreeStateValue <#ThreeStateValue>`_ 
* `Value <#Value>`_ 

Class API
=========

Methods
^^^^^^^


.. method:: __init__(parent, id=-1, label="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name=wx.CheckBoxNameStr)

   Creates and shows a `wx.CheckBox` control.
   
   **Parameters:**

   * `parent` (`wx.Window <wx.Window.html>`_)
   * `id` (int)
   * `label` (string)
   * `pos` (`wx.Point <wx.Point.html>`_)
   * `size` (`wx.Size <wx.Size.html>`_)
   * `style` (long)
   * `validator` (`wx.Validator <wx.Validator.html>`_)
   * `name` (string)

   |

   **Returns:**

   `wx.CheckBox <wx.CheckBox.html>`_
 

--------

.. method:: Get3StateValue()

   Gets the state of a 3-state checkbox.

   |  

   **Returns:**

   `int` 

--------

.. method:: GetValue()

   Gets the state of a 2-state checkbox.

   |  

   **Returns:**

   `bool` 

--------

.. method:: Is3State()

   Returns whether or not the checkbox is a 3-state checkbox.

   |  

   **Returns:**

   `bool` 

--------

.. method:: Is3rdStateAllowedForUser()

   Returns whether or not the user can set the checkbox to the third state.

   |  

   **Returns:**

   `bool` 

--------

.. method:: IsChecked()

   This is just a maybe more readable synonym for `GetValue <#GetValue>`_: just as the latter, it returns ``True`` if 
   the checkbox is checked and ``False`` otherwise.

   |  

   **Returns:**

   `bool` 

--------

.. method:: Set3StateValue(state)

   Sets the CheckBox to the given state.  The state parameter can be one
   of the following: 

   * ``wx.CHK_UNCHECKED`` (Check is off),
   * ``wx.CHK_CHECKED`` (the Check is on) 
   * ``wx.CHK_UNDETERMINED`` (Check is mixed). 

   Raises an exception when the CheckBox is a 2-state checkbox and setting the
   state to ``wx.CHK_UNDETERMINED``.
   

   **Parameters:**

   * `state` (int)

--------

.. method:: SetValue(state)

   Sets the checkbox to the given state. This does not cause a ``wx.wxEVT_COMMAND_CHECKBOX_CLICKED`` event to get emitted.

   **Parameters:**

   * `state` (bool): If ``True``, the check is on, otherwise it is off.

--------

Properties
^^^^^^^^^^


.. attribute:: ThreeStateValue

   See `Get3StateValue <#Get3StateValue>`_ and `Set3StateValue <#Set3StateValue>`_

.. attribute:: Value

   See `GetValue <#GetValue>`_ and `SetValue <#SetValue>`_