
General Functions
*****************

The functions defined in this section provide a wide variety of functionality
that is generally applicable to the VIDA application as a whole.

.. oe:function:: About


   .. oe:api::


      void About()

   Displays information about the VIDA product.

.. oe:function:: AppAddCallback


   .. oe:api::


      unsigned int AppAddCallback(changeName, callbackFunction)

   Adds a Python callback function to be called when certain changes occur 
   within the product.  The changeName parameter is a string, and can have the
   following values:

   - "ActiveChanged"
   - "DisplayChanged"
   - "LockedChanged"
   - "MarkedChanged"
   - "ObjectsAdded"
   - "ObjectsDeleted"
   - "SelectedChanged"
   - "VisibleChanged"
   - "StateReset"

   The callbackFunction parameter is the actual Python function (not a string) 
   to be called each time the specified change happens.

   The return value is an integer callback ID, which can be used to remove
   the callback later.  See :oe:func:`AppRemoveCallback`.

.. oe:function:: AppCurrentDir


   .. oe:api::


      std::string AppCurrentDir()

   Returns the current working directory.  

.. oe:function:: AppCurrentDirSet


   .. oe:api::


      bool AppCurrentDirSet(const std::string &name)

   Sets the current working directory and returns whether or not the change 
   was successful.

.. oe:function:: AppDir


   .. oe:api::


      std::string AppDir()
      
   Returns the path of the directory where the application is installed.

.. oe:function:: AppDocDir


   .. oe:api::


      std::string AppDocDir()

   Returns the path to the directory containing all of the documentation.

.. oe:function:: AppExampleDir


   .. oe:api::


      std::string AppExampleDir()

   Returns the path to the directory containing all of the examples provided 
   with the application.

.. oe:function:: AppInstallDir


   .. oe:api::


      std::string AppInstallDir()

   Returns the path to the directory where VIDA is installed.

.. oe:function:: AppLastDirGet


   .. oe:api::


      std::string AppLastDirGet()

   Returns the path to the last directory that was accessed by VIDA.
   However, if the user has the preference "Open Current Dir" specified, this
   function will return an empty string.

.. oe:function:: AppLastDirSet


   .. oe:api::


      void AppLastDirSet(const std::string &)

   Stores the path to the last directory that was accessed by VIDA.

.. oe:function:: AppLastOpenDirGet


   .. oe:api::


      std::string AppLastOpenDirGet()

   Returns the path to the last directory from which a file was opened. However,
   if the user has the preference "Open Current Dir" specified, this function 
   will return an empty string.

.. oe:function:: AppLastOpenDirSet


   .. oe:api::


      void AppLastOpenDirSet(const std::string &)

   Sets the path to the last directory from which a file was opened.

.. oe:function:: AppLastSaveDirGet


   .. oe:api::


      std::string AppLastSaveDirGet()

   Returns the path to the last directory to which a file was saved. However, if
   the user has the preference "Open Current Dir" specified, this function will
   return an empty string.

.. oe:function:: AppLastSaveDirSet


   .. oe:api::


      void AppLastSaveDirSet(const std::string &)

   Sets the path to the last directory to which a file was saved.

.. oe:function:: AppLicenseFile


   .. oe:api::


      std::string AppLicenseFile()

   Returns the path to the license file being used by VIDA.

.. oe:function:: AppLicenseUpdate


   .. oe:api::


      void AppLicenseUpdate(bool promptonly)

   Searches for a new valid license file. If ``promptonly`` is True, VIDA
   will prompt the user to specify the location of the license file. If it is
   False, VIDA will search the expected potential locations for a new
   valid license file before prompting. If a valid license file is found in one 
   of these locations, that file will be used and the user will not be prompted.

.. oe:function:: AppOpenUrl


   .. oe:api::


      void AppOpenUrl(const std::string &url)

   Opens the specified URL using the most appropriate program for the specified
   URL. For instance, web pages will be opened with the default web browser and 
   files will be opened with the program that that file type is associated.

.. oe:function:: AppRemoveCallback


   .. oe:api::


      void AppRemoveCallback(changeName, unsigned int callbackID)

   Removes a callback created using the AppAddCallback function.  The
   callbackID argument is the value returned from AppAddCallback, and the
   changeName string must be the same one that was used in the call to
   AppAddCallback.  See :oe:func:`AppAddCallback`.

.. oe:function:: AppScriptSave


   .. oe:api::


      bool AppScriptSave(const std::string &fname)

   Saves the current scripting history to the specified file.

