IBuilderWizardManager.GetBuilder Method
Definition
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.
Requests a builder by CLSID or component category ID (CATID).
public:
int GetBuilder(Guid % rguidBuilder, System::UInt32 grfGetOpt, IntPtr hwndPromptOwner, [Runtime::InteropServices::Out] System::Object ^ % ppdispApp, [Runtime::InteropServices::Out] IntPtr % pwndBuilderOwner, Guid % riidBuilder, [Runtime::InteropServices::Out] System::Object ^ % ppunkBuilder);public int GetBuilder (ref Guid rguidBuilder, uint grfGetOpt, IntPtr hwndPromptOwner, out object ppdispApp, out IntPtr pwndBuilderOwner, ref Guid riidBuilder, out object ppunkBuilder);abstract member GetBuilder : Guid * uint32 * nativeint * obj * nativeint * Guid * obj -> intPublic Function GetBuilder (ByRef rguidBuilder As Guid, grfGetOpt As UInteger, hwndPromptOwner As IntPtr, ByRef ppdispApp As Object, ByRef pwndBuilderOwner As IntPtr, ByRef riidBuilder As Guid, ByRef ppunkBuilder As Object) As IntegerParameters
- rguidBuilder
- 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
- UInt32
[in] Options as bit flags. Values are from the BLDGETFLAGS enumeration.
- hwndPromptOwner
-
IntPtr
nativeint
[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
- 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
-
IntPtr
nativeint
[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
- 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
- Object
[out] IUnknown interface pointer of the builder.
Returns
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.