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

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


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

The :c:`GRadio` widget provides the script write with the ability to
present a set mutually exclusive options. This widget functions much the
same as the :c:`Tkinter.Radiobutton`. However this allows you to attach
a run-time variable from grail.rtv_; as well as, group all your options
under one single widget.

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

The following example presents the user with three options. When the
user closes the dialog the chosen option will be written to the
console.

.. Python::

   import Tkinter

   from grail.widgets import *
   from grail import rtv

   root = gwidgetinit()
   items = ("Gaussian Distribution", "Normalized Distribution", 
           "Constant Distribution",)
   var = rtv.IntegerRTV(name="option")
   var.set(0)

   radio = GRadio(root, align="vertical", items=items, rtv=var)
   radio.pack(anchor="nw")
   root.title("Demo - GRadio")
   root.mainloop()

   print "You selected: '%s'." % (items[var.get()])

The script above will generate a widget that is shown in the figure
below,

.. figure:: figure-gradio-example.gif
   :alt: Example of GRadio widget.

   Example of the :c:`GRadio` widget.



-------------
GRadio Widget
-------------

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

class :dc:`GRadio([parent, **keywords])`
    Creates a set of radio buttons. This allows a script writer to
    present the user with a mutual exclusive list of options.

    Arguments:
       :a:`parent` : :c:`Tkinter.Frame` 
         Parent widget, widget we insert into.

       :a:`keywords` 
         Variable keyword list defined below.

    Keywords:
       The keyword :a:`variable` is *ignored*.

       :a:`align`: ['horizontal'|'vertical']
         Indicates the direction to align the GRadio options.
       :a:`items`: list
         A list of strings for each radio button.
       :a:`rtv` : :c:`RTV`
         A run-time variable that will hold the value for the most
         recently selected value.
   
    Components:
       None.

    Signal:
       :d:`const.sigON_SELECT` 
         Emitted when the user or run-time variable changes. The
         receiver function will need to receive an index argument. The
         index corresponds to the value selected in the items list.
    
    :df:`destroy()`
        Handles the Tkinter de-allocation.
    
    :df:`disable()`
        Set the radio buttons to ignore the user events.
    
    :df:`enable()`
        Set the radio buttons to respond to user events.
    
    :df:`getselected()`
        Return the index to the selected radio button.
    
    :df:`select(index)`
        Selects a radio button based on the given index.
    
    :df:`updatevars()`
        Always in a synchronized state; always returns 1.