| title | ms.custom | ms.date | ms.reviewer | ms.suite | ms.technology | ms.tgt_pltfrm | ms.topic | f1_keywords | dev_langs | helpviewer_keywords | ms.assetid | caps.latest.revision | author | ms.author | manager | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
COleDocument Class | Microsoft Docs |
11/04/2016 |
|
reference |
|
|
|
dc2ecb99-03e1-44c7-bb69-48056dd1b672 |
23 |
mikeblome |
mblome |
ghogen |
The base class for OLE documents that support visual editing.
class COleDocument : public CDocument
| Name | Description |
|---|---|
| COleDocument::COleDocument | Constructs a COleDocument object. |
| 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. |
| 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. |
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..
COleDocument
Header: afxole.h
Call this function to add an item to the document.
virtual void AddItem(CDocItem* pItem);
pItem
Pointer to the document item being added.
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.
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);
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.
Nonzero if the function was successful; otherwise 0.
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.
Constructs a COleDocument object.
COleDocument();
Call this function if you want to store the document using the compound-file format.
void EnableCompoundFile(BOOL bEnable = TRUE);
bEnable
Specifies whether compound file support is enabled or disabled.
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.
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);
pWnd
Pointer to the window that displays the container document.
A pointer to the single, in-place active OLE item; NULL if there is no OLE item currently in the "in-place active" state.
Call this function repeatedly to access each of the client items in your document.
COleClientItem* GetNextClientItem(POSITION& pos) const;
pos
A reference to a POSITION value set by a previous call to GetNextClientItem; the initial value is returned by the GetStartPosition member function.
A pointer to the next client item in the document, or NULL if there are no more client items.
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.
[!code-cppNVC_MFCOleContainer#1]
Call this function repeatedly to access each of the items in your document.
virtual CDocItem* GetNextItem(POSITION& pos) const;
pos
A reference to a POSITION value set by a previous call to GetNextItem; the initial value is returned by the GetStartPosition member function.
A pointer to the document item at the specified position.
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.
[!code-cppNVC_MFCOleContainer#2]
Call this function repeatedly to access each of the server items in your document.
COleServerItem* GetNextServerItem(POSITION& pos) const;
pos
A reference to a POSITION value set by a previous call to GetNextServerItem; the initial value is returned by the GetStartPosition member function.
A pointer to the next server item in the document, or NULL if there are no more server items.
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.
[!code-cppNVC_MFCOleServer#2]
Called by the framework to retrieve the currently selected OLE item in the specified view.
virtual COleClientItem* GetPrimarySelectedItem(CView* pView);
pView
Pointer to the active view object displaying the document.
A pointer to the single, selected OLE item; NULL if no OLE items are selected or if more than one is selected.
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.
Call this function to get the position of the first item in the document.
virtual POSITION GetStartPosition() const;
A POSITION value that can be used to begin iterating through the document's items; NULL if the document has no items.
Pass the value returned to GetNextItem, GetNextClientItem, or GetNextServerItem.
Call this function to determine whether the document contains any blank items.
BOOL HasBlankItems() const;
Nonzero if the document contains any blank items; otherwise 0.
A blank item is one whose rectangle is empty.
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();
OnEditChangeIcon creates and launches a COleChangeIconDialog Change Icon dialog box.
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();
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();
OnEditLinks creates and launches a COleLinksDialog Links dialog box that allows the user to change the linked objects.
Sends a message via the resident mail host (if any) with the document as an attachment.
afx_msg void OnFileSendMail();
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..
The framework calls this function after the document's visibility state changes.
virtual void OnShowViews(BOOL bVisible);
bVisible
Indicates whether the document has become visible or invisible.
The default version of this function does nothing. Override it if your application must perform any special processing when the document's visibility changes.
Called by the framework to update the Change Icon command on the Edit menu.
afx_msg void OnUpdateEditChangeIcon(CCmdUI* pCmdUI);
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.
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.
Called by the framework to update the Links command on the Edit menu.
afx_msg void OnUpdateEditLinksMenu(CCmdUI* pCmdUI);
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.
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.
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);
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.
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.
Called by the framework to determine whether a linked OLE item can be pasted from the Clipboard.
afx_msg void OnUpdatePasteLinkMenu(CCmdUI* pCmdUI);
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.
The Paste Special menu command is enabled or disabled depending on whether the item can be pasted into the document or not.
Called by the framework to determine whether an embedded OLE item can be pasted from the Clipboard.
afx_msg void OnUpdatePasteMenu(CCmdUI* pCmdUI);
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.
The Paste menu command and button are enabled or disabled depending on whether the item can be pasted into the document or not.
Call this function to remove an item from the document.
virtual void RemoveItem(CDocItem* pItem);
pItem
Pointer to the document item to be removed.
You typically do not need to call this function explicitly; it is called by the destructors for COleClientItem and COleServerItem.
Call this function to mark the document as modified if any of the contained OLE items have been modified.
virtual void UpdateModifiedFlag();
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.
MFC Sample CONTAINER
MFC Sample MFCBIND
CDocument Class
Hierarchy Chart