Edit

Share via

COleDocument Class

  • Article

The base class for OLE documents that support visual editing.

Syntax

class COleDocument : public CDocument

Members

Public Constructors

Name Description
COleDocument::COleDocument Constructs a COleDocument object.

Public Methods

Name Description
COleDocument::AddItem Adds an item to the list of items maintained by the document.
COleDocument::ApplyPrintDevice Sets the print-target device for all client items in the document.
COleDocument::EnableCompoundFile Causes documents to be stored using the OLE Structured Storage file format.
COleDocument::GetInPlaceActiveItem Returns the OLE item that is currently in-place active.
COleDocument::GetNextClientItem Gets the next client item for iterating.
COleDocument::GetNextItem Gets the next document item for iterating.
COleDocument::GetNextServerItem Gets the next server item for iterating.
COleDocument::GetPrimarySelectedItem Returns the primary selected OLE item in the document.
COleDocument::GetStartPosition Gets the initial position to begin iteration.
COleDocument::HasBlankItems Checks for blank items in the document.
COleDocument::OnShowViews Called when the document becomes visible or invisible.
COleDocument::RemoveItem Removes an item from the list of items maintained by the document.
COleDocument::UpdateModifiedFlag Marks the document as modified if any of the contained OLE items have been modified.

Protected Methods

Name Description
COleDocument::OnEditChangeIcon Handles events in the Change Icon menu command.
COleDocument::OnEditConvert Handles the conversion of an embedded or linked object from one type to another.
COleDocument::OnEditLinks Handles events in the Links command on the Edit menu.
COleDocument::OnFileSendMail Sends a mail message with the document attached.
COleDocument::OnUpdateEditChangeIcon Called by the framework to update the command UI for the Edit/Change Icon menu option.
COleDocument::OnUpdateEditLinksMenu Called by the framework to update the command UI for the Edit/Links menu option.
COleDocument::OnUpdateObjectVerbMenu Called by the framework to update the command UI for the Edit/ ObjectName menu option and the Verb submenu accessed from Edit/ ObjectName.
COleDocument::OnUpdatePasteLinkMenu Called by the framework to update the command UI for the Paste Special menu option.
COleDocument::OnUpdatePasteMenu Called by the framework to update the command UI for the Paste menu option.

Remarks

COleDocument is derived from CDocument, which allows your OLE applications to use the document/view architecture provided by the Microsoft Foundation Class Library.

COleDocument treats a document as a collection of CDocItem objects to handle OLE items. Both container and server applications require such an architecture because their documents must be able to contain OLE items. The COleServerItem and COleClientItem classes, both derived from CDocItem, manage the interactions between applications and OLE items.

If you are writing a simple container application, derive your document class from COleDocument. If you are writing a container application that supports linking to the embedded items contained by its documents, derive your document class from COleLinkingDoc. If you are writing a server application or combination container/server, derive your document class from COleServerDoc. COleLinkingDoc and COleServerDoc are derived from COleDocument, so these classes inherit all the services available in COleDocument and CDocument.

To use COleDocument, derive a class from it and add functionality to manage the application's non-OLE data as well as embedded or linked items. If you define CDocItem-derived classes to store the application's native data, you can use the default implementation defined by COleDocument to store both your OLE and non-OLE data. You can also design your own data structures for storing your non-OLE data separately from the OLE items. For more information, see the article Containers: Compound Files..

CDocument supports sending your document via mail if mail support (MAPI) is present. COleDocument has updated OnFileSendMail to handle compound documents correctly. For more information, see the articles MAPI and MAPI Support in MFC..

Inheritance Hierarchy

CObject

CCmdTarget

CDocument

COleDocument

Requirements

Header: afxole.h

COleDocument::AddItem

Call this function to add an item to the document.

virtual void AddItem(CDocItem* pItem);

Parameters

pItem
Pointer to the document item being added.

Remarks

You do not need to call this function explicitly when it is called by the COleClientItem or COleServerItem constructor that accepts a pointer to a document.

COleDocument::ApplyPrintDevice

Call this function to change the print-target device for all embedded COleClientItem items in your application's container document.

BOOL ApplyPrintDevice(const DVTARGETDEVICE* ptd);
BOOL ApplyPrintDevice(const PRINTDLG* ppd);

Parameters

ptd
Pointer to a DVTARGETDEVICE data structure, which contains information about the new print-target device. Can be NULL.

ppd
Pointer to a PRINTDLG data structure, which contains information about the new print-target device. Can be NULL.

Return Value

Nonzero if the function was successful; otherwise 0.

Remarks

This function updates the print-target device for all items but does not refresh the presentation cache for those items. To update the presentation cache for an item, call COleClientItem::UpdateLink.

