Module appframework

This module provides GUI classes that mimic Maestro panels and dialogs.  The
main class is AppFramework for running Python applications with a Maestro
look-and-feel.  It provides a menu, standard buttons (Start, Write, Reset), a
Start dialog, a Write dialog, a input source selector, and methods for adding
all the relevant job parameters to a single object (used by the user when
creating input files and launching jobs).  The StartDialog and WriteDialog
actually can be used independently of AppFramework, in case a user doesn't
require a full Maestro-like panel.  There also is an AppDialog class for a
Maestro-like dialog (i.e., with buttons packed in the lower right corner).

PyQt Note: You can specify the QtDesigner-generated form via the <ui> argument.
Widgets defined within that form are automatically included in the window. The
form should be read from the *_ui.py file as follows: 
    import <my_script_ui>
    ui = my_script_ui.Ui_Form()


There are two main ways to use AppFramework -- make an instance of the class,
or derive your own class from it.  For example...

----------
class MyGUI(schrodinger.ui.appframework.AppFramework):
    def __init__(self):
        buttons = {
            'start':{'command':self.start,'precommand':self.sanityCheck},
            'write':{'command':self.write,'precommand':self.sanityCheck},
            'reset':{'command':self.setDefaults},
            'close':{'command':self.quit}
            'help':{'command':self.help}
        }
        dialogs = {
            'start':{'jobname':'myjobname','cpus':True,'njobs':True},
            'write':{'jobname':'myjobname'}
        }
        schrodinger.ui.appframework.AppFramework.__init__(
            self,
            ui = my_script_ui.Ui_Form(),
            title="My application",
            buttons=buttons,
            dialogs=dialogs,
            inputframe={
                'support_mae' : True,
            }
        )

    def start(self):
    def write(self):
    def sanityCheck(self):
    def reset(self):
    def quit(self):
    def help(self):
----------

...or...

----------
my_app = schrodinger.ui.appframework.AppFramework(
    title = "My application",
    ui = my_script_ui.Ui_Form(),
    buttons = {
        'start':{'command':start_app,'precommand':sanity_check},
        'write':{'command':write_app,'precommand':sanity_check},
        'reset':{'command':set_app_defaults},
        'close':{'command':quit_app},
        'help':{'command':help_app}
    },
    dialogs = {
        'start':{'jobname':'myjobname','cpus':True,'njobs':True},
        'write':{'jobname':'myjobname'}
    },
    inputframe={
        'filetypes':[('Maestro Files','*.mae'),('SD Files','*.sdf')]
    }

def start_app():
def write_app():
def sanity_check():
def reset_app():
def set_app_defaults():
def quit_app():
def help_app():
----------

Of course, the second approach could be done within a class of its own, with
the button callback functions being methods of the class.


The AppFramework is configured via button and dialog dictionaries.  Each key
is a button or dialog type, and the value is a further dictionary of the
configurable attributes of the button/dialog.  The most critical attribute of
buttons is the callback command.  AppFramework calls this command when the
button is pressed, though it may take other actions first (e.g., bringing up
a dialog).  The dictionary for a particular dialog is used as keyword
arguments when creating the *Dialog instance.  The 'inputframe' is an
additional AppFramework GUI element that is configured separately from the
buttons and dialogs, but also through a dictionary.  Menus (not shown in the
examples) also can be configured (see the AppFramework documentation).

AppFramework places key job information (e.g., the jobname and host from the
StartDialog) into a JobParameters object that is stored as the 'jobparam'
attribute.  When the user's start or write method is called, retrieve the
needed job information from that object.

AppFramework provides a method for application-specific job data to be placed
into the JobParameters object.  Suppose the user's GUI is modular, with
several frames responsible for various parameters of the job.  Any object
that has a 'setup' method can be registered with the AppFramework object, and
this method will be called as part of the setup cascade that occurs when the
Start or Write button is pressed.  To register an object, append the object to
the AppFramework's 'setup' list.  The JobParameters object will be passed to
the registered object via the 'setup' method.  The 'setup' method should
return True if the setup cascade should continue (i.e., there are no
problems).

See the AppFramework, *Dialog, and JobInputFrame classes for explanations of
the various AppFramework configuration options.

The StartDialog can be used directly.  For example...

----------
sd = schrodinger.ui.appframework.StartDialog(
    parent_frame,
    jobname='myjobname',
    title='My application',
    cpus=True
)
sd_params = sd.activate()
----------

The 'sd_params' is a StartDialogParams object whose attributes are the job
parameters set up via the StartDialog.  In AppFramework, the StartDialogParams
attributes are copied into the JobParameters object.


Once you have setup the AppFramework you can add your own widgets to the
central area with 'addCentralWidget()'. Typically you'd create a QWidget 
(QFrame or QGroupBox) containing everything you need and add that just once.
If QtDesigner was used to create a layout, then instead of using
addCentralWidget(), give the form to the constructor via the 'ui' argument.

Copyright Schrodinger, LLC. All rights reserved.

Submit the specified command to run under job control with -LOCAL, and 
return the Job object. The job will be run localhost without any job file
copying.

The first item in <cmd> should be the path to the Python script to run, or
full path to a built-in program. For built-in utilities use:
os.path.join( os.environ['SCHRODINGER'], "utilities", <name> )

<jobname> - Job name to use for this job. Job's standard and error
            output will be saved to <jobname>.log

<print_jobid> - Whether to print the job ID of the job when it is launched
                (defualt is True)

Will raise an exception if a job fails to run.