IVsUIShellOpenDocument.InitializeEditorInstance Method

Article
03/06/2013

Initializes an instance of the document editor.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Declaration
Function InitializeEditorInstance ( _
    grfIEI As UInteger, _
    punkDocView As IntPtr, _
    punkDocData As IntPtr, _
    pszMkDocument As String, _
    ByRef rguidEditorType As Guid, _
    pszPhysicalView As String, _
    ByRef rguidLogicalView As Guid, _
    pszOwnerCaption As String, _
    pszEditorCaption As String, _
    pHier As IVsUIHierarchy, _
    itemid As UInteger, _
    punkDocDataExisting As IntPtr, _
    pSPHierContext As IServiceProvider, _
    ByRef rguidCmdUI As Guid, _
    <OutAttribute> ByRef ppWindowFrame As IVsWindowFrame _
) As Integer

int InitializeEditorInstance(
    uint grfIEI,
    IntPtr punkDocView,
    IntPtr punkDocData,
    string pszMkDocument,
    ref Guid rguidEditorType,
    string pszPhysicalView,
    ref Guid rguidLogicalView,
    string pszOwnerCaption,
    string pszEditorCaption,
    IVsUIHierarchy pHier,
    uint itemid,
    IntPtr punkDocDataExisting,
    IServiceProvider pSPHierContext,
    ref Guid rguidCmdUI,
    out IVsWindowFrame ppWindowFrame
)

int InitializeEditorInstance(
    [InAttribute] unsigned int grfIEI, 
    [InAttribute] IntPtr punkDocView, 
    [InAttribute] IntPtr punkDocData, 
    [InAttribute] String^ pszMkDocument, 
    [InAttribute] Guid% rguidEditorType, 
    [InAttribute] String^ pszPhysicalView, 
    [InAttribute] Guid% rguidLogicalView, 
    [InAttribute] String^ pszOwnerCaption, 
    [InAttribute] String^ pszEditorCaption, 
    [InAttribute] IVsUIHierarchy^ pHier, 
    [InAttribute] unsigned int itemid, 
    [InAttribute] IntPtr punkDocDataExisting, 
    [InAttribute] IServiceProvider^ pSPHierContext, 
    [InAttribute] Guid% rguidCmdUI, 
    [OutAttribute] IVsWindowFrame^% ppWindowFrame
)

abstract InitializeEditorInstance : 
        grfIEI:uint32 * 
        punkDocView:IntPtr * 
        punkDocData:IntPtr * 
        pszMkDocument:string * 
        rguidEditorType:Guid byref * 
        pszPhysicalView:string * 
        rguidLogicalView:Guid byref * 
        pszOwnerCaption:string * 
        pszEditorCaption:string * 
        pHier:IVsUIHierarchy * 
        itemid:uint32 * 
        punkDocDataExisting:IntPtr * 
        pSPHierContext:IServiceProvider * 
        rguidCmdUI:Guid byref * 
        ppWindowFrame:IVsWindowFrame byref -> int

function InitializeEditorInstance(
    grfIEI : uint, 
    punkDocView : IntPtr, 
    punkDocData : IntPtr, 
    pszMkDocument : String, 
    rguidEditorType : Guid, 
    pszPhysicalView : String, 
    rguidLogicalView : Guid, 
    pszOwnerCaption : String, 
    pszEditorCaption : String, 
    pHier : IVsUIHierarchy, 
    itemid : uint, 
    punkDocDataExisting : IntPtr, 
    pSPHierContext : IServiceProvider, 
    rguidCmdUI : Guid, 
    ppWindowFrame : IVsWindowFrame
) : int

Parameters

grfIEI
Type: System.UInt32
[in] Flags controlling the initialization of the editor. For a list of enumeration values, see __VSIEIFLAGS. If you specify a value of IEI_DoNotLoadDocData for this parameter, then this method does not attempt to load your DocData by calling LoadDocData.

