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

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


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

The :c:`GTextEntry` widget is an enhancement on the :c:`Tkinter.Entry`
[#tkinter-entry]_ widget. The main goal of this widget is to provide a
means of synchronizing widget contents via the grail.rtv_ variables.

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

The following example illustrates some of the many ways you can use the
:c:`GTextEntry`. 

.. Python::

 import sys
 import Tkinter
 from grail.widgets import *
 from grail import rtv
 from grail import objsignal
 from grail import const
 
 def onnewvarvalue():
 s = var.tostring()
 s = s[1:]+s[:1]
 var.fromstring(s)
 def onnewvarvalue2(d):
 sys.stdout.write("2nd in chain!\n")
 def onchange(val):
 sys.stdout.write("onchange: %s\n" % (val))
 def onreturn(e):
 sys.stdout.write("onreturn: " +`e` + "\n")
 def ondisable():
 te.disable()
 def onenable():
 te.enable()
 
 root = gwidgetinit()
 root.title("Demo - GTextEntry")
 top, bottom = gtools.splitframe(root)
 
 var = rtv.StringRTV(value='This is a test!', name="__gtextentry test")    
 te = GTextEntry(top, width=35, text='you stink!', rtv=var)
 te.pack(expand=1, fill=Tkinter.X, anchor='nw')
 Tkinter.Button(top, text="new var value!", command=onnewvarvalue).pack()
 disablebutton = Tkinter.Button(top, text='disable', command=ondisable)
 disablebutton.pack()
 enablebutton = Tkinter.Button(top, text='enable', command=onenable)
 enablebutton.pack()
 objsignal.listen(var, const.sigON_CHANGE, None, onnewvarvalue2)
 objsignal.listen(te, const.sigON_CHANGE, None, onchange)
 objsignal.listen(te, const.sigON_RETURN, None, onreturn)
 te.component('default').bind("<Return>", onreturn)
 
 # now some other types of entries
 vars = (rtv.IntegerRTV(name="__gtextentry_integer_test"),
 rtv.FloatRTV(name="__gtextentry_float_test"),)
 texts = ("integer: ", "float: ",)
 labels = gtools.makewidgets(bottom, GLabel, len(texts), list_text=texts)
 entries = gtools.makewidgets(bottom, GTextEntry, len(vars), list_rtv=vars)
 gtools.stdwidgetcolumns(labels, entries)
 
 # activate this line to trace the variables
 # rtv.tracevars(1)
 root.mainloop()


.. figure:: figure-gtextentry-example.gif
   :alt: Example of GTextEntry widget.

   Example of the :c:`GTextEntry` widget.
  

-----------------
GTextEntry Widget
-----------------

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


class :dc:`GTextEntry([parent, **keywords])`
    A standard text entry box.

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

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

    Keywords:
       :a:`rtv` : :c:`RTV`
         Any type of :c:`RTV` object, object is synchronized and
         validated with the :c:`GTextEntry` object.
       :a:`disabledforeground`
         Color for a disabled foreground.
       :a:`disabledbackground` 
         Color for a disabled background.
       :a:`enabledforeground`
         Color for an enable foreground.
       :a:`enabledbackground`
         Color for an enable background.
       :a:`errorforeground`
         Color for an error foreground.
       :a:`errorbackground`
         Color for an error background.

       All other :c:`Tkinter.Entry` [#tkinter-entry]_ keywords are also
       available.

    Signals:  
       :d:`const.sigON_CHANGE`
         Invoked whenever the GUI representation of the internal text
         changes. Generated with the entry's contents.

       :d:`const.sigON_RETURN` 
         Invoked whenever the user hit return within the entry.
         Generated with the entry's contents.
                          
       :d:`const.sigON_KILLFOCUS` 
         Invoked whenever the entry loses focus.  Generated with the
         entry's contents.
    
    Components:
       None
    
    :df:`clearerror()`
        Clears an error state, if the widget is in one.  Does nothing if
        the widget isn't in an error state.
    
    :df:`destroy()`
        Handles the Tkinter de-allocation.
    
    :df:`disable()`
        Set the entry to ignore user events.
    
    :df:`enable()`
        Set the entry to respond to user events.
    
    :df:`flagerror()`
        Set the textentry to an error state. Use the :f:`clearerror`
        function to remove any error state.
    
    :df:`updatevars()`
        Synchronizes the internal variable and entry's contents.
    

----

.. [#tkinter-entry] 
   
   John W. Shipman. "The Label widget." *Tkinter Reference: a GUI for
   Python*. 2004 June 6. 2004 July 28. 
   <http://infohost.nmt.edu/tcc/help/pubs/tkinter/ar01s08.html>