Function:     QtDataBrowser

Purpose:      QtDataBrowser is class to provide a graphical interface which enables
              a user to compose a valid data source input. 
              It can also deal with (zipped) FITS files and FITS files from the
              Internet using a valid web address. It recognizes multiple image header
              data units (HDU's) in a FITS file and it can process so called 
              'alternative headers'. 


Category:     USER IO

Files:        setbrowser.py

Author:       M.G.R. Vogelaar

Use:          browser = QtDataBrowser(parent=None,         # Parent Widget
                                      GipsyAppClassmes=1,  # Integer
                                      classDim=2,          # Integer
                                      missionTxt="",       # Character string
                                      restrictBox=True,    # Is box restricted to header values?
                                      maxSubsets=None)     # Max. number of subsetrs in structure
              

              parent -     A parent Widget or None. From a parent, a group style can be
                           borrowed.

    
              GipsyAppClass -
                           The class (1 or 2) of the GIPSY application which uses
                           the result of this composer
                           More documentation about class 1/2 applications can be found in
                           http://www.astro.rug.nl/~gipsy/gds/memo.gdsinp.pdf
                           The class is set to 1 by default. If you enter a number other
                           than 1 or 2, the parameter is set to 1 and a selection for
                           a class option is provided on the GUI.
                           If the browser is started from main() in this program,
                           the class is set to -1. Two extra buttons will appear near
                           the result fields for set/sussets and box. With this button
                           one can send the result to Hermes (e.g. to supply a prompted
                           keyword with content).
    

              classDim -   If GipsyAppClass=1:
                           The dimension of the subsets.
                           The default value is classDim=0 which implies that any dimensionality
                           is accepted. For images one should specify classDim=2.
                           If GipsyAppClass=2:
                           The number of operation axis, i.e. along which an operation
                           (e.g. mean, sum) is performed. The default value is
                           classDim=0 which implies that any number of operation axes is allowed.
                            Note that class 2 applications always need more than 1 subset.

                                
              missionTxt - A string that will appear on the GUI as a help for the
                           user to compose the right input. 


              restrictBox -
                           Force user to enter box values within their grid ranges.
                           Note that some applications allow for a box bigger than
                           the entire subset.
    

              maxSubsets -
                           Maximum number of subsets. See also $gip_sub/gdsinp.dc2
                           Usually the input is processed by a routine like gdsinp()
                           which requires an upper bound on the number of subsets.
                           Note that if your input has many subsets (several thousands),
                           the process of reading  the input can be slow
                           (because the creation of so called coordinate words takes time)
                           By default the parameter is not set and any number of subsets
                           is allowed. It seems wise to set a value to prevent a user
                           to enter too many subsets by accident.


Methods:      getOpenSet()
              For a QtDataBrowser object, use this method to pop up the browser/composer.
              See also the example.


Returns:      For valid input, this method returns a tuple with two strings
              The first string is the Set/subset specification and the 
              second string is the box. See also the example.
              If Cancel is pressed, None is returned.


Description:  For data sources with more than two axes (dimensions), it is
              not often clear how to compose the set/subset specification,
              This method presents a Graphical User Interface with the 
              functionality of an input composer. It forces the user to 
              select the right number of axes to match with the required
              dimension of the data (e.g. 2 for images).
              It can be used as a stand alone program to inspect your 
              data on disk as, for example, with task DISK.



Example:      The composer will be used in the context of a (py)Qt application.
              In the next example we demonstrate its use. Note that we did
              not list the necessary import statements.


              import gipsy
              from PyQt4.QtGui import QApplication
              from setbrowser import QtDataBrowser
     
              def main():
                 gipsy.init()
                 app = QApplication(sys.argv)
                 fn = QtDataBrowser(GipsyAppClass=2, classDim=0, maxSubsets=1000).getOpenSet()
                 if fn:
                    gipsy.anyout("Set/subset: %s"%(fn[0]))
                    gipsy.anyout("Box: %s"%(fn[1]))
                 gipsy.finis()


Updates:      Feb 21, 2013: VOG, Document created.