HOWTO: Change WebBrowser Properties Stored in Property Bag

ID: Q197921

The information in this article applies to:

Microsoft Internet Explorer (Programming) versions 4.01, 4.01 SP1, 5.0, 5_beta

SUMMARY

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.

MORE INFORMATION

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:


Begin SHDocVwCtl.WebBrowser WebBrowser1
   Height          =   3015
   Left            =   240
   TabIndex        =   0
   Top             =   120
   Width           =   5655
   ExtentX         =   9975
   ExtentY         =   5318
   ViewMode        =   1
   Offline         =   0
   Silent          =   0
   RegisterAsBrowser=   0
   RegisterAsDropTarget=   1
   AutoArrange     =   0  'false
   NoClientEdge    =   0   'False
   AlignLeft       =   0   'False
   ViewID          =   "{0057D0E0-3573-11CF-AE69-08002B2E1262}"
   Location        =   ""
   End

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.)

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;
   }
   };

Immediately after creating the WebBrowser control, call QueryInterface to retrieve a pointer to the WebBrowser control's property bag - IPersistPropertyBag.

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.


   // 
   // Create the WebBrowser control
   // 
   CComPtr<IOleObject> spOleObject;
   HRESULT hr = CoCreateInstance(CLSID_WebBrowser, NULL, CLSCTX_INPROC,
                              IID_IOleObject, (void**)&spOleObject);
   if (FAILED)
   return hr;

   // Set the WebBrowser's properties
   IPersistPropertyBag* pPPBag;
   hr = spOleObject->QueryInterface(IID_IPersistPropertyBag,
                                 (void**)&pPPBag);

   if (SUCCEEDED(hr)) 
   {
   hr = pPPBag->Load(this, NULL);
   hr = pPPBag->Save(this, FALSE, TRUE);

   pPPBag->Release();
   }

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.

REFERENCES

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

"Reusing Browser Technology" in the MSDN Online Web Workshop:

http://www.microsoft.com/workshop/

Additional query words:

Keywords : kbIE400 kbIE401 kbWebBrowser kbIE401sp1 kbIE500 kbDSupport
Version : WINDOWS:4.01,4.01 SP1,5.0,5_beta
Platform : WINDOWS
Issue type : kbhowto