How To Change WebBrowser Properties Stored in Property Bag

The WebBrowser control exposes certain properties such as LocationURL and RegisterAsBrowser through normal COM property methods. Other properties, such as AutoArrange, are stored only in the property bag and no methods are exposed for these properties. Therefore, these properties can only be set in the property bag.

This article describes how to set the WebBrowser properties stored in the property bag in Visual Basic and Visual C++ applications that are hosting the WebBrowser control.

In Visual Basic applications that are hosting the WebBrowser control, changing the values of the properties stored in the property bag is relatively easy. Visual Basic sets the values of these properties in the .frm file for the form that contains the WebBrowser control.

Here is a portion of a .frm file for a Visual Basic application that is hosting the WebBrowser control: You will notice that some of the properties written to this file, such as RegisterAsBrowser and RegisterAsDropTarget, have associated COM property methods exposed by the WebBrowser control. You can change the values of these properties in the Visual Basic Property window or at run time using WebBrowser methods. Others, such as AutoArrange and ViewMode can be changed only by editing this .frm file. For information regarding which properties can be set through WebBrowser methods, please see the "Reusing Browser Technology" section of the MSDN Online Workshop that is listed in the REFERENCES section of this article.

In order to set properties stored in the property bag in a C++ application, there are a few things you have to do. (Note that the sample C++ code in this article sets the AutoArrange property to true so that when navigating to a folder, all folder items will be arranged automatically.)

1. Your application must implement IPropertyBag. For example, if you are hosting the WebBrowser control in an ATL application you can implement this interface simply by inheriting from IPropertyBag, entering it into your COM map, and implementing its methods like this:

      class ATL_NO_VTABLE CAtlBrowser :
        public CComObjectRootEx<CComSingleThreadModel>,
        public CComCoClass<CAtlBrowser, &CLSID_CAtlBrowser>,
        public CWindowImpl<CAtlBrowser>,
        public IDispatchImpl<IAtlBrowser, &IID_IAtlBrowser,
                          &LIBID_ATLBROWSERLib>,
        public IOleClientSite,
        public IOleInPlaceSite,
        public IPropertyBag     //  <-- Inheriting from IPropertyBag
      {
      public:
      // COM Map
      BEGIN_COM_MAP(CAtlBrowser)
         COM_INTERFACE_ENTRY(IAtlBrowser)
         COM_INTERFACE_ENTRY(IDispatch)
         COM_INTERFACE_ENTRY(IOleClientSite)
         COM_INTERFACE_ENTRY(IOleWindow)
         COM_INTERFACE_ENTRY(IOleInPlaceSite)
         COM_INTERFACE_ENTRY(IPropertyBag)  // <-- COM map entry
      END_COM_MAP()
   
      // IPropertyBag Methods
      STDMETHOD(Read)(LPCOLESTR pszPropName, VARIANT* pVar,
                      IErrorLog* pErrorLog)
      {
         USES_CONVERSION;
   
         switch(pVar->vt)
         {
         case VT_BOOL:
            if (!strcmp(OLE2T(pszPropName), "AutoArrange"))
               pVar->boolVal = VARIANT_TRUE;
            break;
         default:
            break;
         };
   
         return S_OK;
      }
   
      STDMETHOD(Write)(LPCOLESTR pszPropName, VARIANT* pVar)
      {
         USES_CONVERSION;
   
         ATLTRACE("%s ", OLE2T(pszPropName));
   
         switch(pVar->vt)
         {
         case VT_I4:
           ATLTRACE("%ld\n", pVar->lVal);
           break;
         case VT_BSTR:
            ATLTRACE("%s\n", OLE2T(pVar->bstrVal));
            break;
         case VT_BOOL:
            ATLTRACE("%hu\n", pVar->boolVal);
            break;
         default:
            ATLTRACE("\n");
            break;
         };
   
         return S_OK;
      }
      };
   					

2. Immediately after creating the WebBrowser control, call QueryInterface to retrieve a pointer to the WebBrowser control's property bag - IPersistPropertyBag.
3. After you retrieve a pointer to the property bag, tell the WebBrowser control to load its properties from your IPropertyBag interface by calling IPersistPropertyBag::Load() and passing it a pointer to your implementation of IPropertyBag.

When you call the Load method, the WebBrowser control will call your IPropertBag::Read() method once for every property that it is storing in its property bag. It is in your Read method where you can set the values of properties stored in the property bag as illustrated in number 1 above.

Note that IPersistPropertyBag::Load can be called only once. Any subsequent calls to Load will fail with an HRESULT of E_UNEXPECTED.

You can instruct the WebBrowser control to save some or all of its properties to your IPropertyBag implementation by calling IPersistPropertyBag::Save(). When you call this function, the WebBrowser control will call your IPropertyBag::Write() method once for every property in the property bag. You can call IPersistPropertyBag::Save() at any time to instruct the WebBrowser control to save it's properties to your IPropertyBag implementation.

The following is ATL source code that creates an instance of the WebBrowser control, retrieves the WebBrowser control's IPersistPropertyBag, and instructs the WebBrowser control to load its properties and then save them. NOTE: Setting the WebBrowser properties stored in the property bag from an MFC application is possible, but extremely difficult. As mentioned prior, IPersistPropertyBag::Load() can be called only once. Also, this method cannot be called after IPersistPropertyBag::InitNew(). When hosting the WebBrowser control in an Microsoft Foundation Classes (MFC) application using a wrapper class (CWebBrowser2) or CHTMLView, the MFC libraries will call either InitNew() or Load() when creating the WebBrowser control. Which method is called depends on a number of conditions. This means that when you call IPersistPropertyBag::Load from your application, it fails with an HRESULT of E_UNEXPECTED.

Therefore, if you wish to set the WebBrowser properties that are stored in the property bag, you must create and site the WebBrowser control manually. You cannot use a wrapper class (CWebBrowser2) or CHTMLView.

IPersistPropertyBag and IPropertyBag in the Microsoft Developer Network (MSDN).

"Reusing Browser Technology" in the MSDN Online Web Workshop: (c) Microsoft Corporation 1998, All Rights Reserved. Contributions by Scott Roberts, Microsoft Corporation.