IViewObjectExImpl Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at IViewObjectExImpl Class.

This class implements IUnknown and provides default implementations of the IViewObject, IViewObject2, and IViewObjectEx interfaces.

Syntax

template<class T>  
class ATL_NO_VTABLE IViewObjectExImpl 
   : public IViewObjectEx

Parameters

T
Your class, derived from IViewObjectExImpl.

Members

Public Methods

Remarks

The IViewObject, IViewObject2, and IViewObjectEx interfaces enable a control to display itself directly, and to create and manage an advise sink to notify the container of changes in the control display. The IViewObjectEx interface provides support for extended control features such as flicker-free drawing, non-rectangular and transparent controls, and hit-testing (for example, how close a mouse click must be to be considered on the control). Class IViewObjectExImpl provides a default implementation of these interfaces and implements IUnknown by sending information to the dump device in debug builds.

Inheritance Hierarchy

IViewObjectEx

IViewObjectExImpl

Requirements

Header: atlctl.h

IViewObjectExImpl::Draw

Draws a representation of the control onto a device context.

STDMETHOD(Draw)(
    DWORD dwDrawAspect,
    LONG lindex,
    void* pvAspect,
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    LPCRECTL prcBounds,
    LPCRECTL prcWBounds,
    BOOL(_stdcall* /* pfnContinue*/) (DWORD_PTR dwContinue),
    DWORD_PTR /* dwContinue */);

Remarks

This method calls CComControl::OnDrawAdvanced which in turn calls your control class's OnDraw method. An OnDraw method is automatically added to your control class when you create your control with the ATL Control Wizard. The Wizard's default OnDraw draws a rectangle with the label "ATL 3.0".

See IViewObject::Draw in the Windows SDK.

IViewObjectExImpl::Freeze

Freezes the drawn representation of a control so it won't change until an Unfreeze. The ATL implementation returns E_NOTIMPL.

STDMETHOD(Freeze)(
    DWORD /* dwAspect */,
    LONG /* lindex */,
    void* /* pvAspect */,
    DWORD* /* pdwFreeze */);

Remarks

See IViewObject::Freeze in the Windows SDK.

IViewObjectExImpl::GetAdvise

Retrieves an existing advisory sink connection on the control, if there is one.

STDMETHOD(GetAdvise)(
    DWORD* /* pAspects */,
    DWORD* /* pAdvf */,
    IAdviseSink** /* ppAdvSink */);

Remarks

The advisory sink is stored in the control class data member CComControlBase::m_spAdviseSink.

See IViewObject::GetAdvise in the Windows SDK.

IViewObjectExImpl::GetColorSet

Returns the logical palette used by the control for drawing. The ATL implementation returns E_NOTIMPL.

STDMETHOD(GetColorSet)(
    DWORD /* dwAspect */,
    LONG /* lindex */,
    void* /* pvAspect */,
    DVTARGETDEVICE* /* ptd */,
    HDC /* hicTargetDevice */,
    LOGPALETTE** /* ppColorSet */);

Remarks

See IViewObject::GetColorSet in the Windows SDK.

IViewObjectExImpl::GetExtent

Retrieves the control's display size in HIMETRIC units (0.01 millimeter per unit) from the control class data member CComControlBase::m_sizeExtent.

STDMETHOD(GetExtent)(
    DWORD /* dwDrawAspect */,
    LONG /* lindex */,
    DVTARGETDEVICE* /* ptd */,
    LPSIZEL* lpsizel);

Remarks

See IViewObject2::GetExtent in the Windows SDK.

IViewObjectExImpl::GetNaturalExtent

Provides sizing hints from the container for the object to use as the user resizes it.

STDMETHOD(GetNaturalExtent)(
    DWORD dwAspect,
    LONG /* lindex */,
    DVTARGETDEVICE* /* ptd */,
    HDC /* hicTargetDevice */,
    DVEXTENTINFO* pExtentInfo,
    LPSIZEL psizel);

Remarks

If dwAspect is DVASPECT_CONTENT and pExtentInfo->dwExtentMode is DVEXTENT_CONTENT, sets * psizel to the control class's data member CComControlBase::m_sizeNatural. Otherwise, returns an error HRESULT.

See IViewObjectEx::GetNaturalExtent in the Windows SDK.

IViewObjectExImpl::GetRect

Returns a rectangle describing a requested drawing aspect. The ATL implementation returns E_NOTIMPL.

