CCP4 Coordinate Library Project

Object interface: General Remarks

The Object interface represents a library of C++ classes, which match closely the General scheme. The data exchange in Object interface may therefore be represented as:

for retrieval -
locating the instance of needed class in the coordinate hierarchy and reading its data from public fields or through public functions
for storing -
either 1) creating the instance of needed class and placing it on the proper place in the coordinate hierarchy, or 2) rewriting public data fields (or protected data fields through the class' public functions) in the instance of needed class that is already present in the hierarchy.
In most cases, these and many other functions (e.g. reading/writing the coordinate files, selection of atoms etc.) are provided by a special class called Manager, which excuses the application programmer of surfing the coordinate hierarchy and (most important) of direct changing it. Ideally, all communication with the hierarchy should go through the Manager; in practice, however, the Manager often provides a pointer to a class with fields opened for public access (e.g. atom class CAtom).

It should be emphasized here that all public data fields are Ok to read, but they are not always Ok to change, unless there is a clear understanding of what is being done. Therefore many public data fields are to be changed only through the corresponding class' functions. This is mentioned wherever necessary. Although such fields should have been declared as protected, they are left public in order to avoid overhead of function calls at reading. This manual does not aim on exchaustive description of the Library's inside, therefore it should be kept in mind that relations between the most innocent data fields in classes may be not as trivial as they seem to be. Breaking such relations in a dynamically linked hierarchy will, as a normal, cause crash.

This manual does not describe all data fields and functions of classes (not even all public functions and fields) and far not all the classes, which are in the Library. The application developer is expected to keep along the following simple rule: if something is not documented, it must not be used. Undocumented classes, functions and fields are only for internal Library functioning, and some of them were temporary left public only because the Library is being developed.

Knowing the following will help to understand some pieces of code and write applications which comply by data types with the Library:
  1. Source file relations: any *.cpp file has a corresponding header file *.h. The opposite is not always correct. Therefore in this manual we refer only to header files, assuming that implementational part of them, if there is any, may be easily located.

  2. Class and structure name conventions
    • class names always start with capital "C", for example CMMDBManager, CChain, CResidue
    • similarly, structure names always start with capital "S"
    • pointers on classes and structures are formed with prefix "P", for example PCChain, PCResidue
    • references to classes and structures are formed with prefix "R", for example RCChain, RCResidue
    • for each class and structure, the Library automatically provides type of the corresponding class, its pointer, reference, pointer on pointer and reference of pointer. For example, definition of class CChain is accompanied by definition of types PCChain, RCChain, PPCChain and RPCChain.

  3. Type definitions
    • all used mathematical types, which are not part of standard C and C++, are defined in file mattype_.h
    • all types, which are specific to coordinate context, are defined in file mmdb_defs.h
    • it is strongly advised to use realtype instead of float or double float types in applications.

  4. File input/output: all file operations in the Library are done through the class CFile (found in file file_.h). There is no requirement for application to use it instead of standard means. However, if application derives classes from those of Library, it must assure compliency with Library on input/output of classes. The only way to do that implies using the class CFile for input/output operations within each derived class. More details about this are found in File operations on Library's classes.



Back to index