IVsUIShell.CreateDocumentWindow Method (UInt32, String, IVsUIHierarchy, UInt32, IntPtr, IntPtr, Guid, String, Guid, IServiceProvider, String, String, Int32[], IVsWindowFrame)


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)

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


Type: System.UInt32

[in] Flags whose values are taken from the __VSCREATEDOCWIN DWORD.

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

Type: Microsoft.VisualStudio.Shell.Interop.IVsUIHierarchy

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

Type: System.UInt32

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

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

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 (IVsTextView) and the text buffer object (IVsTextBuffer). This parameter can be null. Passing null causes the environment to create an instance of a default implementation of the punkDocData on the caller's behalf.

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

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

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

Type: Microsoft.VisualStudio.OLE.Interop.IServiceProvider

[in] Pointer to the IServiceProvider interface. Can be null. 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.

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

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, [Form]). The initial value of this parameter is returned as an [out] parameter in the IVsEditorFactory::CreateEditorInstance method.

Type: System.Int32[]

[out] Can be null 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.

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.

From vsshell.idl:

HRESULT IVsUIShell::CreateDocumentWindow(
   [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"


%1 = "Project1" and

%2 = "MyForm"


" :2"

"Project1 = MyForm [code] :2"



%3 = "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.

Return to top