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


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


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

Provides a standard incremental integer entry widget.

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

The following example sets up a series of :c:`GSpinner` widgets. Each
widget uses handles the data in a different format. The purpose is to
illustrate how you can handle the data format for your use of the
:c:`GSpinner` widget.

.. Python::

 from grail.widgets import *
 from grail import rtv
 from grail import objsignal
 from grail import const
 
 def onrtv1change(var):
    """Event handler for first RTV variable."""
    print "on top spinner's rtv change: rtv value= %d." % (var.get())
 
 root = gwidgetinit()
 root.title("Demo - GSpinner")
 
 var = rtv.IntegerRTV(name="__gspinner_test", value=1)
 objsignal.listen(var, const.sigON_CHANGE, None, onrtv1change)
 var2 = rtv.IntegerRTV(name="__gspinner_rtv2", value=10)
 texts = ("Range 0 to 10: ",
 "Range 5 to 15: ",
 "Range -10 to 10 (no rtv): ",)
 labels = gtools.makewidgets(root, GLabel, len(texts), list_text=texts)
 
 spin1 = GSpinner(parent=root, rtv=var, min=0, max=10)
 spin2 = GSpinner(parent=root, rtv=var2, min=5, max=15)
 spin3 = GSpinner(parent=root, min=-10, max=10, value=3)
 
 gtools.stdwidgetcolumns(labels, (spin1, spin2, spin3,))    
 root.mainloop()

The above script will generate a window that appears as the figure
below,


.. figure:: figure-gspinner-example.gif
   :alt: Example of GSpinner widget.

   Example of the :c:`GSpinner` widget.
  

---------------
GSpinner Widget
---------------

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

class :dc:`GSpinner([parent, **keywords])`
    
    Arguments:
       :a:`parent` : :c:`Tkinter.Frame` 
         Parent widget, widget we insert into.

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

    Keywords:
       :a:`min` : integer
         Minimum value for the spinner. Default is :d:`-sys.MAX_INT`.
       :a:`max` : integer
         Maximum value for the spinner. Default is :d:`sys.MAX_INT`.
       :a:`rtv` : :c:`IntegerRTV`
         Variable to associate with the spinner.

    Signal:
       :d:`const.sigON_CHANGE`
         Emitted when the contents of the :c:`GSpinner` object change.
         Attempts to guarantee that the :a:`text` value of the entry
         component is convertable to an integer prior to signal
         emission. 

    Components:
      entry 
        :c:`GTextEntry` component where the user enters the integer.
      uparrow 
        :c:`GArrow` component representing the up arrow in the
        :c:`GSpinner` object.
      downarrow
        :c:`GArrow` component representing the down arrow in the
        :c:`GSpinner` object.
    
    .. Note::
       If there is a var on this widget, and the var changes its value
       to a value that lies outside of the range [min, max], the rtv
       will then get its value clamped.
    
    :df:`clearerror()`
        Removes any flagging of an error state for the spinner.  If the
        spinner was not in an error state, then nothing happens.
    
    :df:`destroy()`
        Handles the Tkinter de-allocation.
    
    :df:`disable()` 
        Set the spinner to ignore user events.
    
    :df:`enable()` 
        Set the spinner to respond to user events.
    
    :df:`flagerror()` 
        Flags spinner as being in an error state.  If the spinner is
        already in an error state, then nothing happens.
    
    :df:`updatevars()`
        Synchronizes the Graphical User Interface (GUI) with the
        internal variable.