IVsEditorFactory.CreateEditorInstance Method

  • Article

Used by the editor factory architecture to create editors that support data/view separation.

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

Syntax

'Declaration
Function CreateEditorInstance ( _
    grfCreateDoc As UInteger, _
    pszMkDocument As String, _
    pszPhysicalView As String, _
    pvHier As IVsHierarchy, _
    itemid As UInteger, _
    punkDocDataExisting As IntPtr, _
    <OutAttribute> ByRef ppunkDocView As IntPtr, _
    <OutAttribute> ByRef ppunkDocData As IntPtr, _
    <OutAttribute> ByRef pbstrEditorCaption As String, _
    <OutAttribute> ByRef pguidCmdUI As Guid, _
    <OutAttribute> ByRef pgrfCDW As Integer _
) As Integer

int CreateEditorInstance(
    uint grfCreateDoc,
    string pszMkDocument,
    string pszPhysicalView,
    IVsHierarchy pvHier,
    uint itemid,
    IntPtr punkDocDataExisting,
    out IntPtr ppunkDocView,
    out IntPtr ppunkDocData,
    out string pbstrEditorCaption,
    out Guid pguidCmdUI,
    out int pgrfCDW
)

int CreateEditorInstance(
    [InAttribute] unsigned int grfCreateDoc, 
    [InAttribute] String^ pszMkDocument, 
    [InAttribute] String^ pszPhysicalView, 
    [InAttribute] IVsHierarchy^ pvHier, 
    [InAttribute] unsigned int itemid, 
    [InAttribute] IntPtr punkDocDataExisting, 
    [OutAttribute] IntPtr% ppunkDocView, 
    [OutAttribute] IntPtr% ppunkDocData, 
    [OutAttribute] String^% pbstrEditorCaption, 
    [OutAttribute] Guid% pguidCmdUI, 
    [OutAttribute] int% pgrfCDW
)

abstract CreateEditorInstance : 
        grfCreateDoc:uint32 * 
        pszMkDocument:string * 
        pszPhysicalView:string * 
        pvHier:IVsHierarchy * 
        itemid:uint32 * 
        punkDocDataExisting:IntPtr * 
        ppunkDocView:IntPtr byref * 
        ppunkDocData:IntPtr byref * 
        pbstrEditorCaption:string byref * 
        pguidCmdUI:Guid byref * 
        pgrfCDW:int byref -> int

function CreateEditorInstance(
    grfCreateDoc : uint, 
    pszMkDocument : String, 
    pszPhysicalView : String, 
    pvHier : IVsHierarchy, 
    itemid : uint, 
    punkDocDataExisting : IntPtr, 
    ppunkDocView : IntPtr, 
    ppunkDocData : IntPtr, 
    pbstrEditorCaption : String, 
    pguidCmdUI : Guid, 
    pgrfCDW : int
) : int

Parameters

  • grfCreateDoc
    Type: UInt32

    [in] Flags whose values are taken from the __VSCREATEEDITORFLAGS enumeration that defines the conditions under which to create the editor. Only open and silent flags are valid.

  • pszMkDocument
    Type: String

    [in] String form of the moniker identifier of the document in the project system. In the case of documents that are files, this is always the path to the file. This parameter can also be used to specify documents that are not files. For example, in a database-oriented project, this parameter could contain a string that refers to records in a table.

  • pszPhysicalView
    Type: String

    [in] Name of the physical view. See Remarks for details.

  • itemid
    Type: UInt32

    [in] Item identifier of this editor instance.

  • punkDocDataExisting
    Type: IntPtr

    [in] Must be the punkDocData object that is registered in the Running Document Table (RDT). This parameter is used to determine if a document buffer (DocData object) has already been created. When an editor factory is asked to create a secondary view, then this parameter will be non-null indicating that there is no document buffer. If the file is open, return VS_E_INCOMPATIBLEDOCDATA and the environment will ask the user to close it.

  • ppunkDocView
    Type: IntPtr%

    [out] Pointer to the IUnknown interface for the DocView object. Returns nulla null reference (Nothing in Visual Basic) if an external editor exists, otherwise returns the view of the document.

  • ppunkDocData
    Type: IntPtr%

    [out] Pointer to the IUnknown interface for the DocData object. Returns the buffer for the document.

  • pbstrEditorCaption
    Type: String%

    [out] Initial caption defined by the document editor for the document window. This is typically a string enclosed in square brackets, such as "[Form]". This value is passed as an input parameter to the CreateDocumentWindow method. If the file is [ReadOnly] the caption will be set during load of the file.

  • pguidCmdUI
    Type: Guid%

    [out] Returns the Command UI GUID. This GUID is active when this editor is activated. Any UI element that is visible in the editor has to use this GUID. This GUID is used in the .ctc file in the satellite DLL where it indicates which menus and toolbars should be displayed when the document is active.

