Edit

COleDocObjectItem Class

  • Article

Implements Active document containment.

Syntax

class COleDocObjectItem : public COleClientItem

Members

Public Constructors

Name Description
COleDocObjectItem::COleDocObjectItem Constructs a COleDocObject item.

Public Methods

Name Description
COleDocObjectItem::DoDefaultPrinting Prints the container application's document using the default printer settings.
COleDocObjectItem::ExecCommand Executes the command specified by the user.
COleDocObjectItem::GetActiveView Retrieves the document's active view.
COleDocObjectItem::GetPageCount Retrieves the number of pages in the container application's document.
COleDocObjectItem::OnPreparePrinting Prepares the container application's document for printing.
COleDocObjectItem::OnPrint Prints the container application's document.
COleDocObjectItem::QueryCommand Queries for the status of one or more commands generated by user interface events.
COleDocObjectItem::Release Releases the connection to an OLE linked item and closes it if it was open. Does not destroy the client item.

Remarks

In MFC, an Active document is handled similarly to a regular, in-place editable embedding, with the following differences:

  • The COleDocument-derived class still maintains a list of the currently embedded items; however, these items may be COleDocObjectItem-derived items.

  • When an active document is active, it occupies the entire client area of the view when it is in-place active.

  • An Active document container has full control of the Help menu.

  • The Help menu contains menu items for both the Active document container and server.

Because the Active document container owns the Help menu, the container is responsible for forwarding server Help menu messages to the server. This integration is handled by COleDocObjectItem.

For more information on menu merging and Active document activation, see Overview of Active Document Containment.

Inheritance Hierarchy

CObject

CCmdTarget

CDocItem

COleClientItem

COleDocObjectItem

Requirements

Header: afxole.h

COleDocObjectItem::COleDocObjectItem

Call this member function to initialize the COleDocObjectItem object.

COleDocObjectItem(COleDocument* pContainerDoc = NULL);

Parameters

pContainerDoc
A pointer to the COleDocument object acting as the active document container. This parameter must be NULL to enable IMPLEMENT_SERIALIZE. Normally OLE items are constructed with a non- NULL document pointer.

COleDocObjectItem::DoDefaultPrinting

Called by the framework to a document using the default settings.

static HRESULT DoDefaultPrinting(
    CView* pCaller,
    CPrintInfo* pInfo);

Parameters

pCaller
A pointer to a CView object that is sending the print command.

pInfo
A pointer to a CPrintInfo object that describes the job to be printed.

COleDocObjectItem::ExecCommand

Call this member function to execute the command specified by the user.

HRESULT ExecCommand(
    DWORD nCmdID,
    DWORD nCmdExecOpt = OLECMDEXECOPT_DONTPROMPTUSER,
    const GUID* pguidCmdGroup = NULL);

Parameters

nCmdID
The identifier of the command to execute. Must be in the group identified by pguidCmdGroup.

nCmdExecOpt
Specifies command-execution options. By default, set to execute the command without prompting the user. See OLECMDEXECOPT for a list of values.

pguidCmdGroup
Unique identifier of the command group. By default, NULL, which specifies the standard group. The command passed in nCmdID must belong to the group.

Return Value

Returns S_OK if successful; otherwise,returns one of the following error codes.

Value Description
E_UNEXPECTED Unexpected error occurred.
E_FAIL Error occurred.
E_NOTIMPL Indicates MFC itself should attempt to translate and dispatch the command.
OLECMDERR_E_UNKNOWNGROUP pguidCmdGroup is non- NULL but does not specify a recognized command group.
OLECMDERR_E_NOTSUPPORTED nCmdID is not recognized as a valid command in the group pGroup.
OLECMDERR_DISABLED The command identified by nCmdID is disabled and cannot be executed.
OLECMDERR_NOHELP Caller asked for help on the command identified by nCmdID but no help is available.
OLECMDERR_CANCELLED User canceled the execution.

Remarks

The pguidCmdGroup and the nCmdID parameters together uniquely identify the command to invoke. The nCmdExecOpt parameter specifies the exact action to take.

COleDocObjectItem::GetActiveView

Call this member function to get a pointer to the IOleDocumentView interface of the currently active view.

LPOLEDOCUMENTVIEW GetActiveView() const;

Return Value

A pointer to the IOleDocumentView interface of the currently active view. If there is no current view, it returns NULL.

Remarks

The reference count on the returned IOleDocumentView pointer is not incremented before it is returned by this function.

COleDocObjectItem::GetPageCount

Call this member function to retrieve the number of pages in the document.

BOOL GetPageCount(
    LPLONG pnFirstPage,
    LPLONG pcPages);

Parameters

pnFirstPage
A pointer to the number of the document's first page. Can be NULL, which indicates the caller doesn't need this number.

pcPages
A pointer to the total number of pages in the document. Can be NULL, which indicates the caller doesn't need this number.

Return Value

Nonzero if successful; otherwise 0.

COleDocObjectItem::OnPreparePrinting

This member function is called by the framework to prepare a document for printing.

static BOOL OnPreparePrinting(
    CView* pCaller,
    CPrintInfo* pInfo,
    BOOL bPrintAll = TRUE);

Parameters

pCaller
A pointer to a CView object that is sending the print command.

pInfo
A pointer to a CPrintInfo object that describes the job to be printed.

bPrintAll
Specifies whether the entire document is to be printed.

Return Value

Nonzero if successful; otherwise 0.

COleDocObjectItem::OnPrint

This member function is called by the framework to print a document.

static void OnPrint(
    CView* pCaller,
    CPrintInfo* pInfo,
    BOOL bPrintAll = TRUE);

Parameters

pCaller
A pointer to a CView object that is sending the print command.

pInfo
A pointer to a CPrintInfo object that describes the job to be printed.

bPrintAll
Specifies whether the entire document is to be printed.

COleDocObjectItem::QueryCommand

Queries for the status of one or more commands generated by user interface events.

HRESULT QueryCommand(
    ULONG nCmdID,
    DWORD* pdwStatus,
    OLECMDTEXT* pCmdText =NULL,
    const GUID* pguidCmdGroup =NULL);

Parameters

nCmdID
identifier of the command being queried for.

pdwStatus
A pointer to the flags returned as a result of the query. For a list of possible values, see OLECMDF.

pCmdText
Pointer to an OLECMDTEXT structure in which to return name and status information for a single command. Can be NULL to indicate that the caller does not need this information.

pguidCmdGroup
Unique identifier of the command group; can be NULL to specify the standard group.

Return Value

For a complete listing of return values, see IOleCommandTarget::QueryStatus in the Windows SDK.

Remarks

This member function emulates the functionality of the IOleCommandTarget::QueryStatus method, as described in the Windows SDK.

COleDocObjectItem::Release

Releases the connection to an OLE linked item and closes it if it was open. Does not destroy the client item.

virtual void Release(OLECLOSE dwCloseOption = OLECLOSE_NOSAVE);

Parameters

dwCloseOption
Flag specifying under what circumstances the OLE item is saved when it returns to the loaded state. For a list of possible values, see COleClientItem::Close.

Remarks

Does not destroy the client item.

See also

MFC Sample MFCBIND
COleClientItem Class
Hierarchy Chart
COleClientItem Class
CDocObjectServerItem Class