schrodinger.ui.qt.appframework module

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()

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).

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.ui.qt.appframework.get_next_jobname(prefix, starting_num=1)

Given a job name prefix, choose the next available job name based on the names of existing files in the CWD.

Parameters

starting_num (int) – The smallest number to append to the job name

Returns

The completed job name

Return type

str

schrodinger.ui.qt.appframework.make_desres_layout(product_text='', flip=False, vertical=False, third_party_name='Desmond', third_party_dev='Developed by D. E. Shaw Research')

Generate a QLayout containing the Desres logo and Schrodinger product info

Parameters

  • product_text (str) – Name of Schrodinger product to add opposite the DESRES logo

  • flip (bool) – whether to reverse the two logos left/right

  • vertical (bool) – whether to display the logos stacked vertically or side by side horizontally

  • third_party_name (str) – The name of the third party product

  • third_party_dev (str) – The developer of the third party product

schrodinger.ui.qt.appframework.make_desres_about_button(parent)

Generate the about button with copyright information for DESRES panels.

Parameters

parent (QWidget) – The parent widget (the panel)

class schrodinger.ui.qt.appframework.CustomProgressBar(parentwidget)

Bases: PyQt6.QtWidgets.QProgressBar

Class for a custom progress bar (at the bottom of some panels). Brings up the monitor panel if clicked (and if monitoring a job).

__init__(parentwidget)
setError(error)

Set the color of the progress bar to red (error=True) or normal color (error=False).

mousePressEvent(self, a0: QMouseEvent)
schrodinger.ui.qt.appframework.question(msg, button1='OK', button2='Cancel', parent=0, title='Question')

Display a prompt dialog window with specified text. Returns True if first button (default OK) is pressed, False otherwise.

schrodinger.ui.qt.appframework.filter_string_from_supported(support_mae=False, support_sd=False, support_pdb=False, support_cms=False)

Return a Qt filter string for these formats.

Parameters

  • support_mae (bool) – Whether to support maestro (strict) format.

  • support_sd (bool) – Whether to support SD format.

  • support_pdb (bool) – Whether to support PDB format.

  • support_cms (bool) – Whether to support Desmond CMS files.

Returns

Qt filter string

Return type

str

class schrodinger.ui.qt.appframework.AppDockWidget(master, object_name, dockarea)

Bases: schrodinger.ui._maestro_ui.MM_QDockWidget

A DockWidget that calls the parent class’s closeEvent when closing

__init__(master, object_name, dockarea)

Create an AppDockWidget instance

Parameters

master (QWidget) – The parent widget whose closeEvent method will get called when the QDockWidget closes

closeEvent(event)

Called by PyQt when the dock widget is closing. Calls the parent window’s closeEvent.

Parameters

event (QCloseEvent) – The QCloseEvent generated by the widget closing

class schrodinger.ui.qt.appframework.AppFramework(ui=None, title=None, subwindow=False, dockable=False, dockarea=DockWidgetArea.RightDockWidgetArea, buttons=None, dialogs=None, inputframe=None, menu=None, periodic_callback=None, config_dialog_class=<class 'schrodinger.ui.qt.config_dialog.ConfigDialog'>, help_topic=None, show_desres_icon=False, product_text='', flip=False)

Bases: PyQt6.QtWidgets.QMainWindow

The AppFramework class is basically a hull for applications.

With its own instance of a DialogParameters class, Application manages Schrodinger dialogs like start, read, and write so that the programmer is free to worry about other things. The dialogs can be manipulated at anytime to fit the needs of the programmer (please see the DialogParameters class below).

The Application class also comes with an instance of the JobParameters class (jobparam). This object is intended to be used to store all GUI settings. Please see the JobParameters class below for more information on proper usage.

In addition to these features, the AppFramework class can take arguments for Main Menu creation.

Supposing I wanted a menu of the form:

File      Edit              Help
^Save     ^Options          ^About
^Close    ^^First Option
          ^^Second Option

When I create my AppFramework instance, I would pass the following keyword, value pair:

