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

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

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

The :c:`GRunFileExtension` widget is what is known as a *Compound
Widget*. This widget provides the user with ability to quickly put together a
standard user interface for querying for run file and report file
extensions.

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

The following example illustrates setting up two grail.rtv_ variables
with a :c:`GRunFileExtension` widget. When the dialog is closed, the
results will be displayed in the command window,

.. Python::

    import Tkinter
    from grail.widgets import *
    from grail import rtv

    runext = rtv.StringRTV(name="runfile-extension", value="a")
    reportext = rtv.StringRTV(name="report-extension", value="rpt")

    root = gwidgetinit()
    ext = GRunFileExtension(root, run_rtv=runext, report_rtv=reportext)
    ext.pack(anchor='nw', expand='y')

    root.title("Demo - GRunFileExtension Widget")
    root.mainloop()

    # after exiting, display to console.
    print "run file extension: %s" % (runext.get())
    print "report file extension: %s" % (reportext.get())

The widget will appear as follows,

.. figure:: figure-grunfileextension-example.gif
   :alt: Example of GRunFileExtension widget.

   Example of the :c:`GRunFileExtension` widget.




------------------------
GRunFileExtension Widget
------------------------

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

class :dc:`GRunFileExtension([parent, **keywords])`
    Provides a standard mechanism for asking the user for an extension
    for their report file and their run file.

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

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

    Keywords:
       :a:`run_rtv` : :c:`StringRTV`
         Holds the value stored for the run file extension.
       :a:`report_rtv` : :c:`StringRTV`
         Holds the value stored for the report file extension.

    Signal:
      :d:`const.sigON_CHANGE`
        Emitted whenever *either* the run file extension entry or the
        report file extension entry change. The receiver should accept
        two arguments of the form,
        
           :f:`receiver(widgetname, value)`

        Where the :a:`widgetname` is either 'run' or 'report' and the
        value is what is stored within the entry.
   
    Components:
      runentry 
        :c:`GTextEntry` widget for the run file extension.
      reportentry
        :c:`GTextEntry` widget for the report file extension.
      runlabel
        :c:`GLabel` widget for the run file extension labeling.
      reportlabel
        :c:`GLabel` widget for the report file extension labeling.
      group
        :c:`GGroup` widget that surrounds the components. 
  
    .. Note::
       That you can modify the text of the :c:`GGroup` widget by using
       the :a:`group_text` keyword.

..

    :df:`destroy()`
        Handles the Tkinter de-allocation.
    
    :df:`disable()`
        Set the widget to ignore user events.
    
    :df:`enable()`
        Set the widget to respond to user events.
    
    :df:`updatevars()`
        Synchronizes the RTVs with their respective entries.