.. include:: ../substitutions
.. include:: ../../apps-substitutions

.. _vrocs_menus:

.. program:: vROCS 

==============
vROCS menus
==============

File
----

========================= ===================================================================
Menu Item                                 Description
========================= ===================================================================
New Query...                Starts the Query Building Wizard.  The resulting query 
                            (or queries) will be listed in the query input for a simple 
                            or validation run and displayed in the 3D window.  They are also 
                            placed in the Shape Inventory list.  This option is only 
                            available in view mode.
Open Query...               Opens a file browser for opening a saved **ROCS** query file.  
                            Acceptable saved query sources are molecules of a variety of 3D 
                            molecule types, grids or shape queries (\*.sq).  The opened file 
                            is listed as a potential query for simple or validation ROCS runs 
                            and displayed in the 3D window.  It is also placed in the Shape 
                            Inventory list.  This option is only available in view mode.
Add to Shape Inventory...   Starts the Query Building Wizard.  The resulting query (or 
                            queries) will be placed in the Shape Inventory list.  
                            This option is only available in edit mode
Open...                     Opens a file browser for opening a shape query source.  
                            Acceptable shape sources are molecules of a variety of 3D file 
                            types, grids or shape queries (\*.sq).  The opened file will 
                            be placed in the Shape Inventory list.  This option is only 
                            available in edit mode
Save Query...               Save the current query in **ROCS** query format (\*.sq).  
                            This is a save as... operation.  The user will be prompted to 
                            enter a filename and directory location for saving the new 
                            \*.sq file.  The current file will never be overwritten.  
                            Keyboard shortcut is CTRL+S.
Save Color Force Field...   Save as... operation to save a copy of the current color force 
                            field file and prompts for a filename and directory.  
                            This can be useful as a starting point to edit a new custom 
                            color force field file.
Clear...                    Clears all objects from the current **vROCS** session.  
                            Keyboard shortcut is CTRL+N.
Recent Queries...           Select from a list of recently opened queries - molecules, 
                            grids and shape queries.  The selected query will be added 
                            to the list of queries available for simple or validation ROCS 
                            runs and will be displayed in the 3D window.  The list persists 
                            across vROCS sessions.  This option is only available in view 
                            mode.
Recent Databases...         Select from a list of recently opened databases.  
                            The selected database will be used to populate the database 
                            field for simple **ROCS** runs.  The list persists across **vROCS** 
                            sessions.  This option is only available in view mode for 
                            the simple run set-up and sometimes from the Welcome page.
Recent Actives...           Select from a list of recently opened databases.  
                            The selected database will be used to populate the actives
                            field for validation **ROCS** runs.  The list persists across 
                            vROCS sessions.  This option is only available in view 
                            mode for the validation run set-up and sometimes from 
                            the Welcome page.
Recent Decoys...            Select from a list of recently opened databases.  
                            The selected database will be used to populate the decoys 
                            field for validation **ROCS** runs.  The list persists across 
                            **vROCS** sessions.  This option is only available in view mode 
                            for the validation run set-up and sometimes from the 
                            Welcome page.
Recents...                  Select from a list of recently opened shape sources - molecules,
                            grids and shape queries.  The list persists across **vROCS** 
                            sessions.  This option is only available in edit mode.
Exit...                     Close the **vROCS** session.  Displayed in the Application menu on 
                            Mac as ``Quit...``
========================= ===================================================================

Edit
----
========================= =================================================================
Menu Item                 Description
========================= =================================================================
Undo...                     Undo the last action.  This can be done repeatedly or see Undo 
                            History...  Keyboard shortcut is CTRL+Z
Undo History...             Shows the last 10 operations that can be selected to undo. 
                            The Undo history list can be much greater than 10 items so 
                            revisit this list to see additional items.
Redo...                     Redo the last action that was just undone.  This can be done 
                            repeatedly or see Redo History...  Keyboard shortcut is CTRL+Y
Redo History...             Shows the last 10 operations that have been undone and can be 
                            selected to redo.  The Redo history list can be much longer 
                            than 10 items so revisit this list to see additional items.
Preferences...              Opens the Preferences dialog to set user preferences that will 
                            persist across **vROCS** sessions.  There are two pages: vROCS and 
                            Display.  See below for full details.  Displayed in the
                            Application menu on Mac.
========================= =================================================================

Preferences
^^^^^^^^^^^^

Every user has his or her own individual preferences with regards 
to how molecules, grids, and surfaces should look and how applications 
should behave.  For this reason, a Preferences dialog is available 
which allows customization of the application to the user's preference.  
The first time **vROCS** is launched the Preferences will open automatically, 
to enable the user to set his or her own options.   A snapshot of the 
Preferences dialog can be seen :ref:`below<prefs_vrocs_fig>`.  On the left-hand side 
of the dialog is column containing preference categories.  These categories 
include: **vROCS** and Display.  Clicking on any of these categories will update 
the right-hand side of the dialog to display the options corresponding to 
the selected category.  The vROCS category includes preferences for **ROCS** 
and the color force fields.  The Display category contains preferences 
for the Open GL display of molecules and shapes.

vROCS Preferences
^^^^^^^^^^^^^^^^^

.. _vrocs_prefs:

.. _prefs_vrocs_fig:

.. figure:: ../images/vrocs/prefs_vrocs.png
   :scale: 75
   :align: center
   :alt: Preferences: vROCS
   
   **Preferences: vROCS**