.. oe:function:: AppUserDir


   .. oe:api::


      std::string AppUserDir()

   Returns the path of the application user directory containing the application
   preferences, settings, startup script, journal file, and license.


.. oe:function:: AppVersion


   .. oe:api::


      std::string AppVersion()

   Returns a string representation of the complete version number


.. oe:function:: AppVersionMajor


   .. oe:api::


      int AppVersionMajor()

   Returns the first, or major, part of the version number as an integer
   
   
.. oe:function:: AppVersionMinor


   .. oe:api::


      int AppVersionMinor()

   Returns the second, or minor, part of the version number as an integer
   
.. oe:function:: AppVersionBugFix


   .. oe:api::


      int AppVersionBugFix()

   Returns the third, or bug fix, part of the version number as an integer

.. oe:function:: CopyData


   .. oe:api::


      void CopyData(const std::string &data)

   Copies the specified data onto the system clipboard where it can be pasted
   into other applications.

.. oe:function:: CopyMolecules


   .. oe:api::


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

   Copies the specified molecules onto the system clipboard where they can be 
   pasted into other applications in a variety of formats.

.. oe:function:: CopyMoleculesScoped


   .. oe:api::


      void CopyMoleculesScoped(unsigned int scope = BestScope)

   Copies all of the molecules in the specified scope onto the system clipboard
   where they can be pasted into other applications in a variety of formats.

.. oe:function:: Error


   .. oe:api::


      void Error(const std::string &err)

   Raises an exception when called from within a script, otherwise, it reports
   the specified error message to the status bar.

.. oe:function:: ErrorDetailsDialog


   .. oe:api::


      void ErrorDetailsDialog(const std::string &title, const std::string &message, 
                              const std::string &error)

   Launches an error dialog that contain detailed information about the error 
   that occurred.

.. oe:function:: ExtensionsEdit


   .. oe:api::


      void ExtensionsEdit()

   Launches the extensions manager.

.. oe:function:: IsLicensed


   .. oe:api::


      bool IsLicensed(const std::string &toolkit)

   Returns whether or not a valid license exists for the specified toolkit. If
   a valid license is present, that toolkit can be accessed from Python in 
   VIDA. If a valid license is not present, importing that toolkit in
   Python will fail and throw an exception.

.. oe:function:: JournalInit


   .. oe:api::


      void JournalInit(bool force)

   For internal use only. This function specifies the script as a "Journal
   Script" which forces the application to clear its current state and run the
   script starting from a clean state.


.. oe:function:: ObservableBool


   .. oe:api::


      BoolObservable &ObservableBool(const std::string &name, bool create=False)

   Returns a reference to an observable boolean value.

.. oe:function:: ObservableFloat


   .. oe:api::


      FloatObservable &ObservableFloat(const std::string &name, bool create=False)

   Returns a reference to an observable floating point value.

.. oe:function:: ObservableInt


   .. oe:api::


      IntObservable &ObservableInt(const std::string &name, bool create=False)

   Returns a reference to an observable integer value.

.. oe:function:: ObservableKey


   .. oe:api::


      KeyObservable &ObservableKey(const std::string &name, bool create=False)

   Returns a reference to an observable OEKey object.

.. oe:function:: ObservableString


   .. oe:api::


      StringObservable &ObservableString(const std::string &name, bool create=False)

   Returns a reference to an observable string value.

.. oe:function:: ObservableUInt


   .. oe:api::


      UIntObservable &ObservableUInt(const std::string &name, bool create=False)

   Returns a reference to an observable unsigned integer value.

.. oe:function:: ObservableUpdate


   .. oe:api::


      UpdateObservable &ObservableUpdate(const std::string &name, bool create=False)

   Returns a reference to an observable updater.

.. oe:function:: ObservableVecFloat


   .. oe:api::


      FloatVectorObservable &ObservableVecFloat(const std::string &name, 
                                                bool create=False)

   Returns a reference to an observable list of floating point values.

.. oe:function:: ObservableVecInt


   .. oe:api::


      IntVectorObservable &ObservableVecInt(const std::string &name, 
                                            bool create=False)

   Returns a reference to an observable list of integer values.

.. oe:function:: ObservableVecString


   .. oe:api::


      StringVectorObservable &ObservableVecString(const std::string &name, 
                                                  bool create=False)

   Returns a reference to an observable list of string values.