The arguments to this function contain information that OLE uses to identify the target device. The PRINTDLG structure contains information that Windows uses to initialize the common Print dialog box. After the user closes the dialog box, Windows returns information about the user's selections in this structure. The m_pd member of a CPrintDialog object is a PRINTDLG structure.

For more information, see the PRINTDLG structure in the Windows SDK.

For more information, see the DVTARGETDEVICE structure in the Windows SDK.

COleDocument::COleDocument

Constructs a COleDocument object.

COleDocument();

COleDocument::EnableCompoundFile

Call this function if you want to store the document using the compound-file format.

void EnableCompoundFile(BOOL bEnable = TRUE);

Parameters

bEnable
Specifies whether compound file support is enabled or disabled.

Remarks

This is also called structured storage. You typically call this function from the constructor of your COleDocument-derived class. For more information about compound documents, see the article Containers: Compound Files..

If you do not call this member function, documents will be stored in a nonstructured ("flat") file format.

After compound file support is enabled or disabled for a document, the setting should not be changed during the document's lifetime.

COleDocument::GetInPlaceActiveItem

Call this function to get the OLE item that is currently activated in place in the frame window containing the view identified by pWnd.

virtual COleClientItem* GetInPlaceActiveItem(CWnd* pWnd);

Parameters

pWnd
Pointer to the window that displays the container document.

Return Value

A pointer to the single, in-place active OLE item; NULL if there is no OLE item currently in the "in-place active" state.

COleDocument::GetNextClientItem

Call this function repeatedly to access each of the client items in your document.

COleClientItem* GetNextClientItem(POSITION& pos) const;

Parameters

pos
A reference to a POSITION value set by a previous call to GetNextClientItem; the initial value is returned by the GetStartPosition member function.

Return Value

A pointer to the next client item in the document, or NULL if there are no more client items.

Remarks

After each call, the value of pos is set for the next item in the document, which might or might not be a client item.

Example

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
COleClientItem* pItem;
CString strType;
while ((pItem = pDoc->GetNextClientItem(pos)) != NULL)
{
   // Use pItem
   pItem->GetUserType(USERCLASSTYPE_FULL, strType);
   TRACE(strType);
}

COleDocument::GetNextItem

Call this function repeatedly to access each of the items in your document.

virtual CDocItem* GetNextItem(POSITION& pos) const;

Parameters

pos
A reference to a POSITION value set by a previous call to GetNextItem; the initial value is returned by the GetStartPosition member function.

Return Value

A pointer to the document item at the specified position.

Remarks

After each call, the value of pos is set to the POSITION value of the next item in the document. If the retrieved element is the last element in the document, the new value of pos is NULL.

Example

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
CDocItem* pItem;
CString strType;
while (pos != NULL)
{
   pItem = pDoc->GetNextItem(pos);
   // Use pItem
   if (pItem->IsKindOf(RUNTIME_CLASS(COleClientItem)))
   {
      ((COleClientItem*)pItem)->GetUserType(USERCLASSTYPE_FULL, strType);
      TRACE(strType);
   }
}

COleDocument::GetNextServerItem

Call this function repeatedly to access each of the server items in your document.

COleServerItem* GetNextServerItem(POSITION& pos) const;

Parameters

pos
A reference to a POSITION value set by a previous call to GetNextServerItem; the initial value is returned by the GetStartPosition member function.

Return Value

A pointer to the next server item in the document, or NULL if there are no more server items.

Remarks

After each call, the value of pos is set for the next item in the document, which might or might not be a server item.

Example

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
COleServerItem* pItem;
while ((pItem = pDoc->GetNextServerItem(pos)) != NULL)
{
   // Use pItem
}

COleDocument::GetPrimarySelectedItem

Called by the framework to retrieve the currently selected OLE item in the specified view.

virtual COleClientItem* GetPrimarySelectedItem(CView* pView);

Parameters

pView
Pointer to the active view object displaying the document.

Return Value

A pointer to the single, selected OLE item; NULL if no OLE items are selected or if more than one is selected.

Remarks

The default implementation searches the list of contained OLE items for a single selected item and returns a pointer to it. If there is no item selected, or if there is more than one item selected, the function returns NULL. You must override the CView::IsSelected member function in your view class for this function to work. Override this function if you have your own method of storing contained OLE items.

COleDocument::GetStartPosition

Call this function to get the position of the first item in the document.

virtual POSITION GetStartPosition() const;

Return Value

A POSITION value that can be used to begin iterating through the document's items; NULL if the document has no items.

Remarks

Pass the value returned to GetNextItem, GetNextClientItem, or GetNextServerItem.

COleDocument::HasBlankItems

Call this function to determine whether the document contains any blank items.

BOOL HasBlankItems() const;

Return Value

Nonzero if the document contains any blank items; otherwise 0.

Remarks

A blank item is one whose rectangle is empty.

