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