IVsExternalFilesManager2.AddDocumentEx Method

Programmatically informs the Miscellaneous Files project to add a node, allows control over the icon for the node, and provides an opportunity for the editor to query for contextual services.

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

Syntax

'Declaration
Function AddDocumentEx ( _
    dwCDW As UInteger, _
    pszMkDocument As String, _
    punkDocView As IntPtr, _
    punkDocData As IntPtr, _
    ByRef rguidEditorType As Guid, _
    pszPhysicalView As String, _
    ByRef rguidCmdUI As Guid, _
    pszOwnerCaption As String, _
    pszEditorCaption As String, _
    pspContext As IServiceProvider, _
    hicon As IntPtr, _
    <OutAttribute> ByRef pfDefaultPosition As Integer, _
    <OutAttribute> ByRef ppWindowFrame As IVsWindowFrame _
) As Integer
'Usage
Dim instance As IVsExternalFilesManager2
Dim dwCDW As UInteger
Dim pszMkDocument As String
Dim punkDocView As IntPtr
Dim punkDocData As IntPtr
Dim rguidEditorType As Guid
Dim pszPhysicalView As String
Dim rguidCmdUI As Guid
Dim pszOwnerCaption As String
Dim pszEditorCaption As String
Dim pspContext As IServiceProvider
Dim hicon As IntPtr
Dim pfDefaultPosition As Integer
Dim ppWindowFrame As IVsWindowFrame
Dim returnValue As Integer

returnValue = instance.AddDocumentEx(dwCDW, _
    pszMkDocument, punkDocView, punkDocData, _
    rguidEditorType, pszPhysicalView, _
    rguidCmdUI, pszOwnerCaption, pszEditorCaption, _
    pspContext, hicon, pfDefaultPosition, _
    ppWindowFrame)

int AddDocumentEx(
    uint dwCDW,
    string pszMkDocument,
    IntPtr punkDocView,
    IntPtr punkDocData,
    ref Guid rguidEditorType,
    string pszPhysicalView,
    ref Guid rguidCmdUI,
    string pszOwnerCaption,
    string pszEditorCaption,
    IServiceProvider pspContext,
    IntPtr hicon,
    out int pfDefaultPosition,
    out IVsWindowFrame ppWindowFrame
)

int AddDocumentEx(
    [InAttribute] unsigned int dwCDW, 
    [InAttribute] String^ pszMkDocument, 
    [InAttribute] IntPtr punkDocView, 
    [InAttribute] IntPtr punkDocData, 
    [InAttribute] Guid% rguidEditorType, 
    [InAttribute] String^ pszPhysicalView, 
    [InAttribute] Guid% rguidCmdUI, 
    [InAttribute] String^ pszOwnerCaption, 
    [InAttribute] String^ pszEditorCaption, 
    [InAttribute] IServiceProvider^ pspContext, 
    [InAttribute] IntPtr hicon, 
    [OutAttribute] int% pfDefaultPosition, 
    [OutAttribute] IVsWindowFrame^% ppWindowFrame
)

function AddDocumentEx(
    dwCDW : uint, 
    pszMkDocument : String, 
    punkDocView : IntPtr, 
    punkDocData : IntPtr, 
    rguidEditorType : Guid, 
    pszPhysicalView : String, 
    rguidCmdUI : Guid, 
    pszOwnerCaption : String, 
    pszEditorCaption : String, 
    pspContext : IServiceProvider, 
    hicon : IntPtr, 
    pfDefaultPosition : int, 
    ppWindowFrame : IVsWindowFrame
) : int

Parameters

• dwCDW
  Type: System.UInt32

  [in] Defines the __VSCREATEDOCWIN flags, which determine how the document window is created.

• pszMkDocument
  Type: System.String

  [in] Path to the document. This path is used by the environment to register this view in the Running Document Table (RDT).

• punkDocView
  Type: System.IntPtr

  [in] Pointer to the IUnknown interface for the document view object to be displayed within this window.

• punkDocData
  Type: System.IntPtr

  [in] Pointer to the IUnknown interface of an object representing the document data object of this document in situations where there is view or data separation. For example, the core text editor has a text view object (VsTextView Object) and the text buffer object (VsTextBufferObject). This parameter can be nulla null reference (Nothing in Visual Basic). Passing nulla null reference (Nothing in Visual Basic) causes the environment to create an instance of a default implementation of the punkDocData on the caller's behalf.

• rguidEditorType
  Type: System.Guid%

  [in] Unique identifier of the editor factory that created an instance of the document view and document dataobjects. This should be GUID_NULL if the document is not constructed using an editor factory (that is, an instance is created with private knowledge of a particular project).

• pszPhysicalView
  Type: System.String

  [in] String to identify the physical view type for the editor.

• rguidCmdUI
  Type: System.Guid%

  [in] Specifies the GUID that indicates which set of menus should be merged into the main menu bar when this document is active. It is used for turning on visibility of commands and tool windows.

• 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, [Read Only]). The initial value of this parameter is returned as an [out] parameter in the CreateEditorInstance Method.

• pspContext
  Type: Microsoft.VisualStudio.OLE.Interop.IServiceProvider

  [out] Pointer to the IServiceProvider interface. Can be nulla null reference (Nothing in Visual Basic). This is an additional service provider provided by the caller (the Miscellaneous Files project) making it possible for the caller to provide extra context (by means of services) to the embedded editor. Thus, when the embedded object makes a service request, the frame attempts to satisfy this request. If the service is not provided by the frame, pSP is tried. If the service is not found there, then the environment's global service provider is queried.

• hicon
  Type: System.IntPtr

  [in] Specifies a handle to an icon. Allows you to specify the icon for the Miscellaneous Project node.

• pfDefaultPosition
  Type: System.Int32%

  [out] Can be null if the caller does not desire the default position information for the window. true if the environment did not have any information saved about the last position of this tool window (that is, guidPersistenceSlot was not found), hence it was placed in some default location on the screen. false if this window was placed where the user last located and sized it.

• ppWindowFrame
  Type: Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame%

  [out] Pointer to the frame containing this editor, which can be used to manipulate the location, size, caption, and other properties of the window. It can also be used to get the IUnknown interface pointer of the embedding (that is, the punkDocView) or the punkDocData.

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 IVsExternalFilesManager2::AddDocumentEx(
   [in] VSCREATEDOCWIN dwCDW,
   [in] LPCOLESTR pszMkDocument,
   [in] IUnknown *punkDocView,
   [in] IUnknown *punkDocData,
   [in] REFGUID rguidEditorType,
   [in] LPCOLESTR pszPhysicalView,
   [in] REFGUID rguidCmdUI,
   [in] LPCOLESTR pszOwnerCaption,
   [in] LPCOLESTR pszEditorCaption,
   [in] IServiceProvider *pspContext,
   [in] HICON hIcon,
   [out] BOOL *pfDefaultPosition,
   [out] IVsWindowFrame **ppWindowFrame
);

Similar to AddDocument Method. Provides the additional functionality of specifying the Miscellaneous Projects icon and provides an opportunity for the editor to query for contextual services.

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.

See Also

Reference

IVsExternalFilesManager2 Interface

IVsExternalFilesManager2 Members

Microsoft.VisualStudio.Shell.Interop Namespace