Share via


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
'Usage
Dim instance As IBuilderWizardManager 
Dim rguidBuilder As Guid 
Dim grfGetOpt As UInteger 
Dim hwndPromptOwner As IntPtr 
Dim ppdispApp As Object 
Dim pwndBuilderOwner As IntPtr 
Dim riidBuilder As Guid 
Dim ppunkBuilder As Object 
Dim returnValue As Integer 

returnValue = instance.GetBuilder(rguidBuilder, _
    grfGetOpt, hwndPromptOwner, ppdispApp, _
    pwndBuilderOwner, riidBuilder, ppunkBuilder)
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
)
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.

  • 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

See Also

Reference

IBuilderWizardManager Interface

IBuilderWizardManager Members

Microsoft.VisualStudio.Shell.Interop Namespace