Knowledge Base

How to handle document events in a Visual C++ application

Article ID: 815715

Article Last Modified on 5/16/2007

APPLIES TO

Microsoft Visual C++ .NET 2003 Standard Edition
Microsoft Visual C++ 2005 Express Edition

For a Microsoft Visual Basic .NET version of this article, see 311284.

For a Microsoft Visual C# .NET version of this article, see 312777.

SUMMARY

You can use the WebBrowser control in Microsoft Visual Studio or in Microsoft Visual Studio 2005. This article discusses how to handle the events of the WebBrowser control in Visual Studio .NET or Visual Studio 2005.

Document events can be handled in Microsoft Visual C++ .NET 2003 or Microsoft Visual C++ 2005 for both WebBrowser controls and for Microsoft Internet Explorer. The events themselves are exposed by the Mshtml.HTMLDocumentEvents2_Event event interface. The Mshtml.HTMLDocumentEvents2_Event event interface exposes most of the document events that must be handled in your application.

To handle an event, you must define a function that is called when the event occurs. After the event handler is in place, you must hook the event. You can hook an event after the DocumentComplete event on the WebBrowser control is triggered. To connect the sender of the event to your event handler, you set up a delegate. Delegates are type-safe, security-enhanced, managed objects that point to a method.

INTRODUCTION

This step-by-step article discusses how to handle document events for the WebBrowser control in Visual C++ .NET 2003 or Visual C++ 2005. This information also applies to handling document events in Visual C++ .NET 2003 or Visual C++ 2005 when you automate Internet Explorer.

back to the top

Requirements

This article assumes that you are familiar with the following topics:

How to use Visual Studio .NET
How to use Visual C++ .NET 2003 or Visual C++ 2005
How to host the WebBrowser control (Shdocvw.dll)

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:

Visual Studio .NET or Visual C++ 2005
Internet Explorer 5.5 Service Pack 2 (SP2) or later

back to the top

Describe the technique

To handle an event, you must define a function that is called when the event occurs. You must match the signature of the event that is triggered. The following code sample is a sample function that can be used to handle the MouseOver event of the document:

    private:
        void MouseOverEventHandler(mshtml::IHTMLEventObj *e)
        {
        }

You can hook an event after the DocumentComplete event on the WebBrowser control is triggered. To connect the sender of the event to your event handler, you set up a delegate. Delegates are type-safe, security-enhanced, managed objects that point to a method. The following code sample demonstrates how to connect the MouseOverEventHandler method to the MouseOver event of the document:

mshtml::HTMLDocumentEvents2_Event *iEvent;
iEvent->onmouseover += new mshtml::HTMLDocumentEvents2_onmouseoverEventHandler(this, MouseOverEventHandler);

back to the top

Create the project

The code sample in this section sends the WebBrowser control to http://www.microsoft.com. After the page is loaded, the code sample hooks the OnMouseOver event and the OnClick event, and then adds text to a list box when these events are triggered.

Start Visual Studio .NET 2003 or Visual Studio 2005.
On the File menu, point to New, and then click Project.

The New Project dialog box appears.
Under Project Types, click Visual C++ Projects.

Note In Visual C++ 2005, click Visual C++.
Under Templates, click Windows Forms Application (.NET).

Note In Visual C++ 2005, click Windows Forms Application.
In the Name text box, type DocEventsSample, and then click OK.

By default, the form that is named Form1 is created.
In Solution Explorer, right-click the DocEventsSample node, and then click Add Reference.

Note In Visual C++ 2005, click Reference.
In the Add Reference dialog box, click the COM tab.

Note In Visual C++ 2005, click Add new Reference, and then click the COM tab.
In the list of COM components, double-click Microsoft HTML Object Library, and then click OK.
In the toolbox, click the General tab.
Right-click Toolbox, and then click Add/Remove Items.

Note In Visual C++ 2005, click Choose Items.
In the Customize Toolbox dialog box, click the COM Components tab.
In the COM components list, locate the Microsoft Web Browser component.

The Microsoft Web Browser component points to Shdocvw.dll in your system32 directory.
Click to select the Microsoft Web Browser check box, and then click OK.

A new control that is named Microsoft Web Browser appears on the General tab of your toolbox. You can add the WebBrowser control to the form.
Add a Microsoft Web Browser control to the form that is named Form1.
Click Windows Forms, and then double-click ListBox.
Arrange the controls so that they are easy to view on the form.

