==================================
``grail.widgets.gcheckbox`` module
==================================
.. include:: ../../version.h
.. include:: ref.h

.. contents:: Table of Contents
   :backlinks: top


-----------
Description
-----------

This has the definition for the :c:`GCheckBox` widget. The :c:`GCheckBox`
widget provides you with the ability to have a small checkbox and associated
text, as well as listen for a user toggle event. A toggle occurs when the user
checks or unchecks the :c:`GCheckBox` widget.

This widget is RTV  enabled (see grail.rtv_).

-------
Example
-------

The following example creates a GCheckBox widget on a very simple window.

.. Python::

  from grail.widgets import *
  from grail import objsignal
  from grail import const
  from grail import rtv

  def on_toggle(state):
      print "The Checkbox has been toggled to: ",
      if state==1:
          print "ON"
      else:
          print "OFF"

  use_multiore = rtv.IntegerRTV(name="gcheckbox-example")

  root = gwidgetinit()
  root.title("GCheckBox Example")
  root.geometry("%dx%d+%d+%d" % (200, 25, 200, 200))

  cb = GCheckBox(root, rtv=use_multiore, text="Use Multi-ore Percent")
  cb.pack(anchor='nw')
  objsignal.listen(cb, const.sigON_TOGGLE, None, on_toggle)

  root.mainloop()

  if use_multiore.get()==1:
      print "Go ahead! Use that multi-ore percent!"
  else:
      print "No way! I do not want multi-ore percent!"

If you ran the above code you would get the following Tkinter window.

.. figure:: figure-gcheckbox-example.gif
   :alt: GCheckBox screen shot.

   Example of the :c:`GCheckBox` widget.


This example displays to main features. 

 1. **Associates RTV variable with a widget.**
    
    The state of the widget is maintained *after* the window has been destroyed
    by the user. When the :f:`mainloop` function quits, the window has been
    destroyed, and we can query the :a:`use_multiore` RTV to determine what we
    should print to the screen.

 2. **Ability to listen to toggle events.**

    Via the grail.objsignal_ module we are able to listen to the :c:`GCheckBox`
    and determine if there are user events occurring. Whenever the user clicks
    on the :c:`GCheckBox` the :f:`on_toggle()` function is executed.

----------------------------
Working with Floating Points
----------------------------

When working with floating point numbers it is NOT recommended to insert
raw floating point numbers into the :c:`GComboBox`, instead prefer to
store string representations of the floating point numbers.

There is a problem comparing floating point numbers accurately on a
computer, and that can make it difficult to local an item within the
:c:`GComboBox`. 

However, if you manage how you want to represent the floating point, and
convert it to a string, and always make your comparisons with string
representations you have a much better chance of locating an item in the
list.

----------------
GCheckBox Widget
----------------

The :c:`GArrow` widget inherits from,
  * :c:`gwidget.GWidget` (grail.widgets.gwidget_)
  * :c:`objsignal.Emitter` (grail.objsignal_)

class :dc:`GCheckBox([parent, **keywords])`

    In many respects this widget is similar to the :c:`Checkbutton` widget
    [#tkinter-checkbox]_ that is imported with Tkinter [#tkinter]_.  However,
    there are a few differences between the two that should be noted.  The
    following Tkinter :c:`Checkbutton` options are disabled not available, 

      * The 'state' option is disabled for a :c:`GCheckBox`.  
	To set the state of a :c:`GCheckBox` use the :f:`enable` or 
	:f:`disable` functions.
    
      * The toggle state is modified via the 'togglestate' configuration
        option.  For example,
	 
	.. Python::
    
           cb = GCheckBox(root)
           cb['togglestate'] = 1
    
        Would set the checkbox to an on position.
    
      * The 'variable' option for a :c:`Tkinter.Checkbutton` is not
        available.
    
    In addition, the RTV variable can not be configured after the
    :c:`GCheckBox` has be initialized.

    Keywords:
    	Same as :c:`Tkinter.Checkbutton` except where noted above and the
	following,

	:a:`rtv`
	   A grail.rtv_ variable that you wish to associate with the
	   :c:`GCheckbox`. 
    
    Signal:
        :d:`const.sigON_TOGGLE` 

	   Emitted whenever the checkbox is clicked; this signal delivers the
	   state of the widget along with it. Your callback should have the
	   following signature: :f:`ontoggle(state)`.

    Components:
        None.
    
    
    :df:`causetoggleevent()`
        *Mainly for testing purposes*. Generates a toggle event.
        
        Toggles the state of the check button, and generates all the
        appropriate signals, just like a user clicked the check button.

        The preferred method for altering the toggle state is via the
        modification of the :a:`togglestate` variable,

        .. Python::

           cb = GCheckBox(root)
           cb['togglestate'] = 1
        
    
    :df:`destroy()`
        Handles the Tkinter clean-up request.
    
    :df:`disable()`
        Set the checkbox to ignore user events.
    
    :df:`enable()`
        Set the checkbox to respond to user events.
    
    :df:`updatevars()`
        Synchronizes the GUI with the variables.
        
        In this case, the very definition of a check box implies
        that the internal variables are constantly in synchronized.
	So in this case we always return 1.
       

----

.. [#tkinter-checkbox] 
      
     Fredrik Lundh. "The Checkbutton Widget" *An Introduction to Tkinter*.
     1999. June 9 2004.
     <http://www.pythonware.com/library/tkinter/introduction/checkbutton.htm>

.. [#Tkinter] 
     
      Fredrik Lundh. *An Introduction to Tkinter*. 1999. June 9 2004. 
      <http://www.pythonware.com/library/tkinter/introduction/>