STDMETHOD(GetRect)(DWORD /* dwAspect */, LPRECTL /* pRect */);

Remarks

See IViewObjectEx::GetRect in the Windows SDK.

IViewObjectExImpl::GetViewStatus

Returns information about the opacity of the object and what drawing aspects are supported.

STDMETHOD(GetViewStatus)(DWORD* pdwStatus);

Remarks

By default, ATL sets pdwStatus to indicate that the control supports VIEWSTATUS_OPAQUE (possible values are in the VIEWSTATUS enumeration).

See IViewObjectEx::GetViewStatus in the Windows SDK.

IViewObjectExImpl::QueryHitPoint

Checks if the specified point is in the specified rectangle and returns a HITRESULT value in pHitResult.

STDMETHOD(QueryHitPoint)(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    POINT ptlLoc,
    LONG /* lCloseHit */,
    DWORD* /* pHitResult */);

Remarks

The value can be either HITRESULT_HIT or HITRESULT_OUTSIDE.

If dwAspect equals DVASPECT_CONTENT, the method returns S_OK. Otherwise, the method returns E_FAIL.

See IViewObjectEx::QueryHitPoint in the Windows SDK.

IViewObjectExImpl::QueryHitRect

Checks whether the control's display rectangle overlaps any point in the specified location rectangle and returns a HITRESULT value in pHitResult.

STDMETHOD(QueryHitRect)(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    LPRECT prcLoc,
    LONG /* lCloseHit */,
    DWORD* /* pHitResult */);

Remarks

The value can be either HITRESULT_HIT or HITRESULT_OUTSIDE.

If dwAspect equals DVASPECT_CONTENT, the method returns S_OK. Otherwise, the method returns E_FAIL.

See IViewObjectEx::QueryHitRect in the Windows SDK.

IViewObjectExImpl::SetAdvise

Sets up a connection between the control and an advise sink so the sink can be notified about changes in the control's view.

STDMETHOD(SetAdvise)(
    DWORD /* aspects */,
    DWORD /* advf */,
    IAdviseSink* pAdvSink);

Remarks

The pointer to the IAdviseSink interface on the advise sink is stored in the control class data member CComControlBase::m_spAdviseSink.

See IViewObject::SetAdvise in the Windows SDK.

IViewObjectExImpl::Unfreeze

Unfreezes the drawn representation of the control. The ATL implementation returns E_NOTIMPL.

STDMETHOD(Unfreeze)(DWORD /* dwFreeze */);

Remarks

See IViewObject::Unfreeze in the Windows SDK.

IWorkerThreadClient::CloseHandle

Implement this method to close the handle associated with this object.

HRESULT CloseHandle(HANDLE hHandle);

Parameters

hHandle
The handle to be closed.

Return Value

Return S_OK on success, or an error HRESULT on failure.

Remarks

The handle passed to this method was previously associated with this object by a call to CWorkerThread::AddHandle.

Example

The following code shows a simple implementation of IWorkerThreadClient::CloseHandle.

   HRESULT CloseHandle(HANDLE hObject)
   {
      // Users should do any shutdown operation required here.
      // Generally, this means just closing the handle.

      if (!::CloseHandle(hObject))
      {
         // Closing the handle failed for some reason.
         return AtlHresultFromLastError();
      }

      return S_OK;
   }

IWorkerThreadClient::Execute

Implement this method to execute code when the handle associated with this object becomes signaled.

HRESULT Execute(DWORD_PTR dwParam, HANDLE hObject);

Parameters

dwParam
The user parameter.

hObject
The handle that has become signaled.

Return Value

Return S_OK on success, or an error HRESULT on failure.

Remarks

The handle and DWORD/pointer passed to this method were previously associated with this object by a call to CWorkerThread::AddHandle.

Example

The following code shows a simple implementation of IWorkerThreadClient::Execute.

   HRESULT Execute(DWORD_PTR dwParam, HANDLE hObject)
   {
      // Cast the parameter to its known type.
      LONG* pn = reinterpret_cast<LONG*>(dwParam);

      // Increment the LONG.
      LONG n = InterlockedIncrement(pn);

      // Log the results.
      printf_s("Handle 0x%08X incremented value to : %d\n", (DWORD_PTR)hObject, n);

      return S_OK;
   }

See Also

CComControl Class
ActiveX Controls Interfaces
Tutorial
Creating an ATL Project
Class Overview