OpenDoc objects follow the System Object Model (SOM), an object-oriented programming technology for building class libraries that support object binding at run time.
The interface to SOM classes must be written in the CORBA Interface Definition Language (IDL), a programming-language-neutral syntax for creating interfaces. The interfaces are compiled separately from the implementations of the classes by the SOMObjects IDL compiler, which supports object-oriented programming languages, such as C++, and procedural programming languages, such as C.
Because OpenDoc uses SOMObjects and IDL, part editors and other OpenDoc classes that have been created with different compilers or in different programming languages can nevertheless communicate properly with one another. Furthermore, they can be independently revised and extended and still work together. Method prototypes in the IDL syntax is similar to that of C and C++.
Method prototypes in the IDL syntax is similar to that of C and C++. IDL includes essentially the same character set, white space rules, comment styles, preprocessing capabilities, identifier-naming rules, and rules for literals. But there are a few notable differences in source-code appearance when declaring or calling methods of SOM-based objects:
As an example of IDL syntax, here is the prototype for the AcquireFrame method of the ODDraft class:
ODFrame AcquireFrame (in ODStorageUnitID id);
The directional attribute in indicates that the id parameter is only passed into the method.
The SOMObjects IDL compiler converts IDL declarations into declarations and stub definitions in the selected implementation language. It adds any necessary parameters and converts out and inout parameters appropriately for the selected language. For example, out parameters may be implemented as pointers.
All OpenDoc objects are SOM objects, descended from the class SOMObject. Your subclass of ODPart must likewise be a SOM class. If you want the other classes you define to be SOM classes, then you must write your interfaces in IDL, separate from your implementations. You must compile your interfaces with the SOMObjects IDL compiler, which can produce header files and stub implementation source files in the various programming languages supported by the SOMObjects IDL compiler. Options to the compiler specify which files to produce. You complete your development by writing your implementations into the stub implementation files and compiling them, along with the header files, using a standard compiler for your programming language.
For a more detailed description of the Interface Definition Language and instructions on programming with SOM, see the SOMObject Developer Toolkit Users Guide.
OpenDoc is a cross-platform technology, and most of its concepts and features are platform-independent. Throughout this book, any method, function, macro, type, or constant that is specific to a platform is called out as such. This way, you can get a general idea of how platform-specific your code must be, and therefore, how simple or complex it can be to convert to another platform.
The following list explains the purpose of each item on a reference page.
Heading | The heading shows the method or function name. Each heading is preceded by a rule. | ||||||
Description | The description follows the heading and provides a brief purpose. It also identifies options and requirements for calling the method or function. | ||||||
Signature | The section describes the language-calling signature of the method or function. Generally, methods are in C++ and function are in C. | ||||||
Parameters | This section lists each parameter passed by the method or function and provides its data type, parameter type, and a brief description. All parameters must be specified. All data types are written in uppercase and lowercase to match the header files. Generally, a data type of "Pxxxxxx" implicitly defines a pointer to the data type "xxxxxx." The terms kODNULL and kODNULLID applied to a parameter indicates the presence of a parameter that has no value. There are three parameter types:
The C++ interface to any method of a SOM object includes an extra initial parameter, the environment parameter (ev), used by all SOM methods to pass exceptions. See the chapter on OpenDoc runtime features in the OpenDoc Programming Guide for information on SOM exception handling. The C interface to any SOM method includes another extra parameter (somSelf) before the environment parameter, specifying the object to which the method call is directed. For example, the signature of the ODPart::CanvasUpdated method in the SOM language is as follows: void CanvasUpdated (ODPart *somSelf, Environment *ev, ODCanvas *canvas);If you are using the C++ language, the signature is as follows: void CanvasUpdated (Environment *ev, ODCanvas *canvas); | ||||||
Returns | This section includes a list of possible return codes or values. | ||||||
Remarks | This section contains additional information about the method or function such as:
| ||||||
Exception Handling | This section describes the exceptions or error codes. The exception handling section is not shown if there are no exceptions. | ||||||
Override Policy | This section describes whether the method can be overridden. For more information, see "Override Information". | ||||||
Related Methods | This list shows other methods, if any, defined in this document that are related to this method. | ||||||
Example Code | This section provides a programming example of how to use the method or function in an application program. The example uses valid and realistic values for parameters. |