IAxWinAmbientDispatch Interface

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This interface provides methods for specifying characteristics of the hosted control or container.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

interface IAxWinAmbientDispatch : IDispatch

Methods

get_AllowContextMenuThe AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.
get_AllowShowUIThe AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.
get_AllowWindowlessActivationThe AllowWindowlessActivation property specifies whether the container will allow windowless activation.
get_BackColorThe BackColor property specifies the ambient background color of the container.
get_DisplayAsDefaultDisplayAsDefault is an ambient property that allows a control to find out if it is the default control.
get_DocHostDoubleClickFlagsThe DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.
get_DocHostFlagsThe DocHostFlags property specifies the user interface capabilities of the host object.
get_FontThe Font property specifies the ambient font of the container.
get_ForeColorThe ForeColor property specifies the ambient foreground color of the container.
get_LocaleIDThe LocaleID property specifies the ambient locale ID of the container.
get_MessageReflectThe MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.
get_OptionKeyPathThe OptionKeyPath property specifies the registry key path to user settings.
get_ShowGrabHandlesThe ShowGrabHandles ambient property allows the control to find out if it should draw itself with grab handles.
get_ShowHatchingThe ShowHatching ambient property allows the control to find out if it should draw itself hatched.
get_UserModeThe UserMode property specifies the ambient user mode of the container.
put_AllowContextMenuThe AllowContextMenu property specifies whether the hosted control is allowed to display its own context menu.
put_AllowShowUIThe AllowShowUI property specifies whether the hosted control is allowed to display its own user interface.
put_AllowWindowlessActivationThe AllowWindowlessActivation property specifies whether the container will allow windowless activation.
put_BackColorThe BackColor property specifies the ambient background color of the container.
put_DisplayAsDefaultDisplayAsDefault is an ambient property that allows a control to find out if it is the default control.
put_DocHostDoubleClickFlagsThe DocHostDoubleClickFlags property specifies the operation that should take place in response to a double-click.
put_DocHostFlagsThe DocHostFlags property specifies the user interface capabilities of the host object.
put_FontThe Font property specifies the ambient font of the container.
put_ForeColorThe ForeColor property specifies the ambient foreground color of the container.
put_LocaleIDThe LocaleID property specifies the ambient locale ID of the container.
put_MessageReflectThe MessageReflect ambient property specifies whether the container will reflect messages to the hosted control.
put_OptionKeyPathThe OptionKeyPath property specifies the registry key path to user settings.
put_UserModeThe UserMode property specifies the ambient user mode of the container.

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.

The definition of this interface is available in a number of forms, as shown in the table below.

Definition TypeFile
IDLatliface.idl
Type LibraryATL.dll
C++atliface.h (also included in ATLBase.h)

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

IAxWinAmbientDispatchEx Interface
IAxWinHostWindow Interface
CAxWindow::QueryHost
AtlAxGetHost

Show: