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


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

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

Defines the :c:`GPanel` that is used in the :c:`GPanelApp` framework
(see grail.widgets.gpanelapp_).

The idea here is that if you inherit from a :c:`GPanel`, and override
the :f:`makewidgets` attribute, then we have a consistent method for
constructing panels.

.. Note::

   The grail.compass package has a specialized version of the
   :c:`GPanelApp` class that can be used within MineSightŪ-Compass. To
   use a :c:`GPanel` with a Compass capable script you will need to use
   the grail.compass.cmpsys_ module's :f:`runprocedure` function.

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

The following code illustrates creating a panel for use with a the
standard Compass panel application.

.. Python::

 from grail.widgets import *
 from grail.compass import cmpsys
 from grail import messages
 from grail import gsys
 
 class MyPanel(GPanel):
    NAME = "My Panel"
 
    def makewidgets(self):
       self._lbl_entry1 = GLabel(self, text="Entry 1: ")
       self._lbl_entry2 = GLabel(self, text="Entry 2: ")
       self._lbl_entry3 = GLabel(self, text="Entry 3: ")
       self._txt_entry1 = GTextEntry(self)
       self._txt_entry2 = GTextEntry(self)
       self._txt_entry3 = GTextEntry(self)
       left_side = [self._lbl_entry1,
                    self._lbl_entry2,
                    self._lbl_entry3]
       right_side = [self._txt_entry1,
                     self._txt_entry2,
                     self._txt_entry3]
       gtools.stdwidgetcolumns(left_side, right_side)
       self.remember(left_side+right_side)
 
 LAYOUT = GFolder("Example", [GItem(panel=MyPanel)])
 TITLE = "GPanel Example"
 
 def gmain(message, data):
    if message is messages.gRUN:
       cmpsys.runprocedure(sys.argv[0], TITLE, LAYOUT,
          startpanel=MyPanel.NAME)
    else:
       return gsys.grailmain(message, data)
 
 if __name__=="__main__":
    import sys
    isgo = cmpsys.fromcommandline(sys.argv, gmain)
    if isgo:
       sys.stdout.write("...running values against FORTRAN routine.")

Notice that in our example that :a:`self` (a reference to our particular
instance of a :c:`GPanel`), is the parent frame for all our widgets.


-------------
GPanel Widget
-------------

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

class :dc:`GPanel([parent, **keywords])`
    As a user of the MineSightŪ Grail library will never create an
    instance of the :c:`GPanel` class directly.  Instead you would
    supply your sub-class definitions of a :c:`GPanel` to the a
    :c:`GPanelApp` instance.

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

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

    
    Keywords:
      :a:`title` : string
        The title for the panel.
      :a:`widgets` : list of widgets
        Provides the list of widgets for the given panel.
   
    Methods to Override or Extend:
      :f:`makewidgets`
        Override this to define the layout of your panel.
      :f:`onshow`
        Extend this method to do any processing prior to displaying the
        panel.
      :f:`onhide`
        Extend this method to do any processing after the panel has
        hidden itself.

    Data to Overide:
      :d:`NAME`
        Overide this value to indicate the name for your panel.

    :df:`disable()`
        Calls :f:`disable()` on remembered widgets.
    
    :df:`enable()`
        Calls :f:`enable()` on remembered widgets.
    
    :df:`forget(widgetlist)`
        Removes widgets from the remembered list.  Walks the input list
        and removes widgets from the remembered list.
    
    :df:`forgetall()`
        Allows you to quickly forget every widget previously remembered.
    
    :df:`makewidgets()`
        Override this method to design your panel.

        .. Note::

           The class itself is should be your parent frame for your
           widgets.

    :df:`onshow()`
        Extend this method to do any processing prior to displaying the
        panel. This function should return 1 if the hide event is to
        proceed, and return 0 if you do not want the panel to show.

        The default return value is always 1.

    :df:`onhide()`
        Extend this method to do any processing after the panel has
        disappeared. This function should return 1 if the hide event is
        to proceed, and return 0 if you do not want the panel to hide.

        The default return value is always 1.
    
    :df:`remember(widgetlist)`
        Allows composers to remember their widgets.
        
        Remembered widgets can be disabled/enabled, and validation checks
        can be made on widgets that have been remembered.
        
        Thats about all. So if you have a list of labels, there's no
        need to remember those, because Labels are rather benign creatures.
        
        In addition, you should only remember G* widgets, because these
        widgets only have the required additional methods.  Other,
        Tkinter widgets, like :c:`Tkinter.Button`, will essentially only
        be useful in causing a performance hit in your application
        because we have to look at them to realize that we can't do
        anything interesting with them.
    
    :df:`updatevars()`
        Calls :f:`updatevars()` on remembered widgets.
   
    :dd:`NAME`
       Override this value to indicate the name for your panel.