propagating xforms events to the host app

Hi Abel,

I've not had time to write this next bit up as a proper tutorial, but hopefully the following code snippets and so on should help you get it working. If you want more information about the different event types and their arguments, I recommend inspecting DOM2Events.dll with the MS OLE/COM Object Viewer.

To fire events out of the rendered document to the host application, some script along the following lines should do the trick:

// Dispatch a simple event with no arguments.
function dispatchDOMEvent(type)
{
    var evt = new ActiveXObject("DOM2Events.DOMEvent");
    evt.initEvent(type, true, false);
    document.EventTarget.dispatchEvent(evt);

    // Returning an empty string allows the function
    // to be used on the rhs from xf:setvalue.
    return "";
}

// Dispatch an event with up to three arguments: number; number; string.
function dispatchRendererEvent(type, arg1, arg2, arg3)
{
    var evt = new ActiveXObject("Renderer.RendererEvent");
    evt.initEvent(type, true, false, arg1, arg2, arg3);
    document.EventTarget.dispatchEvent(evt);

    // Returning an empty string allows the function
    // to be used on the rhs from xf:setvalue.
    return "";
}

Then call these methods as and when you need to dispatch events up to your application. If you want to trigger this from one of formsPlayer's XForms controls, you first need to define the following namespace on the html element:

xmlns:js="http://www.formsplayer.com/inlineScript"

Then you might invoke the event dispatch like this:

<xf:trigger>
    <xf:label>
        Dispatch
    </xf:label>

    <xf:setvalue ref="/foo/bar" value="js:dispatchRendererEvent('my-event', 6, 9, '42')" />
</xf:trigger>

Obviously, if you just want to dispatch an event from vanilla HTML+JavaScript, it is not necessary to jump through this hoop.

To handle the event in your application, you'll need some code resembling the below (assuming your app is written in C#):

public void handleEvent(DOMEvent evt)
{
    switch(evt.type)
    {
        case "my-event":
            // TODO: Insert your event handling code here.
            break;
        ...
    }
}

Lastly, you need to ensure that you register as a listener for the events that you are interested in, otherwise your handleEvent() will not get called. Additionally, to ensure sane destruction of the renderer and formsPlayer, you need to unregister as a listener for those events before you call Destroy():

private void init(void)
{
    ...

    IEventTarget tgt = (IEventTarget)this.m_Renderer;
    tgt.addEventListener("my-event", (EventListener)this, 0);
}

private void destroy(void)
{
    IEventTarget tgt = (IEventTarget)this.m_Renderer;
    tgt.removeEventListener("my-event", (EventListener)this, 0);

    ...

    this.m_Renderer.Destroy();

    ...
}

That should be everything you need to know. The code above is all written from memory and has not been tested, so there may be mistakes. Let me know if you have any problems, they should be straightforward to resolve.

Cheers,
Phil.

--
Phil Booth, formsPlayer
www.formsPlayer.com
standards. innovation.