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