COleDocument Class
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
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.
COleDocument::OnEditLinks
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for