
Scope Functions
***************************

The functions detailed in this section enable the user to access information
about and change the state of the application through the multiple different
available scopes.

.. oe:function:: Active


   .. oe:api::


      void Active(const OEPropDB::OEKey &k)
      void Active(unsigned int id, unsigned int conf=UINT_MAX)

   Makes the specified object the *Active* or *Focused* object in the 
   application. The object is specified by passing either an OEKey object or a 
   unique ID paired with a conformer index (if dealing with multiconformer 
   molecules). 

.. oe:function:: ActiveConformer


   .. oe:api::


      unsigned int ActiveConformer()

   Returns the index of the currently *Active* or *Focused* conformer.

.. oe:function:: ActiveID


   .. oe:api::


      unsigned int ActiveID()

   Returns the unique ID associated with the currently *Active* or *Focused* 
   object.

.. oe:function:: ActiveKey


   .. oe:api::


      OEPropDB::OEKey ActiveKey()

   Returns the unique key associated with the currently *Active* or *Focused* 
   object.

.. oe:function:: ClearActive


   .. oe:api::


      void ClearActive()

   Clears the *active* / *focused* property from the currently *active* object.

.. oe:function:: ClearLocked


   .. oe:api::


      void ClearLocked()

   Clears the locked property from all objects.

.. oe:function:: ClearMarked


   .. oe:api::


      void ClearMarked()

   Clears the marked property from all objects.

.. oe:function:: ClearSelection


   .. oe:api::


      void ClearSelection()

   Clears the selected property from all objects.

.. oe:function:: ClearVisible


   .. oe:api::


      void ClearVisible()

   Clears the visible property from all objects.

.. oe:function:: ContextClear


   .. oe:api::


      void ContextClear()

   Clears the context scope.

.. oe:function:: ContextGet


   .. oe:api::


      std::vector<OEPropDB::OEKey> ContextGet()

   Returns the list of keys currently contained in the context scope. The 
   "context" scope is used to determine which operations are appropriate 
   for display in the right-click popup menu.

.. oe:function:: ContextInsert


   .. oe:api::


      void ContextInsert(const OEPropDB::OEKey &)
      void ContextInsert(const std::vector<OEPropDB::OEKey> &)

   Inserts the specified key(s) into the context scope. The "context" scope is
   used to determine which operations are appropriate for display in the 
   right-click popup menu.

.. oe:function:: ContextKeysSet


   .. oe:api::


      void ContextKeysSet(const OEPropDB::OEKeyGroup &k)
      void ContextKeysSet(const std::vector<OEPropDB::OEKey> &keys)

   Sets the specified keys to be the "context" keys which are used to determine
   which operations are appropriate for display in the right-click popup menu.

.. oe:function:: ContextSet


   .. oe:api::


      void ContextSet(const OEPropDB::OEKey &)
      void ContextSet(const std::string &prop)
      void ContextSet(const std::vector<OEPropDB::OEKey> &)

   Sets the specified key(s) to be the "context" keys which are used to determine
   which operations are appropriate for display in the right-click popup menu.

.. oe:function:: DefaultScopeGet


   .. oe:api::


      unsigned int DefaultScopeGet()

   Returns the default scope of operations.

.. oe:function:: DefaultScopeSet


   .. oe:api::


      void DefaultScopeSet(unsigned int scope)

   Sets the default scope of operations. Valid parameters are:
  
    * ActiveScope - operations are performed on the *active* / *focused* 
                    object
    * ActiveThenVisibleScope - operations are performed only on the *active* /
                               *focused* object; however, if no object has that
                               property, the operations are performed on the
                               *visible* objects
    * AllScope - operations are performed on all of the currently loaded 
                 objects
    * BestScope - allows the application to determine the current best scope
                  for operations based on the context of the operation
    * MarkedScope - operations are performed on all of the *marked* objects
    * ScratchScope - operations are performed on all of the objects that were
                     added to the *scratch* scope using the 
                     :oe:func:`ScratchInsert` and the
                     :oe:func:`ScratchSet` functions.
    * SelectedScope - operations are performed only on *selected* objects
    * VisibleScope - operations are performed on all of the *visible* objects

.. oe:function:: GetAllContextKeys


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetAllContextKeys()

   Returns all of the relevant keys of interest corresponding to the current
   state of the application. 

.. oe:function:: GetAtomsScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetAtomsScoped(unsigned int scope)

   Returns a list of all the atom keys in the specified scope.

