COleInsertDialog Class

Used for the OLE Insert Object dialog box.

Syntax

class COleInsertDialog : public COleDialog

Members

Public Constructors

Public Methods

Public Data Members

Remarks

Create an object of class COleInsertDialog when you want to call this dialog box. After a COleInsertDialog object has been constructed, you can use the m_io structure to initialize the values or states of controls in the dialog box. The m_io structure is of type OLEUIINSERTOBJECT. For more information about using this dialog class, see the DoModal member function.

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

For more information regarding OLE-specific dialog boxes, see the article Dialog Boxes in OLE.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

COleDialog

COleInsertDialog

Requirements

Header: afxodlgs.h

COleInsertDialog::COleInsertDialog

This function constructs only a COleInsertDialog object.

COleInsertDialog (
    DWORD dwFlags = IOF_SELECTCREATENEW,
    CWnd* pParentWnd = NULL);

Parameters

dwFlags
Creation flag that contains any number of the following values to be combined using the bitwise-OR operator:

• IOF_SHOWHELP Specifies that the Help button will be displayed when the dialog box is called.

• IOF_SELECTCREATENEW Specifies that the Create New radio button will be selected initially when the dialog box is called. This is the default and cannot be used with IOF_SELECTCREATEFROMFILE.

• IOF_SELECTCREATEFROMFILE Specifies that the Create From File radio button will be selected initially when the dialog box is called. Cannot be used with IOF_SELECTCREATENEW.

• IOF_CHECKLINK Specifies that the Link check box will be checked initially when the dialog box is called.

• IOF_DISABLELINK Specifies that the Link check box will be disabled when the dialog box is called.

• IOF_CHECKDISPLAYASICON Specifies that the Display As Icon check box will be checked initially, the current icon will be displayed, and the Change Icon button will be enabled when the dialog box is called.

• IOF_VERIFYSERVERSEXIST Specifies that the dialog box should validate the classes it adds to the list box by ensuring that the servers specified in the registration database exist before the dialog box is displayed. Setting this flag can significantly impair performance.

pParentWnd
Points to the parent or owner window object (of type CWnd) to which the dialog object belongs. If it is NULL, the parent window of the dialog object is set to the main application window.

Remarks

To display the dialog box, call the DoModal function.

COleInsertDialog::CreateItem

Call this function to create an object of type COleClientItem only if DoModal returns IDOK.

BOOL CreateItem(COleClientItem* pItem);

Parameters

pItem
Points to the item to be created.

Return Value

Nonzero if item was created; otherwise 0.

Remarks

You must allocate the COleClientItem object before you can call this function.

COleInsertDialog::DoModal

Call this function to display the OLE Insert Object dialog box.

virtual INT_PTR
    DoModal();

INT_PTR
    DoModal(DWORD  dwFlags);

Parameters

dwFlags
One of the following values:

COleInsertDialog::DocObjectsOnly inserts only DocObjects.

COleInsertDialog::ControlsOnly inserts only ActiveX controls.

Zero inserts neither a DocObject nor an ActiveX control. This value results in the same implementation as the first prototype listed above.

Return Value

Completion status for the dialog box. One of the following values:

• IDOK if the dialog box was successfully displayed.

• IDCANCEL if the user canceled the dialog box.

• IDABORT if an error occurred. If IDABORT is returned, call the COleDialog::GetLastError member function to get more information about the type of error that occurred. For a listing of possible errors, see the OleUIInsertObject function in the Windows SDK.

Remarks

If you want to initialize the various dialog box controls by setting members of the m_io structure, you should do this before calling DoModal, but after the dialog object is constructed.

If DoModal returns IDOK, you can call other member functions to retrieve the settings or information input into the dialog box by the user.

COleInsertDialog::GetClassID

Call this function to get the CLSID associated with the selected item only if DoModal returns IDOK and the selection type is COleInsertDialog::createNewItem.

REFCLSID GetClassID() const;

Return Value

Returns the CLSID associated with the selected item.

Remarks

For more information, see CLSID Key in the Windows SDK.

COleInsertDialog::GetDrawAspect

Call this function to determine if the user chose to display the selected item as an icon.

DVASPECT GetDrawAspect() const;

Return Value

The method needed to render the object.

• DVASPECT_CONTENT Returned if the Display As Icon check box was not checked.

• DVASPECT_ICON Returned if the Display As Icon check box was checked.

Remarks

Call this function only if DoModal returns IDOK.

For more information on drawing aspect, see FORMATETC data structure in the Windows SDK.

COleInsertDialog::GetIconicMetafile

Call this function to get a handle to the metafile that contains the iconic aspect of the selected item.

HGLOBAL GetIconicMetafile() const;

Return Value

The handle to the metafile containing the iconic aspect of the selected item, if the Display As Icon check box was checked when the dialog was dismissed by choosing OK; otherwise NULL.

COleInsertDialog::GetPathName

Call this function to get the full path of the selected file only if DoModal returns IDOK and the selection type is not COleInsertDialog::createNewItem.

CString GetPathName() const;

Return Value

The full path to the file selected in the dialog box. If the selection type is createNewItem, this function returns a meaningless CString in release mode or causes an assertion in debug mode.

COleInsertDialog::GetSelectionType

Call this function to get the selection type chosen when the Insert Object dialog box was dismissed by choosing OK.

UINT GetSelectionType() const;

Return Value

Type of selection made.

Remarks

The return type values are specified by the Selection enumeration type declared in the COleInsertDialog class.

enum Selection {
    createNewItem,
    insertFromFile,
    linkToFile
    };

Brief descriptions of these values follow:

• COleInsertDialog::createNewItem The Create New radio button was selected.

• COleInsertDialog::insertFromFile The Create From File radio button was selected and the Link check box was not checked.

• COleInsertDialog::linkToFile The Create From File radio button was selected and the Link check box was checked.

COleInsertDialog::m_io

Structure of type OLEUIINSERTOBJECT used to control the behavior of the Insert Object dialog box.

OLEUIINSERTOBJECT m_io;

Remarks

Members of this structure can be modified either directly or through member functions.

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

See also

MFC Sample OCLIENT
COleDialog Class
Hierarchy Chart
COleDialog Class