IVsUIShell.CreateDocumentWindow Method

Reference

Definition

Namespace:: Microsoft.VisualStudio.Shell.Interop

Assembly:: Microsoft.VisualStudio.Shell.Interop.dll

Assembly:: Microsoft.VisualStudio.Interop.dll

Package:: Microsoft.VisualStudio.Interop v17.11.40262

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

public:
 int CreateDocumentWindow(System::UInt32 grfCDW, System::String ^ pszMkDocument, Microsoft::VisualStudio::Shell::Interop::IVsUIHierarchy ^ pUIH, System::UInt32 itemid, IntPtr punkDocView, IntPtr punkDocData, Guid % rguidEditorType, System::String ^ pszPhysicalView, Guid % rguidCmdUI, Microsoft::VisualStudio::OLE::Interop::IServiceProvider ^ psp, System::String ^ pszOwnerCaption, System::String ^ pszEditorCaption, cli::array <int> ^ pfDefaultPosition, [Runtime::InteropServices::Out] Microsoft::VisualStudio::Shell::Interop::IVsWindowFrame ^ % ppWindowFrame);

public int CreateDocumentWindow (uint grfCDW, string pszMkDocument, Microsoft.VisualStudio.Shell.Interop.IVsUIHierarchy pUIH, uint itemid, IntPtr punkDocView, IntPtr punkDocData, ref Guid rguidEditorType, string pszPhysicalView, ref Guid rguidCmdUI, Microsoft.VisualStudio.OLE.Interop.IServiceProvider psp, string pszOwnerCaption, string pszEditorCaption, int[] pfDefaultPosition, out Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame ppWindowFrame);

abstract member CreateDocumentWindow : uint32 * string * Microsoft.VisualStudio.Shell.Interop.IVsUIHierarchy * uint32 * nativeint * nativeint * Guid * string * Guid * Microsoft.VisualStudio.OLE.Interop.IServiceProvider * string * string * int[] * IVsWindowFrame -> int

Public 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, pfDefaultPosition As Integer(), ByRef ppWindowFrame As IVsWindowFrame) As Integer

Parameters

grfCDW: UInt32

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

pszMkDocument: String

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

pUIH: IVsUIHierarchy

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

itemid: UInt32

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

punkDocView: IntPtr
nativeint

[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: IntPtr
nativeint

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

rguidEditorType: 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: 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: 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(UInt32, String, String, IVsHierarchy, UInt32, IntPtr, IntPtr, IntPtr, String, Guid, Int32) method.

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

pszOwnerCaption: 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: 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(UInt32, String, String, IVsHierarchy, UInt32, IntPtr, IntPtr, IntPtr, String, Guid, Int32) method.

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

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

Returns

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"	`null`	""	"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.

Applies to

Share via