
.. include:: substitutions

.. _scripting:

*********************
Scripting
*********************

|product| is a scriptable application which contains a built-in Python 
interpreter. Python is an interactive, interpreter, strongly and dynamically 
typed language. More information about Python can be obtained from the `Python 
website <http://www.python.org>`_. The website contains many useful 
tutorials and other related information.

All user interaction with the application goes through a Python layer even if
the user is not aware of it. For instance, every button in |product| is 
associated with a Python command that is sent to the internal interpreter when
that button is pressed. The same integration is true of all the menu items and
other GUI controls in |product|.

.. _journal_file_ref:

Journal File
============

The journal file is a recording of every action that is performed within a 
given session of |product|. In fact, the journal file is itself a Python script 
which can be run to regenerate the state of the application at the time the
file was written.

The journal file is written to ``journal.py`` in the user directory (see 
:ref:`User Directory <user_dir>`). In the unlikely event that |product| were to quit
unexpectedly, the journal file corresponding to that run will be saved in the
same directory but with a different name containing a time stamp associated
with when the application was started (e.g. ``journal_WedMar181507132009.py``).
Journal files are particularly useful for debugging unexpected application
behavior and are of extreme benefit to the application developers when 
tracking user-reported bugs. The inclusion of journal files (if possible) with
bug reports is greatly encouraged.

.. _startup_file_ref:

Startup File
============

The startup file is a Python script located in the user directory (see
:ref:`User Directory <user_dir>`) named ``startup.py``. This script (if present) is executed
each time |product| starts.

The startup file provides the user with a convenient mechanism to customize
the appearance and functionality of |product| using Python.

.. _scripts_directory_ref:

Scripts Directory
=================

In addition to interpreting the startup file (see :ref:`startup_file_ref`)
at runtime, |product| also executes any Python scripts contained in the 
``scripts`` directory of the user directory (see :ref:`User Directory <user_dir>`). This
capability provides a simple mechanism to quickly and easily add or remove 
custom functionality to |product| without having to change the startup file.

.. _scripting_manual_ref:

Scripting API
================

The complete details of the |product| Python interface and API are fully 
described in the appendix.

.. _scripting_window_ref:

Scripting Window
================

The scripting window provides an interactive user interface to the embedded 
Python interpreter. It also displays the output from any Python commands 
issued to |product| as well as any warnings or errors reported by the 
application.

.. _figure_scripting:

.. figure:: images/scriptingwindow.png
   :scale:  75
   :align:  center
   
   **Scripting Window**

The scripting window supports tab completion of the built-in API methods and
hitting the tab key again after tab completion will display the API 
documentation associated with the command directly in the window.

The window history can be cleared by typing the following command 
``InterpreterClear()`` into the scripting window.

.. _openeye_toolkits_ref:

OpenEye Toolkits
================

|product| provides the ability to import any of the OpenEye Python toolkits 
directly into the interpreter. Once a toolkit has been imported, its entire
functionality is available for use within |product|. A valid license for the
imported toolkit is required in order for the import to succeed. An exception 
will be thrown at import time if a valid license cannot be found. All of the 
toolkits come directly bundled with the application, so there is no additional 
need to perform any installation. 

Molecule, grid, and surface objects can be passed back and forth between the 
main application and the Python interpreter using a handful of methods. For
stability reasons, copies of these objects must be "checked out" of |product|, 
where they can be accessed by the toolkits. If any modifications are made to 
the objects in the interpreter, these modifications can be applied to the 
associated objects in |product| by "checking in" the modified object. One 
exception to this rule, is that it is possible to make display changes to the 
original objects by calling the built-in API functions and passing in the 
unique key obtained from the object using the ``GetKey()`` method. A number of
examples follow.

.. ..oe:source:: check_out_molecule.py
   :caption:  Check out a molecule, make a modification, and check it back in 
   :refnum:   1

.. ..oe:source:: add_molecule.py
   :caption:  Add a new molecule from Python
   :refnum:   2

.. ..oe:source:: check_out_surface.py
   :caption:  Check out a surface, make a modification, and check it back in
   :refnum:   3
   
.. ..oe:source:: add_surface.py
   :caption:  Add a new surface from Python
   :refnum:   4
   
.. ..oe:source:: check_out_grid.py
   :caption:  Check out a grid, make a modification, and check it back in
   :refnum:   5
   
.. ..oe:source:: add_grid.py
   :caption:  Add a new grid from Python
   :refnum:   6

.. _oechemlite_ref:

OEChem Objects
--------------

Most of the standard scripting functions in |product| that operate on atoms,
bonds, or molecules take a unique key as a parameter.  |product| 
adds a ``GetKey()`` function to every **OEChem** object (e.g., OEMol, OESurface,
OEAtomBase, etc.) that is accessed from |product|.
In addition, |product| adds the following methods to all 
accessed objects for convenience:

* ``IsActive()``
* ``IsLocked()``
* ``IsMarked()``
* ``IsSelected()``
* ``IsVisible()``
* ``SetLocked( value = True )``
* ``SetMarked( value = True )``
* ``SetSelected( value = True )``
* ``SetVisible( value = True )``

Access to a given molecule is provided through the 
``MoleculeGet`` function. The molecule object returned is a copy of the actual 
molecule in use in |product|. However, this copy can still be used to retrieve 
information about that original molecule as well as to alter the original 
molecule's display and associated data through the standard |product| API.

.. ..oe:source:: get_molecule.py
   :caption:  Get a molecule and select all the carbon atoms
   :refnum:   1

.. _customize_ui_ref:

Customizing the User Interface
==============================

The standard |product| scripting API provides a wide variety of options to 
customize both the menus and toolbars and is detailed extensively in the appendix.

More advanced customization and extension of the user interface is possible 
through the `PySide2 module <https://pypi.org/project/PySide2/>`_, which provides Python wrappers for the Qt
widget library used by |product| for its user interface. Using 
this module within |product| enables
the user to create and interact with entirely new user interface elements.
The specific details of the PySide2 module are described in the section below. 
For more details on Qt, please visit these links: `Qt Company <https://www.qt.io>`_,
`The Qt Project <http://www.qt-project.org>`_ and `Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_.

.. _pyside2_ref:

PySide2
--------

PySide2 is developed by the `Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_ and
is supported by the `Qt Company <https://www.qt.io>`_.

PySide2 is a complete wrapper around the Qt library which 
enables complex user interface customization and development. 

In addition,
to a complete and fully functional API for building widgets, PySide2 can also 
build widgets using the output from 
`Qt Designer <https://doc.qt.io/qt-5/qtdesigner-manual.html>`_. 
Qt Designer
is a graphical tool for designing and building user interface elements from Qt
components. Designer can save the finished widget design to an XML file (.ui) 
which can then be passed to a widget object for creation in Python. The user 
must have a valid Qt license in order to use Qt Designer.

For more details on PySide2, please visit:
`Qt for Python project <https://wiki.qt.io/Qt_for_Python>`_
