IAxWinAmbientDispatch Interface
This interface provides methods for specifying characteristics of the hosted control or container.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
interface IAxWinAmbientDispatch : IDispatch
Members
Methods
| Name | Description |
|---|---|
| get_AllowContextMenu | The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu. |
| get_AllowShowUI | The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface. |
| get_AllowWindowlessActivation | The AllowWindowlessActivation property specifies whether the container will allow windowless activation. |
| get_BackColor | The BackColor property specifies the ambient background color of the container. |
| get_DisplayAsDefault | DisplayAsDefault is an ambient property that allows a control to find out if it is the default control. |
| get_DocHostDoubleClickFlags | The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click. |
| get_DocHostFlags | The DocHostFlags property specifies the user interface capabilities of the host object. |
| get_Font | The Font property specifies the ambient font of the container. |
| get_ForeColor | The ForeColor property specifies the ambient foreground color of the container. |
| get_LocaleID | The LocaleID property specifies the ambient locale ID of the container. |
| get_MessageReflect | The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control. |
| get_OptionKeyPath | The OptionKeyPath property specifies the registry key path to user settings. |
| get_ShowGrabHandles | The ShowGrabHandles ambient property allows the control to find out if it should draw itself with grab handles. |
| get_ShowHatching | The ShowHatching ambient property allows the control to find out if it should draw itself hatched. |
| get_UserMode | The UserMode property specifies the ambient user mode of the container. |
| put_AllowContextMenu | The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu. |
| put_AllowShowUI | The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface. |
| put_AllowWindowlessActivation | The AllowWindowlessActivation property specifies whether the container will allow windowless activation. |
| put_BackColor | The BackColor property specifies the ambient background color of the container. |
| put_DisplayAsDefault | DisplayAsDefault is an ambient property that allows a control to find out if it is the default control. |
| put_DocHostDoubleClickFlags | The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click. |
| put_DocHostFlags | The DocHostFlags property specifies the user interface capabilities of the host object. |
| put_Font | The Font property specifies the ambient font of the container. |
| put_ForeColor | The ForeColor property specifies the ambient foreground color of the container. |
| put_LocaleID | The LocaleID property specifies the ambient locale ID of the container. |
| put_MessageReflect | The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control. |
| put_OptionKeyPath | The OptionKeyPath property specifies the registry key path to user settings. |
| put_UserMode | The UserMode property specifies the ambient user mode of the container. |
Remarks
This interface is exposed by ATL's ActiveX control hosting objects. Call the methods on this interface to set the ambient properties available to the hosted control or to specify other aspects of the container's behavior. To supplement the properties provided by IAxWinAmbientDispatch, use IAxWinAmbientDispatchEx.
AxHost will try to load type information about IAxWinAmbientDispatch and IAxWinAmbientDispatchEx from the typelib that contains the code.
If you are linking to ATL90.dll, AXHost will load the type information from the typelib in the DLL.
See Hosting ActiveX Controls Using ATL AXHost for more details.
Requirements
The definition of this interface is available in a number of forms, as shown in the table below.
| Definition Type | File |
|---|---|
| IDL | atliface.idl |
| Type Library | ATL.dll |
| C++ | atliface.h (also included in ATLBase.h) |
IAxWinAmbientDispatch::get_AllowContextMenu
The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.
STDMETHOD(get_AllowContextMenu)(VARIANT_BOOL* pbAllowContextMenu);
Parameters
pbAllowContextMenu
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::get_AllowShowUI
The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.
STDMETHOD(get_AllowShowUI)(VARIANT_BOOL* pbAllowShowUI);
Parameters
pbAllowShowUI
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_FALSE as the default value of this property.
IAxWinAmbientDispatch::get_AllowWindowlessActivation
The AllowWindowlessActivation property specifies whether the container will allow windowless activation.
STDMETHOD(get_AllowWindowlessActivation)(VARIANT_BOOL* pbAllowWindowless);
Parameters
pbAllowWindowless
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::get_BackColor
The BackColor property specifies the ambient background color of the container.
STDMETHOD(get_BackColor)(OLE_COLOR* pclrBackground);
Parameters
pclrBackground
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses COLOR_BTNFACE or COLOR_WINDOW as the default value of this property (depending on whether the parent of the host window is a dialog or not).
IAxWinAmbientDispatch::get_DisplayAsDefault
DisplayAsDefault is an ambient property that allows a control to find out if it is the default control.
STDMETHOD(get_DisplayAsDefault)(VARIANT_BOOL* pbDisplayAsDefault);
Parameters
pbDisplayAsDefault
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_FALSE as the default value of this property.
IAxWinAmbientDispatch::get_DocHostDoubleClickFlags
The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.
STDMETHOD(get_DocHostDoubleClickFlags)(DWORD* pdwDocHostDoubleClickFlags);
Parameters
pdwDocHostDoubleClickFlags
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses DOCHOSTUIDBLCLK_DEFAULT as the default value of this property.
IAxWinAmbientDispatch::get_DocHostFlags
The DocHostFlags property specifies the user interface capabilities of the host object.
STDMETHOD(get_DocHostFlags)(DWORD* pdwDocHostFlags);
Parameters
pdwDocHostFlags
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses DOCHOSTUIFLAG_NO3DBORDER as the default value of this property.
IAxWinAmbientDispatch::get_Font
The Font property specifies the ambient font of the container.
STDMETHOD(get_Font)(IFontDisp** pFont);
Parameters
pFont
[out] The address of an IFontDisp interface pointer used to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the default GUI font or the system font as the default value of this property.
IAxWinAmbientDispatch::get_ForeColor
The ForeColor property specifies the ambient foreground color of the container.
STDMETHOD(get_ForeColor)(OLE_COLOR* pclrForeground);
Parameters
pclrForeground
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the system window text color as the default value of this property.
IAxWinAmbientDispatch::get_LocaleID
The LocaleID property specifies the ambient locale ID of the container.
STDMETHOD(get_LocaleID)(LCID* plcidLocaleID);
Parameters
plcidLocaleID
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the user's default locale as the default value of this property.
With this method you can discover the Ambient LocalID, that is, the LocaleID of the program your control is being used in. Once you know the LocaleID, you can call code to load locale-specific captions, error message text, and so forth from a resource file or satellite DLL.
IAxWinAmbientDispatch::get_MessageReflect
The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.
STDMETHOD(get_MessageReflect)(VARIANT_BOOL* pbMessageReflect);
Parameters
pbMessageReflect
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::get_OptionKeyPath
The OptionKeyPath property specifies the registry key path to user settings.
STDMETHOD(get_OptionKeyPath)(BSTR* pbstrOptionKeyPath);
Parameters
pbstrOptionKeyPath
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
IAxWinAmbientDispatch::get_ShowGrabHandles
The ShowGrabHandles ambient property allows the control to find out if it should draw itself with grab handles.
STDMETHOD(get_ShowGrabHandles)(VARIANT_BOOL* pbShowGrabHandles);
Parameters
pbShowGrabHandles
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation always returns VARIANT_FALSE as the value of this property.
IAxWinAmbientDispatch::get_ShowHatching
The ShowHatching ambient property allows the control to find out if it should draw itself hatched.
STDMETHOD(get_ShowHatching)(VARIANT_BOOL* pbShowHatching);
Parameters
pbShowHatching
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation always returns VARIANT_FALSE as the value of this property.
IAxWinAmbientDispatch::get_UserMode
The UserMode property specifies the ambient user mode of the container.
STDMETHOD(get_UserMode)(VARIANT_BOOL* pbUserMode);
Parameters
pbUserMode
[out] The address of a variable to receive the current value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::put_AllowContextMenu
The AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.
STDMETHOD(put_AllowContextMenu)(VARIANT_BOOL bAllowContextMenu);
Parameters
bAllowContextMenu
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::put_AllowShowUI
The AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.
STDMETHOD(put_AllowShowUI)(VARIANT_BOOL bAllowShowUI);
Parameters
bAllowShowUI
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_FALSE as the default value of this property.
IAxWinAmbientDispatch::put_AllowWindowlessActivation
The AllowWindowlessActivation property specifies whether the container will allow windowless activation.
STDMETHOD(put_AllowWindowlessActivation)(VARIANT_BOOL bAllowWindowless);
Parameters
bAllowWindowless
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::put_BackColor
The BackColor property specifies the ambient background color of the container.
STDMETHOD(put_BackColor)(OLE_COLOR clrBackground);
Parameters
clrBackground
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses COLOR_BTNFACE or COLOR_WINDOW as the default value of this property (depending on whether the parent of the host window is a dialog or not).
IAxWinAmbientDispatch::put_DisplayAsDefault
DisplayAsDefault is an ambient property that allows a control to find out if it is the default control.
STDMETHOD(put_DisplayAsDefault)(VARIANT_BOOL bDisplayAsDefault);
Parameters
bDisplayAsDefault
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_FALSE as the default value of this property.
IAxWinAmbientDispatch::put_DocHostDoubleClickFlags
The DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.
STDMETHOD(put_DocHostDoubleClickFlags)(DWORD dwDocHostDoubleClickFlags);
Parameters
dwDocHostDoubleClickFlags
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses DOCHOSTUIDBLCLK_DEFAULT as the default value of this property.
IAxWinAmbientDispatch::put_DocHostFlags
The DocHostFlags property specifies the user interface capabilities of the host object.
STDMETHOD(put_DocHostFlags)(DWORD dwDocHostFlags);
Parameters
dwDocHostFlags
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses DOCHOSTUIFLAG_NO3DBORDER as the default value of this property.
IAxWinAmbientDispatch::put_Font
The Font property specifies the ambient font of the container.
STDMETHOD(put_Font)(IFontDisp* pFont);
Parameters
pFont
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the default GUI font or the system font as the default value of this property.
IAxWinAmbientDispatch::put_ForeColor
The ForeColor property specifies the ambient foreground color of the container.
STDMETHOD(put_ForeColor)(OLE_COLOR clrForeground);
Parameters
clrForeground
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the system window text color as the default value of this property.
IAxWinAmbientDispatch::put_LocaleID
The LocaleID property specifies the ambient locale ID of the container.
STDMETHOD(put_LocaleID)(LCID lcidLocaleID);
Parameters
lcidLocaleID
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses the user's default locale as the default value of this property.
IAxWinAmbientDispatch::put_MessageReflect
The MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.
STDMETHOD(put_MessageReflect)(VARIANT_BOOL bMessageReflect);
Parameters
bMessageReflect
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
IAxWinAmbientDispatch::put_OptionKeyPath
The OptionKeyPath property specifies the registry key path to user settings.
STDMETHOD(put_OptionKeyPath)(BSTR bstrOptionKeyPath);
Parameters
bstrOptionKeyPath
[in] The new value of this property.
Return Value
A standard HRESULT value.
IAxWinAmbientDispatch::put_UserMode
The UserMode property specifies the ambient user mode of the container.
STDMETHOD(put_UserMode)(VARIANT_BOOL bUserMode);
Parameters
bUserMode
[in] The new value of this property.
Return Value
A standard HRESULT value.
Remarks
The ATL host object implementation uses VARIANT_TRUE as the default value of this property.
See also
IAxWinAmbientDispatchEx Interface
IAxWinHostWindow Interface
CAxWindow::QueryHost
AtlAxGetHost
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for