menu = {
    1: ["File", "Edit", "Help"],
    "File": {
                "Save": {"command": <command_here>},
                "Close": {"command": <command_here>},
             },
    "Edit": {"Options": {
        "First Option": {"command": <command_here>},
        "Second Option": {"command": <command_here>},
         },
            },
    "Help": {
            "About": {"command": <command_here>},
            },
    }

The dictionary key 1 (int form, not string form) is the key for an ordering list. Because dictionaries are not ordered, this is needed to specify your prefered order.

AppFramework also manages the Bottom Button Bar. One more keyword for the AppFramework instance is “buttons”, and would appear like:

buttons = {"start": {"command": <command_here>},
                     "dialog": <boolean_show_dialog?>},
           "read": {"command": <command_here>},
           "write": {"command": <command_here>,
                     "dialog": <boolean_show_dialog?>},
           "reset": {"command": <command_here>},
           "close": {"command": <command_here>},
           "help": {"command": <command_here>},
           }

The six supported buttons are “start”, “read”, “write”, “reset”, “close”, and “help”. Any button name for which you supply a command will be created and placed in the correct location.

Non-default button names can be used by supplying a ‘text’ keyword.

You can also specify a command for start, read, and write buttons that will be called when the button is pressed before displaying the dialog with the ‘precommand’ keyword. For example, you may want to check an input before allowing the start dialog to appear. These functions should return 0 unless the dialog should not be displayed (nor the specified start/read/write function called). Any function that returns a non-zero value will halt the dialog process, and return to the GUI.

If “checkcommand” is specified, then this function will be called when the user clicks on the Start/Write button (before closing the dialog), and if the function returns a non-zero value, the dialog will not close. The only argument that is given is a job name. This callback is typically used to check for existing files based on the user-specified jobname. IMPORTANT: If the function returns 0, and <jobname>.maegz exists, AppFramework will overwrite the file without asking the user. It is up to your application to make sure the user is okay with that file being overwritten.

Before the user supplied command is called, if there is an associated dialog, the AppFramework presents the dialog, saves the input in the jobparam object mentioned above. Then AppFramework calls the command.

Button configuration options are:

  • command - Required callback function.

  • precommand - Optional command called prior to displaying dialog. Available for Start, Read, and Write dialogs.

  • dialog - If False, the Start or Write dialog is not displayed.

  • text - If used, overrides the text of the button.

Finally, there is an Input Frame that can be used. Please see that class below for information on proper use.

Parameters

  • subwindow (bool) – If subwindow is True, this panel will not try to start a new QApplication instance even if running outside of Maestro (useful for subwindows when a main window is already running).

  • dockable (bool) – If True this instance will be dockable in Maestro.

  • dockarea (Qt QFlags (See constants at top of this module)) – By default this is to the right, but you can specify any of the DOCK_AREA constants specified in this module.

  • periodic_callback (callable) – If specified, this function will be called periodically, a few times a second (frequency is not guaranteed).

  • config_dialog_class (ConfigDialog class or subclass of ConfigDialog) – This allows you to pass in custom dialogs to be used to configure your panel.

  • help_topic (str) – If given, a help button will be created and connected to the specified topic. Note that if help_topic is given, then buttons[‘help’][‘command’] will be ignored.

  • show_desres_icon (bool) – A large amount of panels are contractually bound to show a DE Shaw Research icon, turning this to True will automatically add it to the bottom of the panel.

  • product_text (str) – In panels where DE Shaw Research requires an icon (see above), we also sometimes need to specify that parts of the technology present were developed by Schrodinger. This option will only be used if show_desres_icon==True.

jobCompleted

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

__init__(ui=None, title=None, subwindow=False, dockable=False, dockarea=DockWidgetArea.RightDockWidgetArea, buttons=None, dialogs=None, inputframe=None, menu=None, periodic_callback=None, config_dialog_class=<class 'schrodinger.ui.qt.config_dialog.ConfigDialog'>, help_topic=None, show_desres_icon=False, product_text='', flip=False)

See class docstring.

setStyleSheet(self, styleSheet: str)
isDockableInMaestro()

Returns True if the PyQt panel can be docked into Maestro mainwindow. Otherwise returns false. This function should be called only after parsing the ‘dockable’ argument inside the constructor.