.. oe:function:: GetBondsScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetBondsScoped(unsigned int scope)

   Returns a list of all the bond keys in the specified scope.

.. oe:function:: GetContoursScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetContoursScoped(unsigned int scope)

   Returns a list of all the contour keys in the specified scope.

.. oe:function:: GetGridsScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetGridsScoped(unsigned int scope)

   Returns a list of all the grid keys in the specified scope.

.. oe:function:: GetMarkedAtoms


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedAtoms()

   Returns a list of keys corresponding to all of the currently marked atoms.

.. oe:function:: GetMarkedAtomsScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedAtomsScoped(unsigned int scope)

   Returns a list of keys corresponding to all of the currently marked atoms
   that are also in the specified scope.

.. oe:function:: GetMarkedBonds


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedBonds()

   Returns a list of keys corresponding to all of the currently marked bonds.

.. oe:function:: GetMarkedBondsScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedBondsScoped(unsigned int scope)

   Returns a list of keys corresponding to all of the currently marked bonds
   that are also in the specified scope.

.. oe:function:: GetMarkedContours


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedContours()

   Returns a list of keys corresponding to all of the currently marked contours.

.. oe:function:: GetMarkedGrids


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedGrids()

   Returns a list of keys corresponding to all of the currently marked grids.

.. oe:function:: GetMarkedMolecules


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedMolecules()

   Returns a list of keys corresponding to all of the currently marked 
   molecules.

.. oe:function:: GetMarkedMonitors


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedMonitors()

   Returns a list of keys corresponding to all of the currently marked 
   monitors.

.. oe:function:: GetMarkedSurfaces


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMarkedSurfaces()

   Returns a list of keys corresponding to all of the currently marked 
   surfaces.

.. oe:function:: GetMoleculesScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetMoleculesScoped(unsigned int scope)

   Returns a list of all the molecule keys in the specified scope.

.. oe:function:: GetScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetScoped(unsigned int scope)
      std::vector<OEPropDB::OEKey> GetScoped(unsigned int scope, unsigned int type)

   Returns a list of all the keys in the specified scope. If a *type* parameter
   is specified, it will return a list of all keys of that type in the specified 
   scope. The type parameter can be retrieved by calling the ``GetType`` method 
   on an ``OEKey`` object.

.. oe:function:: GetSelectedAtom


   .. oe:api::


      OEPropDB::OEKey GetSelectedAtom()

   Returns a key corresponding to a single selected atom. If multiple atoms are 
   currently selected, this is equivalent to returning the first entry in list
   returned by :oe:func:`GetSelectedAtoms`.

.. oe:function:: GetSelectedAtoms


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedAtoms()

   Returns a list of keys corresponding to the currently selected atoms.

.. oe:function:: GetSelectedBond


   .. oe:api::


      OEPropDB::OEKey GetSelectedBond()

   Returns a key corresponding to a single selected bond. If multiple atoms are 
   currently selected, this is equivalent to returning the first entry in list
   returned by :oe:func:`GetSelectedBonds`.

.. oe:function:: GetSelectedBonds


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedBonds()

   Returns a list of keys corresponding to the currently selected bonds.

.. oe:function:: GetSelectedContours


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedContours()

   Returns a list of keys corresponding to the currently selected contours.

.. oe:function:: GetSelectedGrids


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedGrids()

   Returns a list of keys corresponding to the currently selected grids.

.. oe:function:: GetSelectedMolecules


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedMolecules()

   Returns a list of keys corresponding to the currently selected molecules.

.. oe:function:: GetSelectedMonitors


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedMonitors()

   Returns a list of keys corresponding to the currently selected monitors.

.. oe:function:: GetSelectedSurfaces


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSelectedSurfaces()

   Returns a list of keys corresponding to the currently selected surfaces.

.. oe:function:: GetSurfacesScoped


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetSurfacesScoped(unsigned int scope)

   Returns a list of all the surface keys in the specified scope.

.. oe:function:: GetVisibleAtoms


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleAtoms()

   Returns a list of all the visible atom keys.

.. oe:function:: GetVisibleBonds


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleBonds()

   Returns a list of all the visible bond keys.

.. oe:function:: GetVisibleContours


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleContours()

   Returns a list of all the visible contour keys.

.. oe:function:: GetVisibleGrids


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleGrids()

   Returns a list of all the visible grid keys.

