CDocObjectServer Class

Implements the additional OLE interfaces needed to make a normal COleDocument server into a full DocObject server: IOleDocument, IOleDocumentView, IOleCommandTarget, and IPrint.

Syntax

class CDocObjectServer : public CCmdTarget

Members

Public Constructors

Public Methods

Protected Methods

Remarks

CDocObjectServer is derived from CCmdTarget and works closely with COleServerDoc to expose the interfaces.

A DocObject server document can contain CDocObjectServerItem objects, which represent the server interface to DocObject items.

To customize your DocObject server, derive your own class from CDocObjectServer and override its view setup functions, OnActivateView, OnApplyViewState, and OnSaveViewState. You will need to provide a new instance of your class in response to framework calls.

For further information on DocObjects, see CDocObjectServerItem and COleCmdUI in the MFC Reference.

Inheritance Hierarchy

CObject

CCmdTarget

CDocObjectServer

Requirements

Header: afxdocob.h

CDocObjectServer::ActivateDocObject

Call this function to activate (but not show) the document object server.

void ActivateDocObject();

Remarks

ActivateDocObject calls IOleDocumentSite's ActivateMe method, but does not show the view because it waits for specific instructions on how to set up and display the view, given in the call to CDocObjectServer::OnActivateView.

Together, ActivateDocObject and OnActivateView activate and display the DocObject view. DocObject activation differs from other kinds of OLE in-place activation. DocObject activation bypasses displaying in-place hatch borders and object adornments (such as sizing handles), ignores object extent functions, and draws scroll bars within the view rectangle as opposed to drawing them outside that rectangle (as in normal in-place activation).

CDocObjectServer::CDocObjectServer

Constructs and initializes a CDocObjectServer object.

explicit CDocObjectServer(
    COleServerDoc* pOwner,
    LPOLEDOCUMENTSITE pDocSite = NULL);

Parameters

pOwner
A pointer to the client site document that is the client for the DocObject server.

pDocSite
A pointer to the IOleDocumentSite interface implemented by the container.

Remarks

When a DocObject is active, the client site OLE interface ( IOleDocumentSite) is what allows the DocObject server to communicate with its client (the container). When a DocObject server is activated, it first checks that the container implements the IOleDocumentSite interface. If so, COleServerDoc::GetDocObjectServer is called to see if the container supports DocObjects. By default, GetDocObjectServer returns NULL. You must override COleServerDoc::GetDocObjectServer to construct a new CDocObjectServer object or a derived object of your own, with pointers to the COleServerDoc container and its IOleDocumentSite interface as arguments to the constructor.

CDocObjectServer::OnActivateView

Call this function to display the DocObject view.

virtual HRESULT OnActivateView();

Return Value

Returns an error or warning value. By default, returns NOERROR if successful; otherwise, E_FAIL.

Remarks

This function creates an in-place frame window, draws scrollbars within the view, sets up the menus the server shares with its container, adds frame controls, sets the active object, then finally shows the in-place frame window and sets the focus.

CDocObjectServer::OnApplyViewState

Override this function to restore the state of the DocObject view.

virtual void OnApplyViewState(CArchive& ar);

Parameters

ar
A CArchive object from which to serialize the view state.

Remarks

This function is called when the view is being displayed for the first time after its instantiation. OnApplyViewState instructs a view to reinitialize itself according to the data in the CArchive object previously saved with OnSaveViewState. The view must validate the data in the CArchive object because the container does not attempt to interpret the view state data in any way.

You can use OnSaveViewState to store persistent information specific to your view's state. If you override OnSaveViewState to store information, you will want to override OnApplyViewState to read that information and apply it to your view when it is newly activated.

CDocObjectServer::OnSaveViewState

Override this function to save extra state information about your DocObject view.

virtual void OnSaveViewState(CArchive& ar);

Parameters

ar
A CArchive object to which the view state is serialized.

Remarks

Your state might include properties like the view type, zoom factor, insertion and selection point, and so on. The container typically calls this function before deactivating the view. The saved state can later be restored through OnApplyViewState.

You can use OnSaveViewState to store persistent information specific to your view's state. If you override OnSaveViewState to store information, you will want to override OnApplyViewState to read that information and apply it to your view when it is newly activated.

See also

CCmdTarget Class
Hierarchy Chart
CDocObjectServerItem Class