interior()

Return the interior frame where client widgets should be parented from

addCentralWidget(w)

Add a widget to the central area of the AppFramework dialog

exec()

Calls exec() method of the application.

show(also_raise=True, also_activate=True)

Redefine the show() method to deiconize if necessary and also raise_() the panel if ‘also_raise’ is specified as True.

Parameters

  • also_raise (bool) – If True (default), the raise_ method will also be called on the window. If False it is not. This is important on some Window managers to ensure the window is placed on top of other windows.

  • also_activate (bool) – If True (default), the activateWindow method will also be called on the window. If False it is not. This is important on some Window managers to ensure the window is placed on top of other windows.

createMenus(d)

Setup for making individual menus, create MainMenuBar.

addButtonToBottomLayout(text, command)

Adds a button to the bottom bar, to go to the right of Job Start buttons. Useful when you need a button on the bottom which is not standard job launching.

Buttons are added from left to right in the order that this function is called..

:param text text that goes on the button :type text str

:param command the slot that the button will run :param callable

Return type

str

Returns

name of button, to be used in setButtonEnabled

updateJobname()

Update jobname in parameters from main window.

start_wrapper_timeout = 3000
setButtonState(button, state)

Set the state of the specified button, e.g.,

self.setButtonState(‘start’, ‘disabled’)

The standard state is ‘normal’. Raises a RuntimeError if the button doesn’t exist or if the requested state can’t be set.

Obsolete. Please use setButtonEnabled() method instead.

setButtonEnabled(button, enabled)

Enable / disable the specified button, e.g.,

self.setButtonEnabled(‘start’, False)

Raises a RuntimeError if the button doesn’t exist.

setupJobParameters()

Setups up the job parameters from the state of the input frame. Do not call directly from your script.

Returns True if success, False on error (after displaying an error message).

getInputSource()

Return the selected input source. Available values (module constants):

  • WORKSPACE

  • SELECTED_ENTRIES

  • INCLUDED_ENTRIES

  • INCLUDED_ENTRY

  • FILE

If the panel has no input frame, raises RuntimeError.

getInputFile()

Return the selected input file path (Python string).

If the panel has no input frame, raises RuntimeError. If FILE source is not allowed, raises RuntimeError.

launchJobCmd(cmd)

Launches job control command. Automatically tracked by the job status button (no need to call monitorJob method afterwards). NOTE: Unlike similar method in AF2, this method does not add -HOST etc options.

monitorJob(jobid, showpanel=False)

Monitor the given jobid and show the monitor panel; if in maestro.

Parameters

  • jobid – jobid of the job to monitor

  • showpanel – whether to bring up the Monitor panel. By default, the panel will open if the “Open Monitor panel” preference is set.

Example, after launching the job, use the jobid to issue the command:

<AppFramework_instance>.monitorJob(<jobid>)
processEvents()

Allow the QApplication’s or Maestro’s main event loop to process pending events.

warning(text, preferences=None, key=None)

Display a warning dialog with the specified text. If preferences and key are both supplied, then the dialog will contain a “Don’t show this again” checkbox. Future invocations of this dialog with the same preferences and key values will obey the user’s show preference.

Parameters

  • text (str) – The information to display in the dialog

  • preferences – obsolete; ignored.

  • key (str) – The key to store the preference under. If specified, a “Do not show again” checkbox will be rendered in the dialog box.

Return type

None

info(text, preferences=None, key=None)

Display an information dialog with the specified text. If preferences and key are both supplied, then the dialog will contain a “Don’t show this again” checkbox. Future invocations of this dialog with the same preferences and key values will obey the user’s show preference.

Parameters

  • text (str) – The information to display in the dialog

  • preferences – obsolete; ignored.

  • key (str) – The key to store the preference under. If specified, a “Do not show again” checkbox will be rendered in the dialog box.

Return type

None

error(text, preferences=None, key=None)

Display an error dialog with the specified text. If preferences and key are both supplied, then the dialog will contain a “Don’t show this again” checkbox. Future invocations of this dialog with the same preferences and key values will obey the user’s show preference.

