Programming Guide: Shell Plug-Ins

# Programming Guide

## Shell Plug-Ins

You can extend the capabilities of the document shell or add session-wide functionality to OpenDoc by implementing shell plug-ins. Shell plug-ins are shared libraries, rather than subclasses of ODExtension. A shell plug-in is not associated with any particular part object.

Your shell plug-in must be installed on the user's machine when a document first opens, if it is to be used with that document.

You can create shell plug-ins for any of several purposes, including these:

- To install a dispatch module or focus module that will be available to all parts in the document

- To install an object (such as a spelling checker) into a name space, allowing it to be accessed as a service by all parts in the document

- To replace parts of OpenDoc with your own capabilities, from individual objects (see "Patching OpenDoc") to entire subsystems (see "Run-Time Object Relationships")

A shell plug-in has a single exported entry point to OpenDoc: its installation function. Your plug-in library needs to implement only that function, with this interface:

    void ODShellPlugInInstall(Environment *ev,
                              ODDraft *draft
                              ODShellPlugInActionCodes *action);

The installation function must have exactly the specified name as well as the specified parameters and return value. You must ensure that the function name ODShellPluginInstall appears in your library's list of exported symbols.

The draft parameter specifies the document draft that is being opened. Use the action parameter to return a value specifying whether the document shell should maintain a connection to your shell plug-in library after the installation function completes.

The installation function must always return noErr, unless it cannot execute. For any ODShellPluginInstall function that returns an error, OpenDoc unloads its shell plug-in library.

Execution of a shell plug-in happens like this:

1. Whenever the user opens an OpenDoc document, OpenDoc launches the document shell. The document shell initializes itself and the session object, and gains access to the document's current draft.

2. The document shell then accesses each plug-in library and calls its ODShellPluginInstall function. The ODShellPluginInstall function performs the functions the plug-in is designed for: it installs custom focus modules or dispatch modules, it patches session-level objects, or it otherwise modifies shell functionality. ODShellPluginInstall then returns the appropriate OSErr value and exits.

3. After all plug-ins have executed, the root part of the OpenDoc document then opens the document window.

For OS/2, if it is to be executed, your shell plug-in file must be located in the OpenDoc Shell Plug-Ins folder on the user's system. For Windows and AIX, if it is to be executed, your shell plug-in file must be located in the path identified by the ODSHELLPLUGINS environment variable.

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