.. oe:function:: ObservableVecUInt


   .. oe:api::


      UIntVectorObservable &ObservableVecUInt(const std::string &name, 
                                              bool create=False)

   Returns a reference an observable list of unsigned integer values.

.. oe:function:: Open


   .. oe:api::


      std::vector<unsigned int> Open(const std::string &filename, 
                                     const std::string &type="")
      std::vector<unsigned int> Open(const std::vector<std::string> &filenames, 
                                     const std::string &type="")

   This function opens the specified file or files. The optional type parameter is the
   file extension to assume for this file.

.. oe:function:: OpenState


   .. oe:api::


      void OpenState(const std::string &filename)

   This function opens the specified state file.  This action will clear the current
   session, including deleting all the loaded molecules.

.. oe:function:: PasteMolecules


   .. oe:api::


      void PasteMolecules()
      void PasteMolecules(const std::vector<std::string> &, 
                          const std::string &format)

   Pastes all of the molecules that can be found in the system clipboard into
   the application. Pasted molecules will appear in a new list called "Pasted".


.. oe:function:: PreferenceDump


   .. oe:api::


      void PreferenceDump()

   This function prints out all the current preferences.

.. oe:function:: PreferenceGetBool


   .. oe:api::


      bool PreferenceGetBool(const std::string &pref, bool def=False)

   This function returns the current boolean value of the given preference.

.. oe:function:: PreferenceGetColor


   .. oe:api::


      OESystem::OEColor PreferenceGetColor(const std::string &pref, 
                                           const OESystem::OEColor &def=OESystem::OEWhite)

   This function returns the current color of the given preference.

.. oe:function:: PreferenceGetDouble


   .. oe:api::


      double PreferenceGetDouble(const std::string &pref, double def=0.0)

   This function returns the double precision number (non-integral) value of the given preference.

.. oe:function:: PreferenceGetFloat


   .. oe:api::


      float PreferenceGetFloat(const std::string &pref, float def=0.0f)

   This function returns the floating point (non-integral) value of the given preference.

.. oe:function:: PreferenceGetInt


   .. oe:api::


      int PreferenceGetInt(const std::string &pref, int def=0)

   This function returns the integer value of the given preference.

.. oe:function:: PreferenceGetString


   .. oe:api::


      std::string PreferenceGetString(const std::string &pref, 
                                      const std::string &def="")

   This function returns the string value of the given preference.

.. oe:function:: PreferenceGetVBool


   .. oe:api::


      std::vector<bool> PreferenceGetVBool(const std::string &pref, 
                                           const std::vector<bool> &v=std::vector<bool>())

   This function returns the vector of boolean values for the given preference.

.. oe:function:: PreferenceGetVDouble


   .. oe:api::


      std::vector<double> PreferenceGetVDouble(const std::string &pref, 
                                               const std::vector<double> &v=std::vector<double>())

   This function returns the vector of double precision values for the given preference.

.. oe:function:: PreferenceGetVFloat


   .. oe:api::


      std::vector<float> PreferenceGetVFloat(const std::string &pref, 
                                             const std::vector<float> &v=std::vector<float>())

   This function returns the vector of floating point values for the given preference.

.. oe:function:: PreferenceGetVInt


   .. oe:api::


      std::vector<int> PreferenceGetVInt(const std::string &pref, 
                                         const std::vector<int> &v=std::vector<int>())

   This function returns the vector of integer values for the given preference.

.. oe:function:: PreferenceIsBool


   .. oe:api::


      bool PreferenceIsBool(const std::string &pref)

   This function returns whether the given preference is a boolean preference.

.. oe:function:: PreferenceIsColor


   .. oe:api::


      bool PreferenceIsColor(const std::string &pref)

   This function returns whether the given preference is a color.

.. oe:function:: PreferenceIsDouble


   .. oe:api::


      bool PreferenceIsDouble(const std::string &pref)

   This function returns whether the given preference is a double precision number.

.. oe:function:: PreferenceIsFloat


   .. oe:api::


      bool PreferenceIsFloat(const std::string &pref)

   This function returns whether the given preference is a floating point number.

.. oe:function:: PreferenceIsInt


   .. oe:api::


      bool PreferenceIsInt(const std::string &pref)

   This function returns whether the given preference is an integer.

.. oe:function:: PreferenceIsSet


   .. oe:api::


      bool PreferenceIsSet(const std::string &pref)

   This function returns whether the given preference has a value.