punkDocView
Type: System.IntPtr
[in] Pointer to the IUnknown interface of the document data object.

punkDocData
Type: System.IntPtr
[in] Pointer to the IUnknown interface of the document data object.

pszMkDocument
Type: System.String
[in] String form of the unique moniker identifier of the document in the project system, for example, the full path to the file. In non-file cases, this identifier is often in the form of a URL.

rguidEditorType
Type: System.Guid%
[in]GUID of the editor type.

pszPhysicalView
Type: System.String
[in] Name of the physical view.

rguidLogicalView
Type: System.Guid%
[in] GUID identifying the logical view. For a list of logical view GUIDS, see Logical View and Physical View. If you implement IVsMultiViewDocumentView on your document data object, then the value passed into the rguidLogicalView parameter determines which view is activated when the editor window is displayed. The editor window is displayed when the editor is instantiated. By specifying the logical view GUID, the caller of IVsUIShellOpenDocument::InitializeEditorInstance can request the specific view that matches the reason the caller is requesting the view. For example, the caller would specify LOGVIEWID_Debugging to get the view appropriate for debugging view, or LOGVIEWID_TextView to get the view appropriate for the text editor (that is, a view that implements IVsCodeWindow).

pszOwnerCaption
Type: System.String
[in] Initial caption defined by the document owner (that is, the project) for the document window. This is often of the format: "ProjectName – ItemName."

pszEditorCaption
Type: System.String
[in] Initial caption defined by the document editor for the document window. This is typically a string enclosed in square brackets (for example, [Form]). The initial value of this parameter is returned as an [out] parameter in the CreateEditorInstance method.

pHier
Type: Microsoft.VisualStudio.Shell.Interop.IVsUIHierarchy
[in] Pointer to the IVsUIHierarchy interface of the project that contains the document.

itemid
Type: System.UInt32
[in] UI hierarchy item identifier of the document in the project system. For more information see VSITEMID.

punkDocDataExisting
Type: System.IntPtr
[in] Pointer to the IUnknown interface of the document data object if the document data object already exists in the running document table.

pSPHierContext
Type: Microsoft.VisualStudio.OLE.Interop.IServiceProvider
[in] Project-specific service provider. For more information, see IServiceProvider.

rguidCmdUI
Type: System.Guid%
[in] Command UI GUID of the commands to display for this editor.

ppWindowFrame
Type: Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame%
[out, retval] The window frame that contains the editor. For more information, see IVsWindowFrame.

Return Value

Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIShellOpenDocument::InitializeEditorInstance(
   [in] VSIEIFLAGS grfIEI,
   [in] IUnknown *punkDocView,
   [in] IUnknown *punkDocData,
   [in] LPCOLESTR pszMkDocument,
   [in] REFGUID rguidEditorType,
   [in] LPCOLESTR pszPhysicalView,
   [in] REFGUID rguidLogicalView,
   [in] LPCOLESTR pszOwnerCaption,
   [in] LPCOLESTR pszEditorCaption,
   [in] IVsUIHierarchy *pHier,
   [in] VSITEMID itemid,
   [in] IUnknown *punkDocDataExisting,
   [in] IServiceProvider *pSPHierContext,
   [in] REFGUID rguidCmdUI,
   [out, retval] IVsWindowFrame **ppWindowFrame
);

Editors can be initialized for file-based documents and non file-based documents. Because IVsUIShellOpenDocument.InitializeEditorInstance takes pszMkDocumentString as an input parameter, this method supports initializing both file-based and non file-based editors.

IVsUIShellOpenDocument.InitializeEditorInstance is a helper function called by CreateEditorInstance. InitializeEditorInstance calls the following methods in order:

CreateDocumentWindow
LoadDocData (called unless IEI_DoNotLoadDocData is specified for IVsUIShellOpenDocument::InitializeEditorInstance (grfIEI).
ActivateLogicalView (called only if the document data object implements IVsMultiViewDocumentView).

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.