__________

SOMPRT.TXT
__________


BUILDING OPENDOC PARTS AS SOM OBJECTS
_____________________________________

The OpenDoc package provides support for building parts as C++ objects.
This file describes how to build SOM based parts and still use the C++
OpenDoc classes.  A sample part, SSmpPrt, is provided that is functionally
equivalent to the SimplePart.  The following diagram shows the the new
SOM class hierarchy.

    OD_Object
        
         RefCntObject
                
                 PersistentObject
                        
                         OD_Part
                                
                                 SSmpPrt (or any part you want to build)


HOW IT WORKS
____________

It is fairly simple to take the XMPPart object and convert it over to
be a SOM class.  The problem is that XMPPart is built on a hierarchy
of classes starting with XMPObject and a SOM class cannot inherit from
a C++ class.  Also the SOM-based part must act like a C++ based part.
Therefore a class heirarchy was built with SOM classes (as shown above)
and a proxy part was created in C++ which passes all its functions over
to the "real" SOM based part.  The following diagram shows how function
calls are routed between the proxy and the SOM part.


                 C++ Classes                        SOM Classes

              Ŀ               Ŀ
                                      Calls                      
               XMPObject           OD_Object        
                                                                 
                             
                                                         
                                                         
              Ŀ               Ŀ
                                      Calls                      
               RefCntObject        RefCntObject     
                                                                 
                             
                                                         
                                                         
              Ŀ               Ŀ
                                      Calls                      
               PersistentObject    PersistentObject 
                                                                 
                             
                                                         
                                                         
              Ŀ               Ŀ
                                                                 
               XMPPart                          OD_Part          
                                                                 
                             
                                                         
                                                         
              Ŀ               Ŀ
   Calls                             Calls                       
    SOMPart(proxy)      SSmpPrt          
                                                                 
                             


The proxy part implements every function defined for XMPPart, plus
it overrides every function of its ancestors (XMPPersistentObject,
XMPRefCntObject and XMPObject).  Therefore every function call on the
proxy part (except for constructors and destructors) is passed to the
SOM objects.  There are still things that must be done in the base
classes on the C++ side (such as incrementing and decrementing the
RefCount, and so forth), so the base classes in the SOM hierarchy
actually call the C++ base class functions.  This means that if you
are implementing a part as a SOM class you have the same opportunity
to override and/or explicitly call base class functions as someone who
is using C++.  This complexity will disappaear when the entire OpenDoc
object hierarchy is built on SOM.

The SOMPart(proxy) has been built for you and its DLL is already in
the BIN directory.  The base classes for the SOM parts (OD_Object,
RefCntObject, PersistentObject, and OD_Part) have been built into one
DLL named OD_PART.DLL which is also in the BIN directory.  OD_PART.DLL
has a LIB in the LIB directory which must be used when you link your
part.


HOW TO CREATE A PART AS A SOM OBJECT
____________________________________

PREREQUISITES
-------------

  You must have the SOMObjects Toolkit installed (with the appropriate
  PATHs set up), and you must run SOMXH.CMD to create the .XH headers
  for a C++ compile.

WRITING A PART
--------------
As you can see by the documentation above and by looking a the sample
code, the part handlers that you build are "real" OpenDoc parts and
they are "real" SOM objects.  Therefore, you can program your part as
you would any other SOM object.  If you are going to create auxillary
classes you can use either SOM or C++.  As indicated above, when you
want to override or explicitly call a parent function, you do it as
you normally do in SOM.

NOTE: The member functions you call on any other OpenDoc object are
      C++ functions and do not use the Environment parameter.  The
      member functions that you call on your "self" are actually SOM
      functions and they do require an Environment parameter.

Even though SOM supports C as well as C++ you will not be able to use
a C compiler because you have to interface with all the rest of
OpenDoc which is C++ based.


BUILDING
--------
The makefile for the SSmpPrt (SOM SimplePart) in the PARTS\SOMPRT
directory shows how to build a SOM based part.  Notice that you have
two additional INCLUDE paths:  one for SOM, and one for the OD_Part
hierarchy.  The import library for OD_PART.DLL (OD_PART.LIB) is in
the LIB directory.


RUNNING
-------
In order to get your part loaded and running, you must add a line to
the PARTS.DAT file in the BIN directory.  The line consists of two
strings separated by blanks just like you would do for a C++ based
part.  The difference is that the first string has three pieces for a
SOM based part.  The line below is the one used for the SOM Simple
Part.

SOM:SSmpPrt,SSimplePart  Simple Part (SOM)

1. The first four character MUST be SOM: and SOM must be all caps.
2. Immediately after the colon (no spaces) put the name of the DLL
   for your part followed by a comma (again no spaces).  In this
   example it is SSmpPrt.
3. Immediately after the comma (no spaces) put the name of the SOM
   class for your part, then put a space to delimit this string from
   the label that goes in the menu.

__________________________________________________________________________

END OF SOMPRT.TXT
__________________________________________________________________________