.. oe:function:: PreferenceIsString


   .. oe:api::


      bool PreferenceIsString(const std::string &pref)

   This function returns whether the given preference is a string.

.. oe:function:: PreferenceIsVBool


   .. oe:api::


      bool PreferenceIsVBool(const std::string &pref)

   This function returns whether the given preference is a list of booleans.

.. oe:function:: PreferenceIsVDouble


   .. oe:api::


      bool PreferenceIsVDouble(const std::string &pref)

   This function returns whether the given preference is a list of double precision numbers.

.. oe:function:: PreferenceIsVFloat


   .. oe:api::


      bool PreferenceIsVFloat(const std::string &pref)

   This function returns whether the given preference is a list of floating point numbers.

.. oe:function:: PreferenceIsVInt


   .. oe:api::


      bool PreferenceIsVInt(const std::string &pref)

   This function returns whether the given preference is a list of floating point numbers.

.. oe:function:: PreferenceMark


   .. oe:api::


      void PreferenceMark()

   This function marks the preferences as a point for undoing.

.. oe:function:: PreferenceRemove


   .. oe:api::


      bool PreferenceRemove(const std::string &pref)

   This function deletes a preference.

.. oe:function:: PreferenceRestore


   .. oe:api::


      void PreferenceRestore()

   This function restores the default preferences.

.. oe:function:: PreferenceSetBool


   .. oe:api::


      bool PreferenceSetBool(const std::string &pref, bool v)

   This function sets the boolean value of the preference.

.. oe:function:: PreferenceSetColor


   .. oe:api::


      bool PreferenceSetColor(const std::string &pref, const OESystem::OEColor &v)

   This function sets the color value of the preference.

.. oe:function:: PreferenceSetCommand


   .. oe:api::


      bool PreferenceSetCommand(const std::string &pref, const std::string &cmd)

   This function sets the command to activate the changes in the preference.

.. oe:function:: PreferenceSetDouble


   .. oe:api::


      bool PreferenceSetDouble(const std::string &pref, double v)

   This function sets double precision value of the preference.

.. oe:function:: PreferenceSetFloat


   .. oe:api::


      bool PreferenceSetFloat(const std::string &pref, float v)

   This function sets floating point value of the preference.

.. oe:function:: PreferenceSetInt


   .. oe:api::


      bool PreferenceSetInt(const std::string &pref, int v)

   This function sets integer value of the preference.

.. oe:function:: PreferenceSetString


   .. oe:api::


      bool PreferenceSetString(const std::string &pref, const std::string &v)

   This function sets the string value of the preference.

.. oe:function:: PreferenceSetVBool


   .. oe:api::


      bool PreferenceSetVBool(const std::string &pref, const std::vector<bool> &v)

   This function sets value of the preference to the passed list of booleans.

.. oe:function:: PreferenceSetVDouble


   .. oe:api::


      bool PreferenceSetVDouble(const std::string &pref, 
                                const std::vector<double> &v)

   This function sets value of the preference to the passed list of double precision numbers.

.. oe:function:: PreferenceSetVFloat


   .. oe:api::


      bool PreferenceSetVFloat(const std::string &pref, 
                               const std::vector<float> &v)

   This function sets value of the preference to the passed list of floating point numbers.

.. oe:function:: PreferenceSetVInt


   .. oe:api::


      bool PreferenceSetVInt(const std::string &pref, const std::vector<int> &v)

   This function sets value of the preference to the passed list of integers.

.. oe:function:: PreferenceValidateCommands


   .. oe:api::


      std::string PreferenceValidateCommands()

   This function checks all the commands for the preferences to ensure that they
   all exist.  It returns a list of Preference commands that could not be found.

.. oe:function:: PreferencesEdit


   .. oe:api::


      void PreferencesEdit()

   This function opens the preferences dialog.

.. oe:function:: Quit


   .. oe:api::


      void Quit(bool force=False)
      void quit(bool force=False)

   Exits the application. If *force* is set to ``False``, the user will be 
   prompted before actually exiting.

.. oe:function:: Redo


   .. oe:api::


      void Redo()
      void Redo(unsigned int steps)

   This function redoes any previously undone actions.

.. oe:function:: RedoTo


   .. oe:api::


      bool RedoTo(const std::string &)

   Redoes all the previously undone operation up to the specified location in 
   the undo stack.
   
   (See :oe:func:`UndoMark`.)