Parameters

  • text (str) – The information to display in the dialog

  • preferences – obsolete; ignored.

  • key (str) – The key to store the preference under. If specified, a “Do not show again” checkbox will be rendered in the dialog box.

Return type

None

question(msg, button1='OK', button2='Cancel', title='Question')

Display a prompt dialog window with specified text. Returns True if first button (default OK) is pressed, False otherwise.

askOverwrite(files=None, parent=None)

Display a dialog asking the user whether to overwrite existing files. Returns True if user chose to overwrite, False otherwise.

Optionally specify a list of files that will be overwritten if the user presses the Overwrite button.

askOverwriteIfNecessary(files)

If any of the files in the <files> list exists, will bring up a dialog box asking the user whether they want to overwrite them. Returns True if the user chose to overwrite or if specified files do not exist. Returns False if the user cancelled.

updateStatusBar()

Updates the status bar.

setWaitCursor(app_wide=True)

Set the cursor to the wait cursor. This will be an hourglass, clock or similar. Call restoreCursor() to return to the default cursor. If ‘app_wide’ is True then it will apply to the entire application (including Maestro if running there). If it’s False then it will apply only to this panel.

restoreCursor(app_wide=True)

Restore the application level cursor to the default. If ‘app_wide’ is True then if will be restored for the entire application, if it’s False, it will be just for this panel.

getApp()

Return QApplication instance which this panel is running under. If in Maestro, returns Maestro’s global QApplication instance.

closeEvent(event)

Called by QApplication when the user clicked on the “x” button to close the window. Will call the user-specified close command (if specified).

closePanel()

Hide panel, if in Maestro. Otherwise close it.

quitPanel()

Quit the panel (even if in Maestro)

Note that the calling script needs to unset the variable that holds this panel instance in order to truly delete the panel. For example, this method should be subclassed as follows:

def quitPanel(self):

global mypanel # Where mypanel is the variable holding this object appframework.AppFramework.quitPanel(self) mypanel = None

getOpenFileName(caption='Select a file', initial_dir=None, support_mae=True, support_sd=True, support_pdb=True)

Brings up an open file dialog box for selecting structure files. By default reads Maestro, SD, and PDB formats. Returns file path that is readable by StructureReader. Is user pressed cancel, empty string is returned.

trackJobProgress(job)

Display a progress dialog showing the progress of this job. (Any previously tracked job will no longer be tracked)

job - a jobcontrol.Job object.

setProgress(step, total_steps)

Set the progress bar value (bottom of the panel) to <step> out of <total_steps>

Set both to 0 to hide the progress bar.

setProgressError(error)

Set the color of the progress bar to red (error=True) or normal color (error=False).

showEvent(show_event)

Override the normal processing when the panel is shown.

help()

Display the help dialog (or a warning dialog if no help can be found). This function requires help_topic to have been given when the class was initialized.

setJobname(jobname)
class schrodinger.ui.qt.appframework.ReadDialog(parent, **kwargs)

Bases: object

Dialog allowing user to specify a file to read in. This dialog has some options which are covered in the DialogParameters class below.

Any keyword arguments (e.g., from the DialogParameters for ‘read’) passed to this class are passed to the askopenfilename used as a file browser/selector.

__init__(parent, **kwargs)

See class docstring.

dialog()

Pop up a file browser. Returns the name of the file and also stores it in the parent JobParameters object as ‘readfilename’.

class schrodinger.ui.qt.appframework.WriteDialog(parent, jobname='', title='', checkcommand=None, **kw)

Bases: object

Toplevel Qt widget that mimics the Write dialog.

The jobname is returned by activate()

__init__(parent, jobname='', title='', checkcommand=None, **kw)

The ‘jobname’ will be the starting value of the job name field. The ‘title’ will be used as the title of the window.

If pre_close_command is specified, it will be run when the user presses the Write button. The dialog is only closed if that function returns 0.

writePressed()

Called when the Write button is pressed. Closes the dialog only if the jobname is valid.

warning(text)

Display a warning window with the specified text.

activate()

Display the dialog and return user-selected job name.