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


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




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

Contains the :c:`GLabel` widget. This widget provides the user the
ability to associate a run-time variable (RTV) from the grail.rtv_
module with a label. Whenever the variable changes, the contents of the
:c:`GLabel` will change.

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

The following sample script illustrates creating a :c:`GLabel` widget
and associating a run-time variable (RTV) with the widget. 

.. Python::

  import Tkinter
  
  from grail.widgets import *
  from grail import rtv
  
  root = gwidgetinit()
  root.title("GLabel Example")
  
  var = rtv.StringRTV(name="example_var", value="Hello World!")
  label = GLabel(root, rtv=var, relief=Tkinter.GROOVE)
  label.pack(expand=1, fill=Tkinter.X)
  
  root.mainloop()

If you changed the value of :a:`var` via its :f:`set` function, then you
would automatically change the text displayed within the :c:`GLabel`
widget.

The example code shown above will generate the following window,

.. figure:: figure-glabel-example.gif
   :alt: Screen shot of the GLabel widget.

   Example of the :c:`GLabel` widget.


-------------
GLabel Widget
-------------

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


class :dc:`GLabel([parent, **keywords])`
    Creates a Label that has can use a run-time variable (RTV).

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

       :a:`keywords` 
         Variable keyword list defined below.
    
    Keywords:
       All keywords usable with the :c:`Tkinter.Label` [#tkinter-label]_
       widget are usable with the :c:`GLabel` widget. In addition the
       following keyword is also defined,

       :a:`rtv` : :c:`StringRTV`
         Associates a run-time variable (grail.rtv_) with the
         :c:`GLabel` widget's :a:`text`. 


    Components:
       None.
    
    :df:`destroy()`
        Handle the Tkinter de-allocation request.
    
    :df:`disable()`
        Set the label to ignore user events.  That is the :c:`GLabel`
        widgets's natural state, so this does nothing.
    
    :df:`enable()`
        Set the label to respond to user events.  In this case we don't
        do anything.
    
    :df:`updatevars()`
        Ensure variable is synchronized with GUI.  In this case its
        *always* in synchronized.
    

-----

.. [#tkinter-label]

   John W. Shipman. "The Label widget." *Tkinter Reference: a GUI for
   Python*. 2004 June 6. 2004 June 16.
   <http://infohost.nmt.edu/tcc/help/pubs/tkinter/ar01s10.html>