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