Q311765 </DIV>
                  <DIV class=summary>
                  <H2>SUMMARY</H2>Dsoframerctl.exe contains a Visual C++ ActiveX 
                  control sample that acts as an ActiveX document container for 
                  hosting Office documents (including Microsoft Word, Microsoft 
                  Excel, Microsoft PowerPoint, Microsoft Project, and Microsoft 
                  Visio documents) in a custom form or Web page. The control 
                  (Dsoframer.ocx) is lightweight and flexible, and gives 
                  developers new possibilities for using Office in a custom 
                  solution.<BR><BR>The control is designed to handle specific 
                  issues that make using ActiveX documents from a non-top-level 
                  host window difficult, and serves as a starting place for 
                  constructing your own embedded object file viewer or editor as 
                  an ActiveX control. </DIV>
                  <DIV class=moreinformation>
                  <H2>MORE INFORMATION</H2>This sample shows Visual C++ 
                  developers how to construct an ActiveX control to act as an 
                  ActiveX document container, which allows developers to embed 
                  Office files for in-place editing and viewing. The control can 
                  then be used by Microsoft Visual Basic, Microsoft Internet 
                  Explorer, or Web developers to view Office files inside their 
                  main solution, and give them programmatic control over the 
                  document while it is embedded.<BR><BR><STRONG>NOTE</STRONG>: 
                  <STRONG>This sample is provided "AS IS" with no warranty or 
                  support from Microsoft.</STRONG> It is a demonstration, 
                  provided for informational purposes only, and has not been 
                  rigorously tested with all environments and ActiveX document 
                  servers. It is up to you to make it "production ready" if you 
                  use it in any development solution.<BR><BR>
                  <H3>Background Information</H3>ActiveX document technology is 
                  not new, but it has become increasingly popular in recent 
                  years, thanks in large part to Internet Explorer. The ability 
                  of Internet Explorer to view and edit Office files inside the 
                  browser is made possible because of ActiveX document 
                  technology. Many developers rely on the support that Internet 
                  Explorer offers for this type of containment in order to host 
                  Office files in their custom solutions, either in Web pages 
                  that are viewed in Internet Explorer, or in the WebBrowser 
                  control (Shdocvw.dll) that is used in a Visual Basic project. 
                  The ability to have Office run embedded inside a custom 
                  solution is very attractive to some development 
                  projects.<BR><BR>There are limitations, however, in how 
                  Internet Explorer implements ActiveX document containment, and 
                  in what it exposes to developers. Some of the limitations of 
                  using Internet Explorer or WebBrowser controls in a solution 
                  are as follows: 
                  <UL>
                    <LI><STRONG>Programmatic control</STRONG>: Internet Explorer 
                    gives limited access to the embedded object, particularly 
                    when the object is embedded inside a Web page. Even when the 
                    object is used outside of a Web page (in the WebBrowser 
                    control, for example), an Automation object cannot be 
                    obtained directly after opening the file. Rather, the code 
                    must wait for the <STRONG>NavigateComplete2</STRONG> event 
                    to fire, thereby preventing synchronous access to the object 
                    right after the <STRONG>Navigate</STRONG> method is called.
                    <LI><STRONG>Documents unintentionally opened outside the 
                    browser</STRONG>: Internet Explorer uses certain criteria 
                    (including a check of an end-user option) to determine 
                    whether it attempts to open a document inside or outside the 
                    browser. This can be problematic if a development project 
                    requires that its documents always open inside the 
                    designated frame, because Internet Explorer does not 
                    guarantee that any non-HTML file will be opened in-place.
                    <LI><STRONG>Toolbars and menus</STRONG>: When you view 
                    Office files, Internet Explorer automatically hides the 
                    toolbars of the document, and makes it difficult to control 
                    this behavior or selectively choose what the default setting 
                    should be. Moreover, menu support is only available if the 
                    document is shown in the top-level frame of the main 
                    Internet Explorer window, not when the document is shown in 
                    a subframe or in the WebBrowser control. Developers may want 
                    better control over both.
                    <LI><STRONG>Saving to a server</STRONG>: Some development 
                    projects require a document to open from or save to a URL 
                    location (Web folder). The ability to save a particular 
                    embedded object to a Web server is not native to Internet 
                    Explorer or the WebBrowser control.</LI></UL>The following 
                  sample corrects all of these issues, and many others. It also 
                  gives developers a component that they can refine and 
                  customize to suit a particular business need or 
                  environment.<BR><BR>
                  <H3>Considerations About the Design</H3>ActiveX document 
                  containment is not a simple task. The requirements to be a 
                  well-written host are fairly lengthy, and participation of the 
                  top-level application is always assumed. The idea of making an 
                  ActiveX control behave as an ActiveX document container is 
                  therefore inherently problematic, and somewhat difficult. 
                  However, this idea has been presented to Microsoft several 
                  times by developers that seek alternatives to the WebBrowser 
                  control, or to aid in more customizable Web projects, and 
                  deserves some attention.<BR><BR>Nonetheless, it should be 
                  recognized that an ActiveX control (even this one) is not 
                  considered a suitable host for this type of embedding, and 
                  will have certain limitations that the developer must always 
                  take into account (and may never be fully able to 
                  resolve).<BR><BR>A fully functional ActiveX document container 
                  needs to control the following elements that belong to the 
                  application that acts as the host, for which an ActiveX 
                  control is not well-suited: 
                  <UL>
                    <LI><STRONG>WindowProc</STRONG>: Because the purpose of 
                    ActiveX documents is to make two applications behave as one, 
                    the top-level window of the host application must forward 
                    messages to the in-place object as it receives them. These 
                    messages are not sent to ActiveX controls because controls 
                    are always in-process, and therefore do not require them. 
                    Therefore, to solve this critical issue, the sample must 
                    subclass the main window of any application on which it is 
                    inserted to capture these window messages and forward them 
                    as needed.
                    <LI><STRONG>MessageLoop</STRONG>: All good OLE containers 
                    should forward keyboard accelerator messages to an in-place 
                    active object. Unfortunately, controls do not control the 
                    main message loop and cannot handle this for the host. As a 
                    result, certain keyboard shortcuts may not work as expected 
                    when focus is not directly inside the user interface window 
                    of the in-place object.
                    <LI><STRONG>Menus</STRONG>: Per Graphics Device Interface 
                    (GDI) rules for the Microsoft Windows operating system, only 
                    the top-level window should have a menu bar. Because this 
                    menu is controlled by the host application and not a 
                    control, it is not possible to handle formal OLE menu 
                    merging without intimate knowledge of the target application 
                    in which the control is set to run. Because menu support is 
                    important to some developers, the sample in this article 
                    uses a pop-up menu for menu access as a workaround. 
                    Developers can choose to enable or disable the pop-up menu 
                    as needed.
                    <LI><STRONG>MessageFilter</STRONG>: All single-threaded 
                    apartment (STA) threads in an OLE application implement a 
                    message filter for processing certain messages while in a 
                    blocking call to an OLE server. It is very important that 
                    the STA message filter does not block return calls for 
                    <STRONG>IOleInPlaceFrame</STRONG> methods, and a good 
                    ActiveX document host should implement a custom message 
                    filter. However, message filters are controlled by the 
                    thread and application, not a control, so this is not 
                    possible under COM rules. The two most common containers for 
                    this sort of control, Internet Explorer and Visual Basic, 
                    support OLE embedding on their own and have a filter that 
                    allows these calls. This means that the sample should work 
                    in these containers with no extra work needed. Other 
                    non-Visual Basic or non-Internet Explorer containers, 
                    however, may stop responding (hang) unexpectedly when they 
                    use this sample. If the containers stop responding, check 
                    the implementation for the message filter.
                    <LI><STRONG>Window Focus and Z Order</STRONG>: Each thread 
                    maintains its own focus and Z order state with respect to 
                    windows that belong to that thread. To have two applications 
                    behave seamlessly, special care needs to be taken to ensure 
                    that focus and Z order states between both applications 
                    remain synchronized. When you display dialog boxes or other 
                    windows that overlap an in-place active object, be sure to 
                    notify the control that you are going into a modal state so 
                    that the control can notify the object and handle focus and 
                    Z order correctly.</LI></UL>These factors limit the ability of 
                  an ActiveX control to make a suitable ActiveX document 
                  container for all hosts, in all situations. However, the 
                  sample given below does meet the needed requirements for 
                  Office servers when it is embedded in a control that is hosted 
                  in a Visual Basic 6.0, Visual Studio .NET, or Internet 
                  Explorer 5.x or 6.0 solution. Other host applications, or 
                  ActiveX document servers, may require you to satisfy more of 
                  the listed requirements than this sample provides. 
                  <H3>Download the Sample</H3>The following file is available 
                  for download from the Microsoft Download Center:<BR>
                  <P class=indent><A class=URLLink 
                  href="http://download.microsoft.com/download/OfficeXPDev/sample/1.0/WIN98MeXP/EN-US/Dsoframerctl.exe" 
                  target=_top>Dsoframerctl.exe</A></P>Release Date: 
                  Jan-29-2002<BR><BR>For additional information about how to 
                  download Microsoft Support files, click the following article 
                  number to view the article in the Microsoft Knowledge Base: 
                  <P class=indent><A class=KBlink 
                  href="http://support.microsoft.com/default.aspx?scid=kb;EN-US;119591">119591</A> 
                  How to Obtain Microsoft Support Files from Online Services 
                  </P>Microsoft scanned this file for viruses. Microsoft used 
                  the most current virus-detection software that was available 
                  on the date that the file was posted. The file is stored on 
                  security-enhanced servers that help to prevent any 
                  unauthorized changes to the file. The Dsoframerctl.exe file 
                  contains the following files:<BR><BR><SPAN 
                  class=weboutput><FONT size=2>
                  <TABLE borderColor=#000000 cellSpacing=0 cellPadding=4 
                  width="70%" borderColorLight=#ffffff border=1>
                    <TBODY>
                    <TR>
                      <TH bgColor=#c0c0c0><FONT size=2>FileName</FONT></TH>
                      <TH bgColor=#c0c0c0><FONT size=2>Size</FONT></TH></TR>
                    <TR>