DOCUMENT:Q280801  26-JUN-2001  [visualc]
TITLE   :INFO: Avoid WS_CLIPCHILDREN and ActiveX Control Painting Problem
PRODUCT :Microsoft C Compiler
PROD/VER::3.0
OPER/SYS:
KEYWORDS:kbATL kbMFC kbDSupport

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - The Microsoft Active Template Library (ATL) 3.0 
 - The Microsoft Foundation Classes (MFC) 
-------------------------------------------------------------------------------

SUMMARY
=======

An in-place container must use the WS_CLIPCHILDREN window style for the window
that it uses as the parent for an ActiveX Control in order to avoid repainting
problems.

MORE INFORMATION
================

The WS_CLIPCHILDREN style excludes the area occupied by child windows when you
draw within the parent window:

   http://msdn.microsoft.com/library/psdk/winui/windows_2v90.htm

To avoid repainting over an in-place object's output, the style must be applied
to the parent window of the object.

For Microsoft Foundation Classes (MFC) OLE (and Active) Document Containers, the
framework implicitly sets this style during in-place activation. However, the
style must be explicitly added for other situations in which in-place activation
is involved. From the point of view of MFC and Active Template Library (ATL)
containers, this is typically when hosting ActiveX controls.

Approaches for MFC Containers
-----------------------------

 - For MFC CWnd (including CView and CDialog) derived classes that host ActiveX
   controls, the style can be added by adding an override for the virtual
   PreCreateWindow() function and modifying cs.style. For instance, here's how
   PreCreateWindow would look in a CView-derived class:

   BOOL CMyView::PreCreateWindow(CREATESTRUCT& cs)
   {
   	// Add the WS_CLIPCHILDREN style to avoid repaint problems:
   	cs.style |= WS_CLIPCHILDREN;

   	return CView::PreCreateWindow(cs);
   }

 - Another way of adding the WS_CLIPCHILDREN style to a CDialog-derived class is
   through the Dialog editor, Styles tab, by selecting Clip children.

Approaches for ATL Containers
-----------------------------

 - For ATL-based container windows derived from CWindowImpl, the WS_CLIPCHILDREN
   style can be specified through Window Traits. For CWindowImpl-derived
   classes, the default traits are specified in the CControlWinTraits class,
   which does include the WS_CLIPCHILDREN style by default. For more information
   on ATL windowing classes and window traits, see the following Microsoft Web
   page:

   ATL 3.0 Window Classes: An Introduction (SubTopic: Using Window Traits to
   Specify Styles)
   http://msdn.microsoft.com/library/techart/atlwindow.htm#atlwindow_topic13

 - For ATL-based dialog boxes, the base class CAxDialogImpl does not derive from
   CWindowImpl, and hence does not have these traits. Custom CWinTraits cannot
   be specified for CAxDialogImpl either. The WS_CLIPCHILDREN style can be added
   through the Dialog editor, Styles tab, by selecting Clip children.

Approaches Common to MFC and ATL
--------------------------------

 - If the windows are being created explicitly through either CWnd::Create (for
   MFC) or CWindow::Create (for ATL), the WS_CLIPCHILDREN style can be specified
   through the dwStyle parameter.

 - A way of dynamically modifying the style, once the window has been created
   and has a valid HWND, is through CWnd::ModifyStyle for MFC windows, or
   CWindow::ModifyStyle for ATL windows.

REFERENCES
==========

CWnd::PreCreateWindow
http://msdn.microsoft.com/library/devprods/vs6/visualc/vcmfc/_mfc_cwnd.3a3a.precreatewindow.htm

CWnd::Create
http://msdn.microsoft.com/library/devprods/vs6/visualc/vcmfc/_mfc_cwnd.3a3a.create.htm

CWindow::Create
http://msdn.microsoft.com/library/devprods/vs6/visualc/vcmfc/vcrefcwindowcreate.htm

CWnd::ModifyStyle
http://msdn.microsoft.com/library/devprods/vs6/visualc/vcmfc/_mfc_cwnd.3a3a.modifystyle.htm

CWindow::ModifyStyle
http://msdn.microsoft.com/library/devprods/vs6/visualc/vcmfc/_atl_cwindow.3a3a.modifystyle.htm

For a specific example of incorrect repainting, see the following Microsoft
Knowledge Base article:

   Q220021 BUG: CHtmlView Does Not Repaint Correctly in AppWizard MDI APP

CHtmlView acts as a container window for the Microsoft WebBrowser Control:

   http://msdn.microsoft.com/workshop/browser/webbrowser/WebBrowser.asp

(c) Microsoft Corporation 2000, All Rights Reserved. Contributions by S. Ganesh,
Microsoft Corporation.


Additional query words:

======================================================================
Keywords          : kbATL kbMFC kbDSupport 
Technology        : kbAudDeveloper kbMFC kbATLsearch kbATL300
Version           : :3.0
Issue type        : kbinfo

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2001.