Assembly: Microsoft.VisualStudio.Shell.Interop (in microsoft.visualstudio.shell.interop.dll)
int CreateDocumentWindow ( [InAttribute] uint grfCDW, [InAttribute] string pszMkDocument, [InAttribute] IVsUIHierarchy pUIH, [InAttribute] uint itemid, [InAttribute] IntPtr punkDocView, [InAttribute] IntPtr punkDocData, [InAttribute] ref Guid rguidEditorType, [InAttribute] string pszPhysicalView, [InAttribute] ref Guid rguidCmdUI, [InAttribute] IServiceProvider psp, [InAttribute] string pszOwnerCaption, [InAttribute] string pszEditorCaption, [OutAttribute] int pfDefaultPosition, out IVsWindowFrame ppWindowFrame )
int CreateDocumentWindow ( /** @attribute InAttribute() */ UInt32 grfCDW, /** @attribute InAttribute() */ String pszMkDocument, /** @attribute InAttribute() */ IVsUIHierarchy pUIH, /** @attribute InAttribute() */ UInt32 itemid, /** @attribute InAttribute() */ IntPtr punkDocView, /** @attribute InAttribute() */ IntPtr punkDocData, /** @attribute InAttribute() */ /** @ref */ Guid rguidEditorType, /** @attribute InAttribute() */ String pszPhysicalView, /** @attribute InAttribute() */ /** @ref */ Guid rguidCmdUI, /** @attribute InAttribute() */ IServiceProvider psp, /** @attribute InAttribute() */ String pszOwnerCaption, /** @attribute InAttribute() */ String pszEditorCaption, /** @attribute OutAttribute() */ int pfDefaultPosition, /** @attribute OutAttribute() */ /** @ref */ IVsWindowFrame ppWindowFrame )
[in] Flags whose values are taken from theDWORD.
[in] Path to the document. This path is used by the environment to register this view in the Running Document Table (RDT).
[in] Pointer to theinterface of the hierarchy item containing this document.
[in] Identifier of the item within the hierarchy corresponding to this document. Value is taken from the VSITEMID enumeration.
[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, a control, such as or , or a simple environment embedding, such as .
[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 (punkDocData on the caller's behalf.) and the text buffer object ( ). This parameter can be a null reference (Nothing in Visual Basic). Passing a null reference (Nothing in Visual Basic) causes the environment to create an instance of a default implementation of the
[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).
[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 () as well as a textual code view ( ). The editor factory must register information in the system registry for the mapping between logical and physical view types under the LogicalViewMap registry subkey.
[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 themethod.
[in] Pointer to the IServiceProvider interface. Can be a 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.
[in] Initial caption defined by the document owner (that is, the project) for the document window. This is often of the form: "ProjectName – ItemName."
[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.
[out] Can be a 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.
[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 ValueIf the method succeeds, it returns . If it fails, it returns an error code.
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 callor 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 punkDocView, caption, position, and so on. For a full list of the properties that can be accessed, see .object is returned by this method. Use this pointer to access the
The document window caption is managed by three independent parties, the document owner (typically the project), the editor, and the environment.
Document window caption
"%1 - %2"
%1 = "Project1" and
%2 = "MyForm"
"Project1 = MyForm [code] :2"
%3 = "c:/.../mydir/mydoc.txt"
a null reference (Nothing in Visual Basic)
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 event to know when to update this caption. The following DocumentAttribute strings are defined:
%1 == Project name –
%2 == item name –
%3 == Document (file) name –
If the OwnerCaption includes a %# string, then the WindowFrame monitors the OnAfterAttributeChange event and the hierarchyevent to track when these names are changing.