IVsUIShell.CreateDocumentWindow Method

Article
04/29/2015

This method creates a document window containing the embedding indicated by the punkDocView parameter.

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

Syntax

'Declaration
Function CreateDocumentWindow ( _
    grfCDW As UInteger, _
    pszMkDocument As String, _
    pUIH As IVsUIHierarchy, _
    itemid As UInteger, _
    punkDocView As IntPtr, _
    punkDocData As IntPtr, _
    ByRef rguidEditorType As Guid, _
    pszPhysicalView As String, _
    ByRef rguidCmdUI As Guid, _
    psp As IServiceProvider, _
    pszOwnerCaption As String, _
    pszEditorCaption As String, _
    <OutAttribute> pfDefaultPosition As Integer(), _
    <OutAttribute> ByRef ppWindowFrame As IVsWindowFrame _
) As Integer

int CreateDocumentWindow(
    uint grfCDW,
    string pszMkDocument,
    IVsUIHierarchy pUIH,
    uint itemid,
    IntPtr punkDocView,
    IntPtr punkDocData,
    ref Guid rguidEditorType,
    string pszPhysicalView,
    ref Guid rguidCmdUI,
    IServiceProvider psp,
    string pszOwnerCaption,
    string pszEditorCaption,
    int[] pfDefaultPosition,
    out IVsWindowFrame ppWindowFrame
)

int CreateDocumentWindow(
    [InAttribute] unsigned int grfCDW, 
    [InAttribute] String^ pszMkDocument, 
    [InAttribute] IVsUIHierarchy^ pUIH, 
    [InAttribute] unsigned int itemid, 
    [InAttribute] IntPtr punkDocView, 
    [InAttribute] IntPtr punkDocData, 
    [InAttribute] Guid% rguidEditorType, 
    [InAttribute] String^ pszPhysicalView, 
    [InAttribute] Guid% rguidCmdUI, 
    [InAttribute] IServiceProvider^ psp, 
    [InAttribute] String^ pszOwnerCaption, 
    [InAttribute] String^ pszEditorCaption, 
    [OutAttribute] array<int>^ pfDefaultPosition, 
    [OutAttribute] IVsWindowFrame^% ppWindowFrame
)

abstract CreateDocumentWindow : 
        grfCDW:uint32 * 
        pszMkDocument:string * 
        pUIH:IVsUIHierarchy * 
        itemid:uint32 * 
        punkDocView:IntPtr * 
        punkDocData:IntPtr * 
        rguidEditorType:Guid byref * 
        pszPhysicalView:string * 
        rguidCmdUI:Guid byref * 
        psp:IServiceProvider * 
        pszOwnerCaption:string * 
        pszEditorCaption:string * 
        pfDefaultPosition:int[] byref * 
        ppWindowFrame:IVsWindowFrame byref -> int

function CreateDocumentWindow(
    grfCDW : uint, 
    pszMkDocument : String, 
    pUIH : IVsUIHierarchy, 
    itemid : uint, 
    punkDocView : IntPtr, 
    punkDocData : IntPtr, 
    rguidEditorType : Guid, 
    pszPhysicalView : String, 
    rguidCmdUI : Guid, 
    psp : IServiceProvider, 
    pszOwnerCaption : String, 
    pszEditorCaption : String, 
    pfDefaultPosition : int[], 
    ppWindowFrame : IVsWindowFrame
) : int

Parameters

grfCDW
Type: UInt32

[in] Flags whose values are taken from the __VSCREATEDOCWINDWORD.

pszMkDocument
Type: String

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

pUIH
Type: Microsoft.VisualStudio.Shell.Interop.IVsUIHierarchy

[in] Pointer to the IVsHierarchy interface of the hierarchy item containing this document.

itemid
Type: UInt32

[in] Identifier of the item within the hierarchy corresponding to this document. Value is taken from the VSITEMID enumeration.

punkDocView
Type: IntPtr

[in] Pointer to the IUnknown interface for the document view object to be displayed within this window. The document view object can be a document object, such as IOleDocument, a control, such as IOleObject or IOleControl, or a simple environment embedding, such as IVsWindowPane.

punkDocData
Type: 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 (IVsTextView) and the text buffer object (IVsTextBuffer). 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: 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: String