COleDocument::OnEditChangeIcon

Displays the OLE Change Icon dialog box and changes the icon representing the currently selected OLE item to the icon the user selects in the dialog box.

afx_msg void OnEditChangeIcon();

Remarks

OnEditChangeIcon creates and launches a COleChangeIconDialog Change Icon dialog box.

COleDocument::OnEditConvert

Displays the OLE Convert dialog box and converts or activates the currently selected OLE item according to user selections in the dialog box.

afx_msg void OnEditConvert();

Remarks

OnEditConvert creates and launches a COleConvertDialog Convert dialog box.

An example of conversion is converting a Microsoft Word document into a WordPad document.

Displays the OLE Edit/Links dialog box.

afx_msg void OnEditLinks();

Remarks

OnEditLinks creates and launches a COleLinksDialog Links dialog box that allows the user to change the linked objects.

COleDocument::OnFileSendMail

Sends a message via the resident mail host (if any) with the document as an attachment.

afx_msg void OnFileSendMail();

Remarks

OnFileSendMail calls OnSaveDocument to serialize (save) untitled and modified documents to a temporary file, which is then sent via electronic mail. If the document has not been modified, a temporary file is not needed; the original is sent. OnFileSendMail loads MAPI32.DLL if it has not already been loaded.

Unlike the implementation of OnFileSendMail for CDocument, this function handles compound files correctly.

For more information, see the MAPI Topics and MAPI Support in MFC articles..

COleDocument::OnShowViews

The framework calls this function after the document's visibility state changes.

virtual void OnShowViews(BOOL bVisible);

Parameters

bVisible
Indicates whether the document has become visible or invisible.

Remarks

The default version of this function does nothing. Override it if your application must perform any special processing when the document's visibility changes.

COleDocument::OnUpdateEditChangeIcon

Called by the framework to update the Change Icon command on the Edit menu.

afx_msg void OnUpdateEditChangeIcon(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to a CCmdUI structure that represents the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI structure through pCmdUI to update the user interface.

Remarks

OnUpdateEditChangeIcon updates the command's user interface depending on whether or not a valid icon exists in the document. Override this function to change the behavior.

COleDocument::OnUpdateEditLinksMenu

Called by the framework to update the Links command on the Edit menu.

afx_msg void OnUpdateEditLinksMenu(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to a CCmdUI structure that represents the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI structure through pCmdUI to update the user interface.

Remarks

Starting with the first OLE item in the document, OnUpdateEditLinksMenu accesses each item, tests whether the item is a link, and, if it is a link, enables the Links command. Override this function to change the behavior.

COleDocument::OnUpdateObjectVerbMenu

Called by the framework to update the ObjectName command on the Edit menu and the Verb submenu accessed from the ObjectName command, where ObjectName is the name of the OLE object embedded in the document.

afx_msg void OnUpdateObjectVerbMenu(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to a CCmdUI structure that represents the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI structure through pCmdUI to update the user interface.

Remarks

OnUpdateObjectVerbMenu updates the ObjectName command's user interface depending on whether or not a valid object exists in the document. If an object exists, the ObjectName command on the Edit menu is enabled. When this menu command is selected, the Verb submenu is displayed. The Verb submenu contains all the verb commands available for the object, such as Edit, Properties, and so on. Override this function to change the behavior.

COleDocument::OnUpdatePasteLinkMenu

Called by the framework to determine whether a linked OLE item can be pasted from the Clipboard.

afx_msg void OnUpdatePasteLinkMenu(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to a CCmdUI structure that represents the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI structure through pCmdUI to update the user interface.

Remarks

The Paste Special menu command is enabled or disabled depending on whether the item can be pasted into the document or not.

COleDocument::OnUpdatePasteMenu

Called by the framework to determine whether an embedded OLE item can be pasted from the Clipboard.

afx_msg void OnUpdatePasteMenu(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to a CCmdUI structure that represents the menu that generated the update command. The update handler calls the Enable member function of the CCmdUI structure through pCmdUI to update the user interface.

Remarks

The Paste menu command and button are enabled or disabled depending on whether the item can be pasted into the document or not.

COleDocument::RemoveItem

Call this function to remove an item from the document.

virtual void RemoveItem(CDocItem* pItem);

Parameters

pItem
Pointer to the document item to be removed.

Remarks

You typically do not need to call this function explicitly; it is called by the destructors for COleClientItem and COleServerItem.

COleDocument::UpdateModifiedFlag

Call this function to mark the document as modified if any of the contained OLE items have been modified.

virtual void UpdateModifiedFlag();

Remarks

This allows the framework to prompt the user to save the document before closing, even if the native data in the document has not been modified.

See also

MFC Sample CONTAINER
MFC Sample MFCBIND
CDocument Class
Hierarchy Chart