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

Chapter 5 - Embedding a Cyberdog Display Part in a Navigator

Opening a Display Part Embedded in a Navigator

When a Cyberdog item is opened, the item calls the Cyberdog part extension's OpenCyberItem method. The parameter set associated with the call to
the OpenCyberItem method may specify an opener part; the opener part may be a navigator. Your implementation of the OpenCyberItem method must support using the opener part, if it exists. For more information about opener parts, see "Cyberdog Item Opening Process" (page 71).

If you handle embedding in the part extension's OpenCyberItem method, your implementation of the OpenCyberItem method must take these actions:

• Call your part extension's SetCyberItem method to store a reference to the Cyberdog item being opened.
• Obtain a navigator part by calling the Cyberdog session's ObtainOpener method, specifying the navigator kind of opener part.
• Acquire the navigator part's Cyberdog navigator part extension.
• Embed your display part by calling the navigator part extension's GoToCyberItem method.

To embed your display part in a navigator, you must completely override the OpenCyberItem method; do not call its inherited method.

In the embedded text-viewer sample, the part extension's OpenCyberItem method calls the embedded text-viewer part's OpenCyberItem method. For information about the Cyberdog part extension's OpenCyberItem method, see "Overriding Cyberdog Part Extension Methods" (page 119). Listing 5-2 shows how the embedded text-viewer part's OpenCyberItem method performs these actions.

Listing 5-2 The OpenCyberItem method of the embedded text-viewer part

void CybTxtNavViewer::OpenCyberItem(Environment *ev, 
                           CyberItem* item, 
                           ODPart* openerPart, 
                           ParameterSet* openParams) 
{
   
   // Start the download.
   this->InitiateDownload(ev, item, openParams);
   
   // Let the extension know which Cyberdog item is being displayed.
   fCybTxtNavViewerCyberExt->SetCyberItem(ev, item, openParams);
   
   // Ensure that a parameter set is available for the call to
   // the ObtainOpener method.
   TempParameterSet acquiredParams 
                     = AcquireCreateParameterSet(ev, openParams);
   
   // Obtain a navigator kind of opener part.
   ODPart* navPart = GetCyberSession(ev)->ObtainOpener(ev, 
                                          openerPart, 
                                          kNavigatorKind,
                                          item,
                                          acquiredParams);
   
   // Tell the navigator to go to this part, which causes the part to
   // become embedded in the navigator's content area.
   TempNavigatorExtension navigatorExt(navPart,
                              kCyberNavigatorExtension);
   navigatorExt->GoToCyberItem(ev, item, GetODPart(ev), acquiredParams);
}

The call to InitiateDownload starts the download operation and sets up the progress broadcaster. For information about starting a download operation, see "Creating a Stream for Downloading" (page 135). For information about progress broadcasters, see "Using a Progress Broadcaster" (page 154).

When a Cyberdog item calls the OpenCyberItem method, it passes an opener part in the openerPart parameter, if one exists; otherwise, it passes kODNULL. If an opener part is passed in the parameter, the ObtainOpener method uses it if the part matches the specified kind of opener part.

Thus, in Listing 5-2, the call to ObtainOpener specifies creating a kNavigatorKind opener part. If this kind of part is passed when the Cyberdog item calls the OpenCyberItem method, the ObtainOpener method returns it; otherwise, the method returns a new navigator part.

Note

Even if Cyberdog calls the OpenCyberItem method with a kNavigatorKind opener part, the ObtainOpener method might return a new navigator part; for example, if the Browse in Place preferences are different. u

The ObtainOpener method requires a parameter set object to be passed in. You cannot pass kODNULL. In Listing 5-2, the AcquireCreateParameterSet method creates a parameter set object if the Cyberdog item calls the OpenCyberItem method and passes kODNULL in the openParams parameter. Listing 5-3 shows the AcquireCreateParameterSet method.

Listing 5-3 Creating a parameter set object

ParameterSet* CybTxtNavViewer::AcquireCreateParameterSet
                                    (Environment* ev, 
                                     ParameterSet* params)
{
   if (params)
   {
      params->Acquire(ev);
      return params;
   }
   else
   {
      TempParameterSet newParams = new ParameterSet;
      FailNil(newParams);
      newParams->IParameterSet(ev);
      return newParams.DontRelease();
   }
}

Listing 5-2 shows the use of objects created from C++ templates, such as TempNavigatorExtension and TempOpenerPartExtension. These templates define extensions that are based on Cyberdog classes, such as CyberNavigatorExtension and CyberOpenerPartExtension, but whose methods handle existence checks and automatically manage the release of their corresponding Cyberdog objects. Otherwise, objects created from these templates behave exactly as their corresponding Cyberdog objects behave.

IMPORTANT

These template classes are not part of the Cyberdog API. They are provided with the sample code on the Cyberdog Programming SDK "as is" for your convenience.