Programming Reference: OpenDoc and SOMObjects

# Programming Reference

## OpenDoc and SOMObjects

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

### IDL Prototypes

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:

- In IDL method declarations, each parameter declaration is preceded by a directional attribute (in, out, or inout) that notes whether the parameter is used as an input, an output, or both.

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

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.

### SOM Development

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.

### Platform Dependency

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.

### Conventions Used in Method and Function Descriptions

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:

Input | A value specified by the programmer, but not modified by the method or function. If the parameter is a pointer to a value, neither the pointer nor the information it points to changes.
Output | A parameter that receives the output. If the value represents a pointer, the pointer remains the same, but the information it points to changes.
In/Out | A value provided as input to the method and whose content is changed upon return. If the parameter is a pointer to a value, the pointer remains the same, but the information it points to changes.

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:

- guidelines for specifying parameters
- instructions about the order in which to use the method with related methods or the function with related functions
- when you might want to use one method or function for another

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.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]