0

What is the different between HTMLDocumentEvents and HTMLDocumentEvents2 of mshtml ?

Roman R.
  • 68,205
  • 6
  • 94
  • 158
palazzo train
  • 3,229
  • 1
  • 19
  • 40

1 Answers1

2

These are different interfaces: different methods, even though some are duplicating one another exactly or extending.

HTMLDocument COM object is capable to deliver events using several interfaces and it is up to COM client to choose which interface to use. Originally it was HTMLDocumentEvents and then a need to extend the object adding new events suggested to leave the original interface intact and add new event interfaces with new methods (HTMLDocumentEvents2, HTMLDocumentEvents3, HTMLDocumentEvents4).

Extended interface can have additional methods, arguments without danger of breaking compatibility with existing clients using older event interface, e.g. onhelp, onclick methods on the two interrfaces:

dispinterface HTMLDocumentEvents {
    properties:
    methods:
        [id(0x8001000a)]
        VARIANT_BOOL onhelp();
        [id(0xfffffda8)]
        VARIANT_BOOL onclick();

dispinterface HTMLDocumentEvents2 {
    properties:
    methods:
        [id(0x8001000a)]
        VARIANT_BOOL onhelp([in] IHTMLEventObj* pEvtObj);
        [id(0xfffffda8)]
        VARIANT_BOOL onclick([in] IHTMLEventObj* pEvtObj);
Roman R.
  • 68,205
  • 6
  • 94
  • 158
  • Why is this an answer? The shown methods are about `DWebBrowserEvents` and `DWebBrowserEvents2` dispinterfaces of the WebBrowser component, the op is asking about the `HTMLDocumentEvents` and `HTMLDocumentEvents2` dispinterfaces of the MSHTML component. – acelent Jan 08 '15 at 10:47
  • @PauloMadeira: You are correct, it was a wrong excerpt. – Roman R. Jan 08 '15 at 10:59
  • Ok, but still, the main reason is that with `HTMLDocumentEvents`, you had to get the event object from the document (e.g. `document->parentWindow(&window); window->event(&event);`), thus the event handler had to have a pointer to the document beforehand. With `HTMLDocumentEvents2`, the event object is simply given on every method, which is enough for most things without having to keep a reference to the document. As such, this prevents event handlers from keeping the document alive in a cyclic reference. – acelent Jan 08 '15 at 11:09
  • This is hardly the reason. This explains why `HTMLDocumentEvents2` appeared in first place: original `HTMLDocumentEvents` did not have `IHTMLEventObj*` parameters but as it was already published, it was too late to simply change syntax of existing methods. A new `HTMLDocumentEvents2` was needed, and existing `HTMLDocumentEvents` was still needed for compatibility for legacy apps. This is the reason why both interfaces exist. Without legacy app constraint, the handy arguments would be just added on existing event interface. Nice and clean solution but unacceptable as it breaks legacy apps. – Roman R. Jan 08 '15 at 11:22
  • Actually, [you shouldn't change an interface once it's published](http://msdn.microsoft.com/en-us/library/windows/desktop/ms688484(v=vs.85).aspx), even without the need for legacy. Nitpick: `HTMLDocumentEvents2` is not really extending `HTMLDocumentEvents`, since dispinterfaces always inherit from `IDispatch` alone; also, in events, it's the client's responsibility to implement the dispinterface. For posterity: my first comment doesn't really apply anymore, since the answer has been almost completely changed. – acelent Jan 08 '15 at 12:55
  • @PauloMadeira: You can delete the entire comment, which is outdated to clean up the thread. – Roman R. Jan 08 '15 at 13:00
  • Apparently `HTMLDocumentEvents2` extends the event set previously backed by `HTMLDocumentEvents` interface. The older one did not have `stop` method and the newer one received it. Your mistake is that you put it as if two dispinterfaces were the intention so that implementer could choose the one he needs. It is however clear, and IDL trace proves it, that #2 interface is historical evolution of MSHTML library and it was added later to expose new functionality (being yet backward compatible), and this is the only reason why we have several event interfaces there. – Roman R. Jan 08 '15 at 13:06
  • I'll leave the comment to match the answer's change history. About the evolution, they are distinct interfaces with distinct method signatures, and as you found out, different sets of methods. I agree the methods have the same names and DISPIDs, so you might call that compatibility from a dispatching interface's point of view. As for my *mistake*, the language I used implied that one is older than the other. Alas, every numbered interface in MSHTML and WebBrowser is due to evolution. I didn't mention the newer interface appeared in IE5, but I guess this is mostly irrelevant nowadays. – acelent Jan 08 '15 at 13:42
  • Anyway, I don't want to discuss this further, I guess you're right and I'm wrong. It's your answer, not mine, I didn't even post an answer. In fact, I'll upvote your answer because it's right as it stands. – acelent Jan 08 '15 at 13:43