[in] String to identify the physical view type for the editor. Some editor factories can support creating multiple physical view types. For example, it is possible for a single editor factory to support creating a graphical designer view (LOGVIEWID_Designer) as well as a textual code view (LOGVIEWID_Code). The editor factory must register information in the system registry for the mapping between logical and physical view types under the LogicalViewMap registry subkey.

rguidCmdUI
Type: Guid%

[in] Indicates what set of menus should be merged into the main menu bar when this document is active. This type of menu merging is recommended over OLE2 menu merging, which can be used if this parameter is GUID_NULL. The initial value of this parameter is returned as an [out] parameter in the CreateEditorInstance method.

psp
Type: Microsoft.VisualStudio.OLE.Interop.IServiceProvider

[in] Pointer to the IServiceProvider interface. Can be nulla null reference (Nothing in Visual Basic). This is an additional service provider provided by the caller (typically a 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.

pszOwnerCaption
Type: String

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

pszEditorCaption
Type: 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 IVsEditorFactory::CreateEditorInstance method.

pfDefaultPosition
Type: array<Int32[]

[out] Can be nulla null reference (Nothing in Visual Basic) if the caller does not desire this information. 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: Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIShell::CreateDocumentWindow(
   [in] VSCREATEDOCWIN grfCDW,
   [in] LPCOLESTR pszMkDocument,
   [in] IVsUIHierarchy *pUIH,
   [in] VSITEMID itemid,
   [in] IUnknown *punkDocView,
   [in] IUnknown *punkDocData,
   [in] REFGUID rguidEditorType,
   [in] LPCOLESTR pszPhysicalView,
   [in] REFGUID rguidCmdUI,
   [in] IServiceProvider *pSP,
   [in] LPCOLESTR pszOwnerCaption,
   [in] LPCOLESTR pszEditorCaption,
   [out] BOOL *pfDefaultPosition,
   [out] IVsWindowFrame **ppWindowFrame
);

IVsUIShell.CreateDocumentWindow is a low-level routine that is used in advanced scenarios. This method is not typically called by most clients, who generally call OpenStandardEditor or OpenSpecificEditor to open a document. These methods call IVsUIShell.CreateDocumentWindow as part of their implementation.

The following items are associated with every document window:

The path of the document (pszMkDocument), which is registered in the RDT.

A hierarchy/ItemID pair indicating the project with which the document is associated.

The view object displayed in the client area of the window (punkDocView).

An object representing the underlying data being edited by this view (punkDocData).

The environment-implemented IVsWindowFrame object is returned by this method. Use this pointer to access the punkDocView, caption, position, and so on. For a full list of the properties that can be accessed, see __VSFPROPID.

The document window caption is managed by three independent parties, the document owner (typically the project), the editor, and the environment.

Owner caption	Editor caption	Environment caption	Document window caption
"%1 - %2" where %1 = "Project1" and %2 = "MyForm"	"[code]"	" :2"	"Project1 = MyForm [code] :2"
"%3" where %3 = "c:/.../mydir/mydoc.txt"	nulla null reference (Nothing in Visual Basic)	""	"c:/.../mydir/mydoc.txt"

"%1 - %2"

where

%1 = "Project1" and

%2 = "MyForm"

"[code]"

" :2"

"Project1 = MyForm [code] :2"

"%3"

where

%3 = "c:/.../mydir/mydoc.txt"

nulla null reference (Nothing in Visual Basic)

"c:/.../mydir/mydoc.txt"

This management is accomplished by the document WindowFrame tracking the pszOwnerCaption and pszEditorCaption caption properties. These strings are a concatenation of the WindowFrame with any environment contributed strings. The pszOwnerCaption string can be defined using a sprintf-like format string to specify where DocumentAttribute strings should be automatically substituted. The window frame can listen for the OnAfterAttributeChange event to know when to update this caption. The following DocumentAttribute strings are defined:

%1 == Project name –

pHier->GetProperty(VSITEMID_ROOT, VSHPROPID_Name,...)

%2 == item name –

pHier->GetProperty(itemid, VSHPROPID_Name,...)

%3 == Document (file) name –

pHier->GetProperty(itemid, VSHPROPID_SaveName,...)

If the OwnerCaption includes a %# string, then the WindowFrame monitors the OnAfterAttributeChange event and the hierarchy OnPropertyChanged event to track when these names are changing.

.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.

Partager via