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


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

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

Contains the :c:`GModelDim` widget helps to provide a consisten means
for asking a user to indicate the model dimensions that they wish to
work with.

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

The following example posts a dialog that queries for model dimensions.
The results of the query are synchronized via the grail.rtv_ variables.
We then use the :f:`getrtv` and the name of the variable to retrieve and
display the contents of each variable out to the screen.

.. Python::

 from grail.widgets import *
 from grail import rtv
 
 root = gwidgetinit()
 root.title("GModelDim Example")
 
 md = GModelDim(root,
                minx=1, maxx=10,
                minxrtv=rtv.IntegerRTV(name="varminx"),
                maxxrtv=rtv.IntegerRTV(name="varmaxx"),
 
                miny=1, maxy=10,
                minyrtv=rtv.IntegerRTV(name="varminy"),
                maxyrtv=rtv.IntegerRTV(name="varmaxy"),
 
                minz=1, maxz=10,
                minzrtv=rtv.IntegerRTV(name="varminz"),
                maxzrtv=rtv.IntegerRTV(name="varmaxz"),
                align='vertical')
 md.pack()
 
 root.mainloop()
 
 # Display the contents of the variables.
 VARIABLE_NAMES = ["varminx", "varmaxx", "varminy", 
                   "varmaxy", "varminz", "varmaxz"]
 for varname in VARIABLE_NAMES:
    var = rtv.getrtv(varname)
    value = var.get()
    print "%s: %d." % (varname, value)

The above script will create a window that will appear as follows,
 
.. figure:: figure-gmodeldim-example.gif
   :alt: Screen shot of the GModelDim widget.

   Example of the :c:`GModelDim` widget.


----------------
GModelDim Widget
----------------

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

class :dc:`GModelDim([parent, **keywords])`
    Widget to help present and collect model dimensions.

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

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

    Keywords:
      :a:`align` : ['vertical'|'horizontal']
        One of two string values that indicates how the minimum-maximum
        widgets are to be aligned.
      :a:`minx` : integer
        Minimum value for x (equivalent to xminmax_min).
      :a:`miny` : integer
        Minimum value for y (equivalent to yminmax_min).
      :a:`minz` : integer
        Minimum value for z (equivalent to zminmax_min).
      :a:`maxx` : integer
        Maximum value for x (equivalent to xminmax_max).
      :a:`maxy` : integer
        Maximum value for y (equivalent to yminmax_max).
      :a:`maxz` : integer
        Maximum value for z (equivalent to zminmax_max).
      :a:`minxrtv` : :c:`IntegerRTV`
        Variable for minimum x value in the :c:`GModelDim` widget.
      :a:`minyrtv` : :c:`IntegerRTV`
        Variable for minimum y value in the :c:`GModelDim` widget.
      :a:`minzrtv` : :c:`IntegerRTV`
        Variable for minimum z value in the :c:`GModelDim` widget.
      :a:`minxrtv` : :c:`IntegerRTV`
        Variable for maximum x value in the :c:`GModelDim` widget.
      :a:`minyrtv` : :c:`IntegerRTV`
        Variable for maximum y value in the :c:`GModelDim` widget.
      :a:`minzrtv` : :c:`IntegerRTV`
        Variable for maximum z value in the :c:`GModelDim` widget.
        
    Components:
       xminmax
         The x :c:`GMinMax` spinner widget.
       yminmax
         The y :c:`GMinMax` spinner widget.
       zminmax
         The z :c:`GMinMax` spinner widget.

    Signals:
       The follow signals are not found in the grail.const_ module, and
       are instead referenced by their strings.

       "onxminchange()" 
          Emitted when the minimum x value changes.
       "onyminchange()" 
          Emitted when the minimum y value changes.
       "onzminchange()" 
          Emitted when the minimum z value changes.
       "onxmaxchange()" 
          Emitted when the maximum x value changes.
       "onymaxchange()" 
          Emitted when the maximum y value changes.
       "onzmaxchange()" 
          Emitted when the maximum z value changes.
          
    :df:`disable()`
        Set the :c:`GModelDim` to ignore user events.
    
    :df:`enable()`
        Set the :c:`GModelDim` to respond to user events.
    
    :df:`updatevars()`
        Force all vars to synchronize with the user's input.