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.

About

void About()

Displays information about the VIDA product.

AppAddCallback

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

AppCurrentDir

std::string AppCurrentDir()

Returns the current working directory.

AppCurrentDirSet

bool AppCurrentDirSet(const std::string &name)

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

AppDir

std::string AppDir()

Returns the path of the directory where the application is installed.

AppDocDir

std::string AppDocDir()

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

AppExampleDir

std::string AppExampleDir()

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

AppInstallDir

std::string AppInstallDir()

Returns the path to the directory where VIDA is installed.

AppLastDirGet

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.

AppLastDirSet

void AppLastDirSet(const std::string &)

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

AppLastOpenDirGet

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.

AppLastOpenDirSet

void AppLastOpenDirSet(const std::string &)

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

AppLastSaveDirGet

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.

AppLastSaveDirSet

void AppLastSaveDirSet(const std::string &)

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

AppLicenseFile

std::string AppLicenseFile()

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

AppLicenseUpdate

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.

AppOpenUrl

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.

AppRemoveCallback

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

AppScriptSave

bool AppScriptSave(const std::string &fname)

Saves the current scripting history to the specified file.

AppUserDir

std::string AppUserDir()

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

AppVersion

std::string AppVersion()

Returns a string representation of the complete version number

AppVersionMajor

int AppVersionMajor()

Returns the first, or major, part of the version number as an integer

AppVersionMinor

int AppVersionMinor()

Returns the second, or minor, part of the version number as an integer

AppVersionBugFix

int AppVersionBugFix()

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

CopyData

void CopyData(const std::string &data)

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

CopyMolecules

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.

CopyMoleculesScoped

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.

Error

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.

ErrorDetailsDialog

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.

ExtensionsEdit

void ExtensionsEdit()

Launches the extensions manager.

IsLicensed

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.

JournalInit

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.

ObservableBool

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

Returns a reference to an observable boolean value.

ObservableFloat

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

Returns a reference to an observable floating point value.

ObservableInt

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

Returns a reference to an observable integer value.

ObservableKey

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

Returns a reference to an observable OEKey object.

ObservableString

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

Returns a reference to an observable string value.

ObservableUInt

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

Returns a reference to an observable unsigned integer value.

ObservableUpdate

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

Returns a reference to an observable updater.

ObservableVecFloat

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

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

ObservableVecInt

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

Returns a reference to an observable list of integer values.

ObservableVecString

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

Returns a reference to an observable list of string values.

ObservableVecUInt

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

Returns a reference an observable list of unsigned integer values.

Open

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.

OpenState

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.

PasteMolecules

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

PreferenceDump

void PreferenceDump()

This function prints out all the current preferences.

PreferenceGetBool

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

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

PreferenceGetColor

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

This function returns the current color of the given preference.

PreferenceGetDouble

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

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

PreferenceGetFloat

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

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

PreferenceGetInt

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

This function returns the integer value of the given preference.

PreferenceGetString

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

This function returns the string value of the given preference.

PreferenceGetVBool

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.

PreferenceGetVDouble

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.

PreferenceGetVFloat

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.

PreferenceGetVInt

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.

PreferenceIsBool

bool PreferenceIsBool(const std::string &pref)

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

PreferenceIsColor

bool PreferenceIsColor(const std::string &pref)

This function returns whether the given preference is a color.

PreferenceIsDouble

bool PreferenceIsDouble(const std::string &pref)

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

PreferenceIsFloat

bool PreferenceIsFloat(const std::string &pref)

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

PreferenceIsInt

bool PreferenceIsInt(const std::string &pref)

This function returns whether the given preference is an integer.

PreferenceIsSet

bool PreferenceIsSet(const std::string &pref)

This function returns whether the given preference has a value.

PreferenceIsString

bool PreferenceIsString(const std::string &pref)

This function returns whether the given preference is a string.

PreferenceIsVBool

bool PreferenceIsVBool(const std::string &pref)

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

PreferenceIsVDouble

bool PreferenceIsVDouble(const std::string &pref)

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

PreferenceIsVFloat

bool PreferenceIsVFloat(const std::string &pref)

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

PreferenceIsVInt

bool PreferenceIsVInt(const std::string &pref)

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

PreferenceMark

void PreferenceMark()

This function marks the preferences as a point for undoing.

PreferenceRemove

bool PreferenceRemove(const std::string &pref)

This function deletes a preference.

PreferenceRestore

void PreferenceRestore()

This function restores the default preferences.

PreferenceSetBool

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

This function sets the boolean value of the preference.

PreferenceSetColor

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

This function sets the color value of the preference.

PreferenceSetCommand

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

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

PreferenceSetDouble

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

This function sets double precision value of the preference.

PreferenceSetFloat

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

This function sets floating point value of the preference.

PreferenceSetInt

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

This function sets integer value of the preference.

PreferenceSetString

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

This function sets the string value of the preference.

PreferenceSetVBool

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

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

PreferenceSetVDouble

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.

PreferenceSetVFloat

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.

PreferenceSetVInt

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

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

PreferenceValidateCommands

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.

PreferencesEdit

void PreferencesEdit()

This function opens the preferences dialog.

Quit

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.

Redo

void Redo()
void Redo(unsigned int steps)

This function redoes any previously undone actions.

RedoTo

bool RedoTo(const std::string &)

Redoes all the previously undone operation up to the specified location in the undo stack.

(See UndoMark.)

Save

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.

SaveMiniState

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.

SaveState

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

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

SaveStateFilter

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.

SettingsGetBool

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

This function returns the specified boolean setting.

SettingsGetFloat

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

This function returns the specified float setting.

SettingsGetInt

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

This function returns the specified int setting.

SettingsGetString

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

This function returns the specified string setting.

SettingsRestore

void SettingsRestore()

This function returns the specified restore setting.

SettingsSetBool

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

This function sets the specified bool setting.

SettingsSetFloat

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

This function sets the specified float setting.

SettingsSetInt

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

This function sets the specified integer setting.

SettingsSetString

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

This function sets the specified string setting.

SettingsSync

void SettingsSync()

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

StateMark

int StateMark()

Reserved for internal use.

StatePop

int StatePop(bool load=True)

Reserved for internal use.

Undo

void Undo()
void Undo(unsigned int steps)

This function undoes the previous actions.

UndoHint

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.

UndoMark

bool UndoMark(const std::string &)

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

UndoTo

bool UndoTo(const std::string &)

Undoes all the previous operations up to the specified operation.

(See UndoMark.)

UpdateRedo

void UpdateRedo()

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

VFSleep

void VFSleep(unsigned int seconds)

Sleeps the application for the specified number of seconds.

ViewerExportPOVRAY

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.

ViewerScreenshot

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.

WriteHistory

void WriteHistory(const std::string &filename)

Writes the current Python interpreter history to the specified filename.