.. oe:function:: GetVisibleIDs


   .. oe:api::


      std::vector<unsigned int> GetVisibleIDs()

   Returns a list of all the IDs for the current set of visible objects.

.. oe:function:: GetVisibleMolecules


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleMolecules()

   Returns a list of all the visible molecule keys.

.. oe:function:: GetVisibleMonitors


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleMonitors()

   Returns a list of all the visible monitor keys.

.. oe:function:: GetVisibleSurfaces


   .. oe:api::


      std::vector<OEPropDB::OEKey> GetVisibleSurfaces()

   Returns a list of all the visible surface keys.

.. oe:function:: IDGet


   .. oe:api::


      unsigned int IDGet(const OESystem::OEBase &)

   Returns the ID associated with the specified Python object.

.. oe:function:: IDTypeGet


   .. oe:api::


      std::string IDTypeGet(unsigned int)

   Returns the name of the object type associated with the specified ID.


.. oe:function:: IsActive


   .. oe:api::


      bool IsActive(const OEPropDB::OEKey &k)
      bool IsActive(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional 
   conformer index) is active/focused.

.. oe:function:: IsLocked


   .. oe:api::


      bool IsLocked(const OEPropDB::OEKey &k)
      bool IsLocked(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is locked.

.. oe:function:: IsMarked


   .. oe:api::


      bool IsMarked(const OEPropDB::OEKey &k)
      bool IsMarked(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is marked.

.. oe:function:: IsSelected


   .. oe:api::


      bool IsSelected(const OEPropDB::OEKey &k)
      bool IsSelected(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is selected.

.. oe:function:: IsTrulyVisible


   .. oe:api::


      bool IsTrulyVisible(const OEPropDB::OEKey &k)
      bool IsTrulyVisible(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is truly visible.

.. oe:function:: IsVisible


   .. oe:api::


      bool IsVisible(const OEPropDB::OEKey &k)
      bool IsVisible(unsigned int id, unsigned int conf=UINT_MAX)

   Returns whether or not the specified object (key or ID with optional
   conformer index) is visible.
   
.. oe:function:: Lock


   .. oe:api::


      void Lock(const std::string &k)
      void Lock(const OEPropDB::OEKey &k, bool state)
      void Lock(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Lock(unsigned int id, bool state, unsigned int conf=UINT_MAX)

   Sets the *locked* property on the specified object to the specified value
   (*state*). If a string value is passed to this function as opposed to an
   object specifier, the *locked* property will be set for all the objects 
   that satisfy the specified query. For more details on the query language,
   see the relevant chapter in the main VIDA manual.

.. oe:function:: LockScoped


   .. oe:api::


      void LockScoped(bool state, unsigned int scope)

   Sets the *locked* property to the specified value for all objects in the
   specified scope.


.. oe:function:: Mark


   .. oe:api::


      void Mark(const std::string &prop)
      void Mark(const OEPropDB::OEKey &k, bool state)
      void Mark(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Mark(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Mark(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                unsigned char action)

   Sets the *marked* property on the specified object to the specified value
   (*state*). If a string value is passed to this function as opposed to an
   object specifier, the *marked* property will be set for all the objects 
   that satisfy the specified query. For more details on the query language,
   see the relevant chapter in the main VIDA manual.

.. oe:function:: MarkScoped


   .. oe:api::


      void MarkScoped(bool state, unsigned int scope)

   Sets the *marked* property to the specified value for all objects in the
   specified scope.


.. oe:function:: MimicParentVisibilityGet


   .. oe:api::


      bool MimicParentVisibilityGet(const OEPropDB::OEKey &k)

   Returns whether or not the visibility of the specified object is controlled 
   by its parent's visibility.

.. oe:function:: MimicParentVisibilitySet


   .. oe:api::


      void MimicParentVisibilitySet(const OEPropDB::OEKey &k, bool mimic)
      void MimicParentVisibilitySet(const std::vector<OEPropDB::OEKey> &k, 
                                    bool mimic)

   Sets whether or not the visibility of the specified object(s) is controlled 
   by each individual's parent's visibility.

.. oe:function:: MimicParentVisibilitySetScoped


   .. oe:api::


      void MimicParentVisibilitySetScoped(const std::string &tag, bool mimic, 
                                          unsigned int scope = BestScope)

   Sets whether or not the visibility of a certain set of objects with the 
   specified scope is controlled by each individual's parent's visibility. The
   set of objects is determined by the presence or absence of the specified 
   *tag* on the molecule.
  
.. oe:function:: ScratchClear


   .. oe:api::


      void ScratchClear()

   This function clears the ScratchScope.

.. oe:function:: ScratchGet


   .. oe:api::


      std::vector<OEPropDB::OEKey> ScratchGet()

   Returns all of the keys currently in the ScratchScope.
  
.. oe:function:: ScratchInsert


   .. oe:api::


      void ScratchInsert(const OEPropDB::OEKey &)
      void ScratchInsert(const std::vector<OEPropDB::OEKey> &)

   This function adds a key to the ScratchScope.

.. oe:function:: ScratchSet


   .. oe:api::


      void ScratchSet(const std::string &prop)
      void ScratchSet(const OEPropDB::OEKey &)
      void ScratchSet(const std::vector<OEPropDB::OEKey> &)

   This function sets the contents of the ScratchScope.

.. oe:function:: Select


   .. oe:api::


      void Select(const std::string &prop)
      void Select(const OEPropDB::OEKey &k, bool state)
      void Select(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Select(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Select(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                  unsigned char action)

   This function selects objects according to the selection language.

.. oe:function:: SelectAllMolecules


   .. oe:api::


      void SelectAllMolecules()

   This function selects every molecule that is currently visible.

.. oe:function:: SelectByQuery


   .. oe:api::


      void SelectByQuery(const std::string &query, int action=0, 
                         unsigned int scope = BestScope)

   This function selects every molecule in the specified scope based on whether or 
   not it matches the specified substructure *query*. Valid query inputs include 
   SMILES, SMARTS, and IUPAC as well as common names. The IUPAC and common name to 
   structure conversion is performed by the Ogham toolkit.

.. oe:function:: SelectInvert


   .. oe:api::


      void SelectInvert()

   This function selects the currently visible, but not selected items, and deselects
   the visible and selected items.

.. oe:function:: SelectKeys


   .. oe:api::


      void SelectKeys(const std::vector<OEPropDB::OEKey> &atomsKeys)

   This function selects the objects corresponding to each of the keys specified 
   in the parameter list *keys*.


.. oe:function:: SelectOERID


   .. oe:api::


      void SelectOERID(unsigned int id, bool selected=true)

   This function sets the selected property on the object corresponding to the 
   specified *id*. The *selected* parameter specifies whether or not the object
   should either be selected or unselected.

.. oe:function:: SelectResidues


   .. oe:api::


      void SelectResidues(const std::vector<OEPropDB::OEKey> &keys, bool state)

   Set the selected state of the residues containing the specified atoms.

.. oe:function:: SelectScoped


   .. oe:api::


      void SelectScoped(bool state, unsigned int scope)

  Select or unselect (based on the *state* parameter) all the objects in the
  specified scope.


.. oe:function:: SelectWithin


   .. oe:api::


      void SelectWithin(float radius, bool selected)

   This function selects all molecule objects, including atoms and bonds,
   within the specified radius of the currently selected objects.

.. oe:function:: SelectWithout


   .. oe:api::


      void SelectWithout(float radius, bool selected)

   This function selects all molecule objects, including atoms and bonds,
   outside of the specified radii of the currently selected objects.

.. oe:function:: Subset


   .. oe:api::


      void Subset(const std::string &name, const std::string &sel)

   Creates a named subset that can be then used in the Select routine.

.. oe:function:: Visible


   .. oe:api::


      void Visible(const std::string &prop)
      void Visible(const OEPropDB::OEKey &k, bool state)
      void Visible(const std::vector<OEPropDB::OEKey> &keys, bool state)
      void Visible(unsigned int id, bool state, unsigned int conf=UINT_MAX)
      void Visible(const std::vector<OEPropDB::OEKey> &keys, bool state, 
                   unsigned char action)
      bool Visible(const std::vector<unsigned int> &ids, bool visible, 
                   unsigned int conf=UINT_MAX)

   This function sets the keys that pass the specified criteria to be visible.

.. oe:function:: VisibleScoped


   .. oe:api::


      void VisibleScoped(bool state, unsigned int scope)
   
   Sets the visibility of all the objects in the specified scope based on the
   *state* parameter.

.. oe:function:: VisualizeCommandScopeGet


   .. oe:api::


      unsigned int VisualizeCommandScopeGet()

   Reserved for future expansion.

.. oe:function:: VisualizeCommandScopeSet


   .. oe:api::


      void VisualizeCommandScopeSet(unsigned int scope)

   Reserved for future expansion.