.. _prefs_opengl_fig:


========================== =================================================================
Menu Item                  Description
========================== =================================================================
Default color force field  Click the radio buttons to select the default color force field 
                           which will be used to apply color atoms to molecules that are 
                           loaded into **vROCS** or to define the nature and interaction of 
                           color atoms that are added during manual query editing.  
                           This color force field information will be saved in any saved 
                           query file.  Options are: 
                           
                           Implicit Mills-Dean
                           
                           Explicit Mills-Dean
                           
                           Custom
                           
                           To use a custom color force field define the path to the color 
                           force field (\*.cff) file that contains definitions of the color 
                           atoms.  Multiple custom color force fields can be loaded into 
                           **vROCS** and are listed in the box.  The selected (active) custom 
                           color force field will be highlighted in blue.  Custom color 
                           force fields can be deleted from the list by clicking on the 
                           red X beside their name in the list.
                           
                           Changing the default color force field during an **vROCS** session 
                           will not result in changing the force field for any currently 
                           opened molecules or queries.  Changes will take place only if 
                           no molecules or queries are opened or on closing and reopening 
                           **vROCS**.
Display ROCS run in 3D     Check on to display a 3D Open GL rendering of the query and 
                           database molecules aligning as the run progresses together with 
                           2D structures for the current 5 best hits.  Click off to display 
                           a text-based run progress summary, saving compute resources on 
                           lower performance computers.  This is equivalent to checking 
                           on/off the 3D View option in the simple or validation Run 
                           Set-Up Options dialog but persists across all runs and sessions, 
                           not a single run.
Color Atom Styles          Change the color and style for the different color atom types.  
                           Select the force field from the drop-down menu.  For each color 
                           atom type select a color from the drop-down color list and a 
                           style (solid or mesh) for the color atom display.  Restore 
                           default color atom colors and styles by clicking the Restore 
                           button below.
Restore                    Click to restore the current preferences to the default ones.
Save                       Save the current preferences for this session and for future 
                           sessions of **vROCS**.
Cancel                     Click to close this dialog without applying any of the changed 
                           preferences.
========================== =================================================================

OpenGL Preferences
^^^^^^^^^^^^^^^^^^

.. figure:: ../images/vrocs/prefs_opengl.png
   :scale: 75
   :align: center
   :alt: Preferences: Display
   
   **Preferences: Display**
   
=============================== =================================================================
Menu Item                       Description
=============================== =================================================================
Background Color                Change the background color by selecting from a drop-down color 
                                list.
Lighting Position               Sets the position of the lighting used in the 3D view.
Material Shininess              Sets the shininess of solid-rendered objects in the 3D view.
Disable OpenGL Shaders          Turns off hardware shading functions.  May be useful if the
                                3D scenes are not rendering properly.
Disable Hardware Acceleration   Turns off all hardware rendering.  May be useful if scenes
                                are not rendering properly due to video driver problems.
Screenshot Shares Context       May be useful if screenshots are not being saved properly
                                on some systems.
Restore                         Click to restore the current preferences to the default ones.
Save                            Save the current preferences for this session and for 
                                future sessions of **vROCS**.
Cancel                          Click to close this dialog without applying any of the 
                                changed preferences.
=============================== =================================================================

|

There are three buttons at the bottom of the dialog.  Clicking on the Restore 
button will restore the current preferences to the default ones.  Clicking 
on the Save button will save the current preferences for this run and for 
future runs of **vROCS**.  Clicking on the Cancel button will close this dialog 
and will not apply any of the changed preferences.

Preferences are stored in a binary file (preferences.oeb) in a user-specific 
local directory on the computer currently running the application.  
The preferences file can be found in:

* ``C:\Documents_and_Settings\USERNAME\AppData\Local\OpenEye\vROCS\<version>``
  on Microsoft Windows Vista.
* ``C:\Users\USERNAME\AppData\Local\OpenEye\vROCS\<version>`` on Microsoft Windows 7.
* ``~USERNAME/.OpenEye/vROCS/<version>`` on all other platforms.  

While the preference file shares the same file extension as the 
OpenEye's binary database file, it cannot be read into **vROCS** using the 
``File > Open`` menu item.  The preferences file is loaded automatically 
when the application starts and is saved back to disk when the application 
exits.  Deleting this file is equivalent to clicking on the Restore 
button in the dialog box.

There is also a file in this same directory which called vROCS.ini 
which contains machine specific settings like the list of recent files, 
preferred layouts, and hardware stereo options.  Deleting this file 
will restore these settings to the defaults as well.

This directory can be opened from within vROCS by selecting the 
``Open User Directory`` menu item in the Help menu.

Help
----

========================== =======================================================
Menu Item                  Description
========================== =======================================================
About...                     Provides version and release information.  This should 
                             be provided when requesting technical support.  
                             Displayed in the Application menu on Mac
Documentation...             Access this user documentation manual in either PDF or 
                             HTML format.
License...                   Open and display the current license file or access a 
                             browser to set the license file.
Open Data Directory...       Opens a file browser in a platform-specific location
                             for access to the tutorial datasets.
Open User Directory...       Open a file browser in the user directory containing
                             the preferences.oeb and vROCS.ini files described 
                             above.
File Bug Report...           Opens a new email prefilled with "support@eyesopen.com"
                             in the To: field.  Write an informative title and add
                             details of the bug you wish to report.  Don't forget to
                             include details of your platform and OS.
========================== =======================================================