.. oe:function:: Save


   .. oe:api::


      void Save(const std::string &filename, const std::vector<unsigned int> &ids)
      void Save(const std::string &filename, 
                const std::vector<OEPropDB::OEKey> &keys)

   This function saves the passed IDs or OEKeys to a file with the given filename.

.. oe:function:: SaveMiniState


   .. oe:api::


      void SaveMiniState(const std::string &filename, const std::string &version="")

   This function saves the current application state as a "mini state" to the
   specified file.

.. oe:function:: SaveState


   .. oe:api::


      void SaveState(const std::string &filename, const std::string &version="")

   This function saves the current application state to the specified file.

.. oe:function:: SaveStateFilter


   .. oe:api::


      void SaveStateFilter(const std::string &filename, const std::string &filter)

   This function saves the state of the application to the specified file in the 
   state file format determined by the specified *filter*.


.. oe:function:: SettingsGetBool


   .. oe:api::


      bool SettingsGetBool(const std::string &s, bool def=False)

   This function returns the specified boolean setting.

.. oe:function:: SettingsGetFloat


   .. oe:api::


      float SettingsGetFloat(const std::string &s, float def=0.0f)

   This function returns the specified float setting.

.. oe:function:: SettingsGetInt


   .. oe:api::


      int SettingsGetInt(const std::string &s, int def=0)

   This function returns the specified int setting.

.. oe:function:: SettingsGetString


   .. oe:api::


      std::string SettingsGetString(const std::string &s, const std::string &def="")

   This function returns the specified string setting.

.. oe:function:: SettingsRestore


   .. oe:api::


      void SettingsRestore()

   This function returns the specified restore setting.

.. oe:function:: SettingsSetBool


   .. oe:api::


      bool SettingsSetBool(const std::string &s, bool v)

   This function sets the specified bool setting.

.. oe:function:: SettingsSetFloat


   .. oe:api::


      bool SettingsSetFloat(const std::string &s, float v)

   This function sets the specified float setting.

.. oe:function:: SettingsSetInt


   .. oe:api::


      bool SettingsSetInt(const std::string &s, int v)

   This function sets the specified integer setting.

.. oe:function:: SettingsSetString


   .. oe:api::


      bool SettingsSetString(const std::string &s, const std::string &v)

   This function sets the specified string setting.

.. oe:function:: SettingsSync


   .. oe:api::


      void SettingsSync()

   This function synchronizes the application settings with those stored on disk.
   Ordinarily this function should not need to be called.

.. oe:function:: StateMark


   .. oe:api::


      int StateMark()

   Reserved for internal use.

.. oe:function:: StatePop


   .. oe:api::


      int StatePop(bool load=True)

   Reserved for internal use.

.. oe:function:: Undo


   .. oe:api::


      void Undo()
      void Undo(unsigned int steps)

   This function undoes the previous actions.

.. oe:function:: UndoHint


   .. oe:api::


      void UndoHint(const std::string &action, bool replace=True)

   This function is used to name the current undo action. Ordinarily this function
   should not need to be called by the user.

.. oe:function:: UndoMark


   .. oe:api::


      bool UndoMark(const std::string &)

   Sets a name for the current position in the undo stack which can be used
   later by the :oe:func:`UndoTo` function.

.. oe:function:: UndoTo


   .. oe:api::


      bool UndoTo(const std::string &)

   Undoes all the previous operations up to the specified operation.
   
   (See :oe:func:`UndoMark`.)

.. oe:function:: UpdateRedo


   .. oe:api::


      void UpdateRedo()

   This function updates the redo menu. Ordinarily this function
   should not need to be called by the user.

.. oe:function:: VFSleep


   .. oe:api::


      void VFSleep(unsigned int seconds)

   Sleeps the application for the specified number of seconds.

.. oe:function:: ViewerExportPOVRAY


   .. oe:api::


      void ViewerExportPOVRAY(const std::string &fname)

   This function exports the current scene in the 3D display to a POV-Ray input
   file. The resulting file can be used as input to the POV-Ray raytracing program
   to generate very high quality static 3D images.

.. oe:function:: ViewerScreenshot


   .. oe:api::


      void ViewerScreenshot(const std::string &fname)
      void ViewerScreenshot(const std::string &fname, unsigned int width, 
                            unsigned int height)

   This function saves a screenshot of the 3D display window to the specified
   file (*fname*) in PNG format.


.. oe:function:: WriteHistory


   .. oe:api::


      void WriteHistory(const std::string &filename)

   Writes the current Python interpreter history to the specified filename.

