IVsExternalFilesManager.AddDocument Method

Programmatically tells the Miscellaneous Files project to add a node.

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

Syntax

'Declaration
Function AddDocument ( _
    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, _
    <OutAttribute> ByRef pfDefaultPosition As Integer, _
    <OutAttribute> ByRef ppWindowFrame As IVsWindowFrame _
) As Integer
int AddDocument(
    uint dwCDW,
    string pszMkDocument,
    IntPtr punkDocView,
    IntPtr punkDocData,
    ref Guid rguidEditorType,
    string pszPhysicalView,
    ref Guid rguidCmdUI,
    string pszOwnerCaption,
    string pszEditorCaption,
    out int pfDefaultPosition,
    out IVsWindowFrame ppWindowFrame
)
int AddDocument(
    [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, 
    [OutAttribute] int% pfDefaultPosition, 
    [OutAttribute] IVsWindowFrame^% ppWindowFrame
)
abstract AddDocument : 
        dwCDW:uint32 * 
        pszMkDocument:string * 
        punkDocView:IntPtr * 
        punkDocData:IntPtr * 
        rguidEditorType:Guid byref * 
        pszPhysicalView:string * 
        rguidCmdUI:Guid byref * 
        pszOwnerCaption:string * 
        pszEditorCaption:string * 
        pfDefaultPosition:int byref * 
        ppWindowFrame:IVsWindowFrame byref -> int
function AddDocument(
    dwCDW : uint, 
    pszMkDocument : String, 
    punkDocView : IntPtr, 
    punkDocData : IntPtr, 
    rguidEditorType : Guid, 
    pszPhysicalView : String, 
    rguidCmdUI : Guid, 
    pszOwnerCaption : String, 
    pszEditorCaption : String, 
    pfDefaultPosition : int, 
    ppWindowFrame : IVsWindowFrame
) : int

Parameters

  • pszMkDocument
    Type: System.String

    [in] Path to the document. The environment uses this path to register the 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 the document window.

  • punkDocData
    Type: System.IntPtr

    [in] Pointer to the IUnknown interface of an object representing the document data object of the document that is being added 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 (VsTextBuffer Object). 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 behalf of the caller.

  • rguidEditorType
    Type: System.Guid%

    [in] Unique identifier of the editor factory that created an instance of the document view and document data objects. 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 what 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.

  • pfDefaultPosition
    Type: System.Int32%

    [out] Can be nulla null reference (Nothing in Visual Basic) if the caller does not want 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 IVsExternalFilesManager::AddDocument(
   [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,
   [out] BOOL *pfDefaultPosition,
   [out] IVsWindowFrame **ppWindowFrame
);

Very similar to CreateDocumentWindow Method. AddDocument does not include the parameters ItemId and pUIH (a pointer to IVsHierarchy) because the Miscellaneous Files project assigns its own ItemId and the pUIH pair, and uses the rest of the AddDocument parameters to create a document window.

.NET Framework Security

See Also

Reference

IVsExternalFilesManager Interface

Microsoft.VisualStudio.Shell.Interop Namespace