Inside Macintosh: Cyberdog Programmer's Kit / Part 2 - Programming in Cyberdog

Chapter 4 - Creating a Cyberdog Display Part

Implementing Your Cyberdog Part Extension

A Cyberdog display part is associated with a Cyberdog part extension. An extension is an OpenDoc object that provides additional capabilities or behaviors. The Cyberdog part extension allows Cyberdog to send messages to your display part. This extension defines methods that implement Cyberdog behaviors, such as opening the location represented by a Cyberdog item.

You create a Cyberdog part extension subclass from the CyberPartExtension class. The CyberPartExtension class is an indirect subclass of the ODExtension OpenDoc class. The CyberPartExtension class is a SOM class. The following sections show you how to define a CyberPartExtension subclass and override its methods.

To implement a Cyberdog part extension, you typically take these actions:

• Override the somInit method if you use additional fields.
• Override the OpenCyberItem method to open your display part in the way you specify. Cyberdog calls this method to notify a part that it is being opened by a Cyberdog item rather than some other way, such as being restored from disk.
• Override the GetCyberItemWindow method if you want your display part's window to be selected when the same Cyberdog item is redisplayed. Cyberdog calls this method to locate a window that is already displaying the Cyberdog item. For example, if the user double clicks on a Cyberdog item in the notebook and then repeats the action, your override of the GetCyberItemWindow method can return the window in which the item is currently displayed. If you do not override this method, the item appears in a new window each time it is displayed.

You may also wish to provide a way for your SOM part extension object to obtain a reference to the C++ display part object, which is a technique used in the text-viewer example.

Listing 4-1 shows the SOM class definition of the text-viewer's part extension subclass.

Listing 4-1 The text-viewer sample's part extension class definition

module Apple {
   interface som_CybTxtViewerCyberExt : CyberPartExtension
   {
      void     SetBasePart(in somToken basePart);
      somToken GetBasePart(); 
       
   #ifdef __SOMIDL__
      implementation
      {
      functionprefix = som_CybTxtViewerCyberExt__;
   
      override:
         somInit,
         OpenCyberItem,
         GetCyberItemWindow,
         BaseRemoved;
         
      releaseorder:
         SetBasePart,
         GetBasePart;
         
      majorversion = 1; minorversion = 0;
   
   #ifdef __PRIVATE__
      somToken fBasePart;
   #endif
      };
   #endif
   };
};

The BaseRemoved, SetBasePart, and GetBasePart methods and the fBasePart field are used to associate a SOM part extension object with a C++ display part object, as described in the following section.

Associating a Part Extension With a Display Part

You may find it convenient to implement the tasks performed by SOM-class methods in methods of a C++ class. For example, the text-viewer uses a straightforward technique to associate a Cyberdog part extension subclass, which is a SOM class, with the C++ implementation of a Cyberdog display part class, CybTxtViewer. The CybTxtViewer C++ class implements the text-viewer part's behavior.

The SOM class contains a field, fBasePart, which points to the associated C++ object. The SOM class provides the SetBasePart and GetBasePart methods, which respectively set and retrieve the value of this field. The text-viewer part calls the extension's SetBasePart method when it creates the part extension object to associate the C++ display part object with the extension. See Listing 4-13 (page 128).

Listing 4-2 shows an override of the somInit method, which initializes the fBasePart field to kODNULL. Note that the somInit method's inherited method is also invoked.

Listing 4-2 The somInit method of the text-viewer's part extension

SOM_Scope void  SOMLINK som_CybTxtViewerCyberExt__somInit
                        (Apple_som_CybTxtViewerCyberExt *somSelf)
{
   ... 
   Apple_som_CybTxtViewerCyberExt_parent_CyberPartExtension_somInit
                                             (somSelf);
   somThis->fBasePart = kODNULL;
}

The SetBasePart method sets the fBasePart field with the contents of the basePart parameter, as follows:

somThis->fBasePart = basePart;

The GetBasePart method retrieves the contents of the fBasePart field:

return somThis->fBasePart;

The extension class overrides the ODExtension::BaseRemoved method to reset the fBasePart field to kODNULL when the associated C++ object no longer exists, as shown in Listing 4-3. The inherited BaseRemoved method is then called.

Listing 4-3 The BaseRemoved method of the text-viewer's part extension

SOM_Scope void  SOMLINK som_CybTxtViewerCyberExt__BaseRemoved
                        (Apple_som_CybTxtViewerCyberExt *somSelf, 
                         Environment *ev)
{
...
SOM_TRY
   somThis->fBasePart = kODNULL;
   Apple_som_CybTxtViewerCyberExt_parent_CyberPartExtension_BaseRemoved
                                             (somSelf,ev);
SOM_CATCH_ALL
SOM_ENDTRY
}

Overriding Cyberdog Part Extension Methods

To implement a Cyberdog part extension class, you typically override the OpenCyberItem method. You must override the somInit method if you define fields. See Listing 4-2 (page 118). You override the GetCyberItemWindow method if you want your display part's window to be selected when the same Cyberdog item is redisplayed.

In the text-viewer example, the methods defined in the SOM part extension subclass pass control to the corresponding methods in the C++ text-viewer part class. Listing 4-4 shows an override of the OpenCyberItem method that calls its inherited OpenCyberItem method and then calls the text-viewer part's OpenCyberItem method.

Listing 4-4 The OpenCyberItem method of the text-viewer's part extension

SOM_Scope void  SOMLINK som_CybTxtViewerCyberExt__OpenCyberItem(
                        Apple_som_CybTxtViewerCyberExt *somSelf,
                        Environment *ev,
                        CyberItem* item,
                        ODPart* openerPart,
                        ParameterSet* openParams)
{
... 
SOM_TRY
Apple_som_CybTxtViewerCyberExt_parent_CyberPartExtension_OpenCyberItem
                        (somSelf,ev,item,openerPart,openParams);
   CybTxtViewer* realPart = (CybTxtViewer*) somThis->fBasePart;
   if (realPart)
      realPart->OpenCyberItem(ev, item, openerPart, openParams);
SOM_CATCH_ALL
SOM_ENDTRY
}

Listing 4-5 shows an override of the GetCyberItemWindow method that calls the text-viewer part's GetCyberItemWindow method.

Listing 4-5 The GetCyberItemWindow method of the part extension

SOM_Scope ODWindow*  SOMLINK som_CybTxtViewerCyberExt__GetCyberItemWindow
      (Apple_som_CybTxtViewerCyberExt *somSelf, 
       Environment *ev,
       CyberItem* item)
{
   ...
   ODWindow* result; 
   ODVolatile(result);
   
   SOM_TRY
      CybTxtViewer* realPart = (CybTxtViewer*) somThis->fBasePart;
      if (realPart)
          return realPart->GetCyberItemWindow(ev, item);
   SOM_CATCH_ALL
       result = kODNULL;
   SOM_ENDTRY
   return result;
}