Return Value

Type: Int32
If the document has a format that cannot be opened in the editor, VS_E_UNSUPPORTEDFORMAT is returned.
If the document is open in an incompatible editor (or E_NOINTERFACE), VS_E_INCOMPATIBLEDOCDATA is returned.
If the file could not be opened for any other reason, another HRESULT error code is returned.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsEditorFactory::CreateEditorInstance(
   [in] VSCREATEEDITORFLAGS grfCreateDoc,
   [in] LPCOLESTR pszMkDocument,
   [in] LPCOLESTR pszPhysicalView,
   [in] IVsHierarchy *pvHier,
   [in] VSITEMID itemid,
   [in] IUnknown *punkDocDataExisting,
   [out] IUnknown **ppunkDocView,
   [out] IUnknown **ppunkDocData,
   [out] BSTR *pbstrEditorCaption,
   [out] GUID *pguidCmdUI,
   [out, retval] VSEDITORCREATEDOCWIN *pgrfCDW
);

IVsEditorFactory.CreateEditorInstance is called by the environment in response to a project system calling either the OpenStandardEditor or OpenSpecificEditor helper functions in its OpenItem Method implementation. In the case of OpenStandardEditor, the environment first determines the editor factory with the highest priority for opening the file and then calls IVsEditorFactory.CreateEditorInstance. If the environment is unable to instantiate the document data in that editor, it will find the editor with the next highest priority and attempt to so that same thing. You can return the following for your editor factory to support this loop:

VS_E_UNSUPPORTEDFORMAT allows the loop to continue without closing the document if it is currently open.

Return this value if the document data provided to your editor factory is not compatible with your editor factory. You can determine whether the document data is compatible by calling QueryInterface on the document data object for the set of interfaces you require. In this case, the user is not prompted to close the file.VS_E_INCOMPATIBLEDOCDATA asks if the open document should be closed. Any other return will stop the loop from continuing.

Return this value if the document data provided to your editor factory is not compatible with your editor factory. You can determine whether the document data is compatible by calling QueryInterface on the document data object for the set of interfaces you require. This value is also returned if your editor factory only supports a single view on the document data, because in this case, the document data is already open with another view. Returning this value causes the environment to prompt the user to close the file in the other editor and allow it to be opened in your editor.

Note

If your editor instantiates the document data and document view on the same object, then your editor can only support opening a single view for an instance of the document data. As a result, if you are requested to open document data that is already instantiated in another editor, or even your editor, you are unable to support providing another view and must return this value.

If the document data object referenced by ppunkDocData supports IOleCommandTarget, the object is included in the command routing chain of the environment after the command is routed to the active object referenced by ppunkDocView.

The physical view string pszPhysicalView either is supplied by MapLogicalView or is found in the registry under the appropriate editor key of the form: HKLM\SOFTWARE\Microsoft\VisualStudio\8.0\Editors\<guid of editor>\LogicalViews\<guid of logical view>.

.NET Framework Security

See Also

Reference

IVsEditorFactory Interface

Microsoft.VisualStudio.Shell.Interop Namespace