Resize the form that is named Form1, the Web Browser control, and the ListBox control.

Double-click Form1 to open the Code window for the Form1_Load method. Add the following code for the Form1_Load method:

Object *myurl = __try_cast<Object *>(new String("http://www.microsoft.com"));
Object *nullobj = NULL;
this->axWebBrowser1->Navigate2(&myurl, &nullobj, &nullobj, &nullobj, &nullobj);

On the View menu, click Designer, and then click WebBrowser. In the Properties window, click Events. Locate the DocumentComplete event. Type DocumentComplete, and then press ENTER.

You can see the Code window, and you can see a template for the DocumentComplete event.

Type the following code or paste the following code in the DocumentComplete event handler.

mshtml::IHTMLDocument2 *pDoc = NULL;

// Get the document pointer loaded in the WebBrowser control.
pDoc = __try_cast<mshtml::IHTMLDocument2*>(axWebBrowser1->Document);

mshtml::HTMLDocumentEvents2_Event *iEvent;
iEvent = __try_cast<mshtml::HTMLDocumentEvents2_Event *> (pDoc);
iEvent->onclick += new mshtml::HTMLDocumentEvents2_onclickEventHandler(this, ClickEventHandler);
iEvent->onmouseover += new mshtml::HTMLDocumentEvents2_onmouseoverEventHandler(this, MouseOverEventHandler);
listBox1->Items->Clear();

Add the following functions to the project in the Form1 class:
```
private:
    bool ClickEventHandler(mshtml::IHTMLEventObj *e)
    {
        String *str;
        str = String::Concat(e->type, S":", e->srcElement->tagName);           
        listBox1->Items->Insert(0, str);
        return true;
    }
private:
    void MouseOverEventHandler(mshtml::IHTMLEventObj *e)
    {
        String *str;
        str = String::Concat(e->type, S":", e->srcElement->tagName);           
        listBox1->Items->Insert(0, str);
    }
```
Note You must add the common language runtime support compiler option (/clr:oldSyntax) in Visual C++ 2005 to successfully compile the previous code sample.
To add the common language runtime support compiler option in Visual C++ 2005, follow these steps:
1. Click Project, and then click <ProjectName> Properties.
  
  Note<ProjectName> is a placeholder for the name of the project.
2. Expand Configuration Properties, and then click General.
3. Click to select Common Language Runtime Support, Old Syntax (/clr:oldSyntax) in the Common Language Runtime support project setting on the right pane, click Apply, and then click OK.
For more information about the common language runtime support compiler options, visit the following Microsoft Developer Network Web site: site:

/clr (Common Language Runtime Compilation)
http://msdn2.microsoft.com/en-us/library/k8d11d4s.aspx
Press CTRL+SHIFT+B to build the application.
Press CTRL+F5 to start the application.

The form that is named Form1 appears with the Web page in the WebBrowser control. If you move or if you click the Web page, you can see the mouse events in the ListBox control.

back to the top

Review the notes

If you are automating Internet Explorer, the process is the same. However, instead of using the axWebBrowser1 variable name of the WebBrowser control, you can use your local variable name for Internet Explorer.
This sample does not consider framesets. When you navigate to a frameset, you may not see any events in your application. In this case, you must add code to handle the chance that there may be framesets.

back to the top

Additional query words: Document events WebBrowser Control HTMLDocumentEvents2 DocumentComplete Handling events

REFERENCES

For additional information about the WebBrowser control and the methods, the properties, and the events that the WebBrowser control exposes, visit the following Microsoft Developer Network (MSDN) Web site:

http://msdn2.microsoft.com/en-us/library/Aa752043.aspx

For additional information about handling and raising events, visit the following the MSDN Web site:

http://msdn2.microsoft.com/en-us/library/edzehd2t(vs.71).aspx

For additional information about the WebBrowser control, visit the following MSDN Web site:

http://msdn2.microsoft.com/en-us/library/Aa752040.aspx

For additional information about developing Web-based solutions for Internet Explorer, visit the following Microsoft Web sites:

http://msdn.microsoft.com/ie/

http://support.microsoft.com/iep

back to the top

Keywords: kbprogramming kbinterop kbmshtml kbhtml kbforms kbcominterop kbcollections kbwindowsforms kbwebbrowser kbhowtomaster KB815715