Convert the CDocument Class to the COleServerDoc Class

The CDocument class implements standard document behavior in a stand-alone application. When the application runs as an OLE in-place editing server, however, the document must do extra work on behalf of OLE. The framework implements the bulk of this OLE document support in class COleServerDoc. The remaining work you have to do is:

• Change the base class of CScribbleDoc from CDocument to COleServerDoc.
  
  
• Implement the document’s support for embedded items.

Suggested Reading

• ClassView: Overview, Visual C++ User’s Guide
  
  
• ClassView Topics, Visual C++ Programmer’s Guide
  
  
• Reading the FileView and ClassView Panes, Visual C++ User’s Guide
  
  
• HIERSVR, Visual C++ Samples
  
  
• COleServerDoc Overview, Microsoft Foundation Class Reference

To change the base class of CScribbleDoc

1. Use ClassView to jump to the declaration for class CScribbleDoc and change:

   class CScribbleDoc : public CDocument
   

   to:

   class CScribbleDoc : public COleServerDoc
   

2. Use FileView to open ScribbleDoc.cpp and replace all instances of CDocument with COleServerDoc.

   This changes the base class reference of CScribbleDoc from CDocument to COleServerDoc.

The COleServerItem object represents the Scribble document when the document is embedded in a container. To create a COleServerItem for a given document, AppWizard provides an override of GetEmbeddedItem in the COleServerDoc-derived class. The return type of OnGetEmbeddedItem is a pointer to a COleServerItem.

Note   A COleServerItem object can also represent an OLE link item, but Scribble doesn’t illustrate that. The sample HIERSVR illustrates this link item.

In the following procedure, you’ll fill in some of the code that AppWizard would have generated had you originally chosen the Full-server option.

To implement the document’s support for embedded items

1. Using FileView, switch to ScribbleDoc.h in the editor and add the following forward class reference for CScribbleItem immediately before the line class CScribbleDoc : public COleServerDoc:

   class CScribbleItem;
   

2. In ScribbleDoc.cpp, add the following #include statement immediately after the line #include "scribbleDoc.h":

   #include "ScribbleItem.h" 
   

   Note   The short filename for this header file is ScribItm.h. If you’re starting from the sample source files from Scribble Step 6 to complete this tutorial step, you must use this short filename. Otherwise, you will not be able to compile your project.

   Now you’ll add the OnGetEmbeddedItem function override. (AppWizard provided this code in the Scratch version of Scribble you generated with Full-server support.)

3. In ClassView, right-click the CScribbleDoc class icon.
   
   
4. From the menu, click Add Member Function.
   
   
5. In the Function Type box, type: COleServerItem*.
   
   
6. In the Function Declaration box, type: OnGetEmbeddedItem().
   
   
7. In the Access group box, click Protected.
   
   
8. Click the Virtual check box, (note that this adds the virtual keyword to the declaration) and click OK.
   
   
9. In ScribbleDoc.cpp, implement the function as follows:

   // OnGetEmbeddedItem is called by the framework to get the COleServerItem
   //  that is associated with the document.  It is only called when necessary.
   
   CScribbleItem* pItem = new CScribbleItem(this);
   ASSERT_VALID(pItem);
   return pItem;
   

10. Switch back to ScribbleDoc.h and, in the Public Attributes section, add the following code:

    CScribbleItem* GetEmbeddedItem()
    { return (CScribbleItem*)COleServerDoc::GetEmbeddedItem(); }
    

    Note   AppWizard provided this code in the \Scratch\Scribble project, but you must insert it manually in the Scribble project.

    This code provides a type-safe function to return a pointer to the specific COleServerItem-derived class, CScribbleItem.