IVsEditorFactory.CreateEditorInstance Method

Article
04/22/2008

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

'Déclaration
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
'Utilisation
Dim instance As IVsEditorFactory
Dim grfCreateDoc As UInteger
Dim pszMkDocument As String
Dim pszPhysicalView As String
Dim pvHier As IVsHierarchy
Dim itemid As UInteger
Dim punkDocDataExisting As IntPtr
Dim ppunkDocView As IntPtr
Dim ppunkDocData As IntPtr
Dim pbstrEditorCaption As String
Dim pguidCmdUI As Guid
Dim pgrfCDW As Integer
Dim returnValue As Integer

returnValue = instance.CreateEditorInstance(grfCreateDoc, _
    pszMkDocument, pszPhysicalView, _
    pvHier, itemid, punkDocDataExisting, _
    ppunkDocView, ppunkDocData, pbstrEditorCaption, _
    pguidCmdUI, pgrfCDW)

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
)

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: System.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: System.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: System.String

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

pvHier
Type: Microsoft.VisualStudio.Shell.Interop.IVsHierarchy

[in] Pointer to the IVsHierarchy interface.

itemid
Type: System.UInt32

[in] Item identifier of this editor instance.

punkDocDataExisting
Type: System.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: System.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: System.IntPtr%

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

pbstrEditorCaption
Type: System.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: System.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.

pgrfCDW
Type: System.Int32%

[out, retval] enum of type __VSEDITORCREATEDOCWIN. These flags are passed to CreateDocumentWindow.

Return Value

Type: System.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 [M:Microsoft.VisualStudio.Shell.Interop.IVsEditorFactory.MapLogicalView(][System.Guid@,System.String@][)] 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>.

Permissions

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.

Partager via