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

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

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

The :c:`GPopupMenu` provides a means of showing a right click pop up menu
that can respond to menu commands.

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

The example below shows a simple version of a pop up menu that will print
out commands to the command shell.

.. Python::

 from grail.widgets import *
 import Tkinter

 def _onmousedown(e):
     popup.show(e.widget.winfo_pointerxy())

 def _onoption1():       
     print "on option1"

 def _onoption2():      
     print "on option2"
 
 def _onoption3():       
      print "on option3"

 def _ontry():           
      print "try"
 
 def _ontryagain():     
      print "try again"

 root = gwidgetinit()

 options = (("Option1", _onoption1),
            ("Option2", _onoption2),
            ("Option3", _onoption3),
            '-',
            ("Try", _ontry,),
            ("Try Again", _ontryagain,),
            '-',
            ("Disabled Option", None))
 popup = GPopupMenu(root, options=options)

 Tkinter.Label(root, text="right click on me to see the popup").pack()
 root.title("Demo - GPopupMenu")
 root.geometry("%dx%d+%d+%d" % (250, 250, 100, 100))
 root.bind("<3>", _onmousedown)    
 root.mainloop()

The above example will create a popup menu that will appears as follows,

.. figure:: figure-gpopupmenu-example.gif
   :alt: GPopupMenu screen shot.

   Example of the :c:`GPopupMenu` widget.

-----------------
GPopupMenu Widget
-----------------

The :c:`GPopupMenu` widget inherits from,
  * :c:`gwidget.GWidget` (grail.widgets.gwidget_)

class :dc:`GPopupMenu([parent, **keywords])`
    This widget functions a little different from the other widgets.  In
    this widget you specify the menu options as title-callback pairs.
    Obviously the separator doesn't have a callback and is simply specified
    as a '-' or '=' (what ever makes you happier).
    
    An example of a typical popup menu configuration options would be
    something like this,

    .. Python::
    
       options = (("Cut", _oncut),
                  ("Copy", _oncopy),
                  ("Paste", _onpaste),
                  '-'
                  ("Select All", _onselectall))
    
    where all the callbacks such as :f:`_oncut` or :f:`_oncopy` have
    already been defined.

    If you define the callback as :d:`None`, then the menu item will
    appear in a disabled state.
    
    You have to rig up the response to the right click button, but
    fortunately its not to tricky and can be done as follows,

    .. Python::
    
        def _onmousedown(event):
           popup.show(event.widget.winfo_pointerxy())
        
        popup = GPopupMenu(frame, options=options)
        frame.bind("<3>", _onmousedown)
    
    Basically what you are doing is,
    
       (a) Building the pop up menu.
       (b) Instructing the frame that the right mouse button
           event ("<3>") is attached to the :f:`_onmousedown` function.
       (c) Making a call to the :f:`show` function on the popup menu
           to make the popup menu appear where the user just made
           the right click.

    The options can not be changed once a popup menu has been
    constructed; re-construct a new popup menu if you really want.

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

       :a:`keywords` 
         Variable keyword list defined below.
   
    Keyword:
       :a:`option` : list
         Specifies the configuration for the dialog.  See the above for
         an example of how to specify the option-callback list.

    Signals:
       None.  You specify callbacks for each of your options with this widget.

    Components:
       None.
    
 
    
    :df:`show(point)`
        Forces the widget to appear at x, y (in root coordinates)
        
        Arguments:
          :a:`point` : x,y tuple
            The x and y root coordinates that you want this window to
            appear at.
        
        Example:
           
           Typically you would have your event mapped to some event
           handler, that would receive an event object (for example,
           using the bind() attribute).  Given that you had this event
           handler, and a popup menu called 'popup' you would do
           something like this,
           
           .. Python::

              def _onevent(event):
                 popup.show(e.widget.winfo_pointerxy())