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


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


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

Basically adds the semantics to treat a :c:`Tkinter.Button` as a
MineSightŪ Grail button within the MineSightŪ Grail widget library.

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

The following segment of code illustrates how a :c:`GButton` behaves. The event
chain button illustrates how you can use both the :a:`command` keyword or the
:d:`const.sigON_CLICK` signal to handle a user button click.
 
  .. Python::

    # event handlers
    def _onDisabledClicked():
        print "Called _onDisabledClicked()"

    def _onEnabledClicked():
        print "Called _onEnabledClicked()"
    
    def _onCommand(event=None):
        print "Called _onCommand() (specified via keyword)"
        
    def _onClickSignal():
        print "Called _onClickSignal() (specified via ObjSig)"
    
    root = Tkinter.Tk()
    buttons = []
    btn = GButton(root, text="disabled")
    objsignal.listen(btn, "onClick()", None, _onDisabledClicked)
    btn.disable()
    btn.focus_set()
    buttons.append(btn)

    btn = GButton(root, text="enabled")
    objsignal.listen(btn, "onClick()", None, _onEnabledClicked)
    buttons.append(btn)

    btn = GButton(root, text="event chain", command=_onCommand)
    objsignal.listen(btn, "onClick()", None, _onClickSignal)
    buttons.append(btn)

    for btn in buttons:
        btn.pack(fill='both', expand=1)

    root.title("Demo - GButton")
    root.geometry("%dx%d+%d+%d" % (200, 80, 150, 150))
    root.mainloop()


--------------
GButton Widget
--------------

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

class :dc:`GButton([parent, **kws])`
    Takes the :c:`Tkinter.Button` and adds the :f:`enable()` and 
    :f:`disable()` functions.

    Keywords:
      Same as :c:`Tkinter.Button`.

    Signal:
      :d:`const.sigON_CLICK` 
        Generated when the user clicks the button widget.

    Component:
      None.

    :df:`disable()`
        Set the button to ignore user events.
    
    :df:`enable()`
        Set the button to respond to user events.
    
    :df:`updatevars()`
        No RTVs; always returns 1.