IBuilderWizardManager.GetBuilder Method
Requests a builder by CLSID or component category ID (CATID).
Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)
Syntax
'Declaration
Function GetBuilder ( _
ByRef rguidBuilder As Guid, _
grfGetOpt As UInteger, _
hwndPromptOwner As IntPtr, _
<OutAttribute> ByRef ppdispApp As Object, _
<OutAttribute> ByRef pwndBuilderOwner As IntPtr, _
ByRef riidBuilder As Guid, _
<OutAttribute> ByRef ppunkBuilder As Object _
) As Integer
int GetBuilder(
ref Guid rguidBuilder,
uint grfGetOpt,
IntPtr hwndPromptOwner,
out Object ppdispApp,
out IntPtr pwndBuilderOwner,
ref Guid riidBuilder,
out Object ppunkBuilder
)
int GetBuilder(
[InAttribute] Guid% rguidBuilder,
[InAttribute] unsigned int grfGetOpt,
[InAttribute] IntPtr hwndPromptOwner,
[OutAttribute] Object^% ppdispApp,
[OutAttribute] IntPtr% pwndBuilderOwner,
[InAttribute] Guid% riidBuilder,
[OutAttribute] Object^% ppunkBuilder
)
abstract GetBuilder :
rguidBuilder:Guid byref *
grfGetOpt:uint32 *
hwndPromptOwner:IntPtr *
ppdispApp:Object byref *
pwndBuilderOwner:IntPtr byref *
riidBuilder:Guid byref *
ppunkBuilder:Object byref -> int
function GetBuilder(
rguidBuilder : Guid,
grfGetOpt : uint,
hwndPromptOwner : IntPtr,
ppdispApp : Object,
pwndBuilderOwner : IntPtr,
riidBuilder : Guid,
ppunkBuilder : Object
) : int
Parameters
rguidBuilder
Type: System.Guid%[in] The CLSID or CATID of the builder. You can use a CATID only if you specify BLDGETOPT_AUTOMAPGUID as part of grfGetOpt.
grfGetOpt
Type: System.UInt32[in] Options as bit flags. Values are from the BLDGETFLAGS enumeration.
hwndPromptOwner
Type: System.IntPtr[in] Optional owner HWND for all dialogs if the user needs to choose which builder to run. Used only if you specify both BLDGETOPT_FAUTOMAPGUID and BLDGETOPT_FAUTOMAPENABLEPROMPT as part of grfGetOpt.
ppdispApp
Type: System.Object%[out] The IDispatch of the application the caller can pass to the invoke call on the builder. The caller must call release for this interface. You can use NULL if this IBuilderWizardManager does not have an IDispatch or the caller is not interested in getting the application IDispatch.
pwndBuilderOwner
Type: System.IntPtr%[out] Calculated HWND the caller should use as the owner HWND for invoking the builder. May be NULL if the caller is not interested in the calculated hwnd. Set to the HWND of the application main frame window if hwndPromptOwner is NULL. then *phwndBuilderOwner will be set to the hwnd of Application main frame window. Set to hwndPromptOwner if hwndPromptOwner is not NULL. This is the case when invoking the builder from within another modal dialog.
riidBuilder
Type: System.Guid%[in] Interface the client wants from the builder OLE server. The client needs to know the interface to ask for based on the type of builder wanted.
ppunkBuilder
Type: System.Object%[out] IUnknown interface pointer of the builder.
Return Value
Type: System.Int32
S_OK if the builder interface is successfully returned.
S_FALSE if the dialog UI is canceled.
E_NOINTERFACE if the builder is not supported.
An error HRESULT from CoCreatInstance if the builder automation server could not be instantiated.
Remarks
If the caller of GetBuilder is within a modal dialog, then the caller needs to pass the HWND of the modal dialog as the hwndPromptOwner. If the caller is not within a modal dialog, then the caller should just pass NULL—the IBuilderWizardManager will use the HWND for the application frame window.
The IBuilderWizardManager client must know the interface the builder implements and the signature of the method to call on the builder OLE server. Most builders expect at least the IDispatch of the host application and the HWND to use as the owner for windows.
The following are some important kinds of builders:
Object Builder – a builder invoked to set the properties of an OLE object newly created inside a container, for example a button wizard builder.
Property Builder – a builder invoked from a property page to help the user edit a property's value.
HTML Builder – a builder that returns a string of HTML text.
As a convenience for the client, the IBuilderWizardManager returns an AddRef counted pointer to the Application’s IDispatch and the HWND that the client will need to pass to the builder.
IBuilderWizardManager may want to act as if it doesn't support Object Builders if the user has disables Object Builders from running. Applications such as Access and IStudio give the user a Wizard toggle button that disables Object Builders.
.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.