-
Tobias Schmidt authoredTobias Schmidt authored
Editors
The structure, topology and connectivity of :class:`entities <EntityHandle>` is edited via editors. This includes operations such as changing atom positions, connecting atoms with bonds as well as adding and removing chains, residues and atoms. There are two flavors of editors, one for the internal coordinate system (:class:`ICSEditor`) and one for the external coordinate system (:class:`XCSEditor`).
Edit Modes
Editors support two modes: An unbuffered edit mode and a buffered edit mode. In the unbuffered edit mode, dependent information such as the spatial organizer and the internal coordinate system (in case of the XCSEditor) are updated after every change. In buffered edit mode, the updates are delayed until one of the following happens:
- The last editor goes out of scope.
- :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` is called explicitly.
The editors follow the RIAA (resource allocation is initialization) principle: Whenever an editor is requested an internal reference counter is incremented. In the destructor, this reference count is decremented. When the count drops to zero, the dependent information is updated.
In Python, one can not rely on the destructors being called. It is advised to always put a call to :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` when the editing is finished. Alternatively, starting from Python version 2.6, one can use the with statement to make sure the destructor are called and the dependent information is updated.