WebPageEventHandler

Since: BlackBerry 10.0.0

#include <bb/cascades/WebPageEventHandler>

A class that injects events into a WebPage.

When rendering a WebPage using a WebPageCompositor in a custom OpenGL scene, you can map screen events from the screen window coordinate system to the webpage content coordinate system depending on how the page is projected onto the screen, and inject them using this API.

This API can also be used to inject mouse and keyboard events.

You can create events using createTouchEvent().

This object can be created on any thread. However, the object has an affinity for the thread it was created on, and may not be used on any other thread.

Note:

Events are handled asynchronously, please refer to handleEvent(Event*) and eventHandled(Event*) for more detailed information.

An example of multi-threaded use is as follows:
class ScreenThread : public QThread {
    Q_OBJECT

public:
    void run();

Q_SIGNALS:
    void touch(int eventType, int sourceX, int sourceY /*, ... */);

};
void ScreenThread::run()
{
    // Screen initialization
    // ...

    screen_event_t event;
    int eventType;
    screen_create_event(&event);

    while (true) {
        // screen_get_event(...);
        screen_get_event_property_iv(event, SCREEN_PROPERTY_TYPE, &eventType);
        // ...
        switch (eventType) {
        // ...
        case SCREEN_EVENT_MTOUCH_TOUCH:
        case SCREEN_EVENT_MTOUCH_RELEASE:
        case SCREEN_EVENT_MTOUCH_MOVE: {
            int sourcePosition[2];
            screen_get_event_property_iv(event, SCREEN_PROPERTY_SOURCE_POSITION, sourcePosition);
            // ...
            emit touch(eventType, sourcePosition[0], sourcePosition[1] /*, ...*/);
            break;
        }
        // ...
        }
    }
}
class MyThread : public QThread {
    Q_OBJECT

public:
    void run();

public Q_SLOTS:
    void onWebPageInitialized(const QString&);
    void onTouch(int eventType, int sourceX, int sourceY /*, ... */);

private Q_SLOTS:
    void onEventHandled(Event* event);

private:
    WebPageEventHandler* m_eventHandler;
};
void MyThread::run()
{
    // Screen initialization
    // ...

    // Create event handler
    m_eventHandler = new WebPageEventHandler();
    QObject::connect(m_eventHandler, SIGNAL(eventHandled(Event*)), this, SLOT(onEventHandled(Event*)));

    exec();
 }

void MyThread::onWebPageInitialized(const QString& uniqueId)
{
    m_eventHandler->connectToWebPage(uniqueId);
}

void MyThread::onTouch(int eventType, int sourceX, int sourceY /*, ... */) {
    Event* touchEvent = m_eventHandler->createTouchEvent(eventType);

    // Map sourceX, sourceY to web page viewable area coordinate system depending on where the web page is
    // displayed inside the screen window.
    // For the purpose of this code sample, let's assume that the web page is displayed in the top left
    // corner of the screen window, at 1:1 scale.
    int localX = sourceX;
    int localY = sourceY;
    int screenX;
    int screenY;
    int id;
    int pressure;
    int orientation;
    int sequenceId;
    long long timestamp;

    // Set parameters
    // ...

    m_eventHandler->addTouchPoint(touchEvent, localX, localY, screenX, screenY, id, pressure, orientation, sequenceId, timestamp);

    m_eventHandler->handleEvent(touchEvent);
}

void MyThread::onEventHandled(Event* event)
{
    delete event;
}
int main(int argc, char **argv)
{
    // Main thread
    Application app(argc, argv);

    ScreenThread* screenThread = new ScreenThread;

    MyThread* thread = new MyThread;

    // This will change the thread affinity for the QThread object itself so connections
    // to its slots use a queued connection if necessary to make sure the slot will execute
    // on the right thread.
    thread->moveToThread(thread);

    WebPage* webPage = new WebPage();

    QObject::connect(screenThread, SIGNAL(touch(int, int, int)), thread, SLOT(onTouch(int, int, int)));
    QObject::connect(webPage, SIGNAL(initialized(const QString&)), thread, SLOT(onWebPageInitialized(const QString&)));

    screenThread->start();
    thread->start();

    webPage->setUrl(QUrl("http://www.example.com"));

    return Application::exec();
}
WebPageCompositor is normally used from C++, but here is an example of using WebPageCompositor in QML:
import WebPageComponent 1.0

Page {
    Container {
        //      ...
        onTouch: {
            eventHandler.handleEvent(event);
        }

        touchBehaviors: [
            TouchBehavior {
                TouchReaction {
                    eventType: TouchType.Down
                    phase: PropagationPhase.AtTarget
                    response: TouchResponse.StartTracking
                }
            }
        ]
        //     ...
        attachedObjects: [
            WebPage {
                id: page
                url: "http://www.example.com"
                onInitialized: {
                    eventHandler.connectToWebPage(uniqueId);
                }
            },
            WebPageEventHandler {
                id:eventHandler
            }
        ]
    }
}
Add the following lines to the C++ main program to register WebPageCompositor:
qmlRegisterType<bb::cascades::WebPage>("WebPageComponent", 1, 0,"WebPage");
qmlRegisterType<bb::cascades::WebPageEventHandler>("WebPageComponent", 1, 0,"WebPageEventHandler");


Overview

Public Functions Index

WebPageEventHandler (QObject *parent=0)
virtual ~WebPageEventHandler ()
Q_INVOKABLE voidaddTouchPoint (bb::cascades::Event *, int localX, int localY, int screenX, int screenY, int id, int pressure, int orientation, int sequenceId, long long timestamp) const
Q_INVOKABLE bb::cascades::Event *createKeyEvent (int scan, int sym, int cap, int flags, int modifiers, int sequenceId, long long timestamp) const
Q_INVOKABLE bb::cascades::Event *createMouseEvent (int buttonState, int localX, int localY, int screenX, int screenY, int wheelDelta, int wheelTicks) const
Q_INVOKABLE bb::cascades::Event *createTouchEvent (int touchType) const

Public Slots Index

voidconnectToWebPage (const QString &uniqueId)
voidhandleEvent (bb::cascades::Event *event)
voidsetKeyboardFocus (bool focus)

Signals Index

voidconnectionFailed ()
voidconnectionSucceeded ()
voideventHandled (bb::cascades::Event *event)
voidkeyboardHideRequested ()
voidkeyboardShowRequested (int layout, int enterKey)

Public Functions

WebPageEventHandler (

Constructs a WebPageEventHandler.

See also:

connectToWebPage(const QString&).

Parameters
parent

Optional parent for this object.

Since:

BlackBerry 10.0.0

virtual~WebPageEventHandler ()

Destructor.

Q_INVOKABLE void addTouchPoint (
  • bb::cascades::Event *,
  • intlocalX,
  • intlocalY,
  • intscreenX,
  • intscreenY,
  • intid,
  • intpressure,
  • intorientation,
  • intsequenceId,
  • long longtimestamp )

Adds a touch point to a touch event.

TouchType::Down and Up typically only have one touch point associated.

For TouchType::Move one or more fingers that moved may be grouped together into one event by adding multiple touch points, to reduce the number of events the webpage has to process.

TouchType::Cancel events can't have any touch points.

The parameters match those provided by the screen for screen_event_t instances of type SCREEN_EVENT_MTOUCH_TOUCH, MOVE or RELEASE. The definitions of these values are found in screen/screen.h.

The position of the screen event needs to be converted to the webpage viewable area before passing it as the localX and localY parameters of this method. Initially, the viewable area of the webpage is positioned at (0, 0) and the webpage uses an 1:1 scale, so conversion to the webpage viewable area coordinate system is straight forward. However, if a WebPageCompositor has been connected to the WebPage, the viewable area of the webpage may have been changed using the compositor APIs and the application is responsible for mapping the screen coordinates to the currently viewable area. This mapping also depends on where the web page is rendered relative to the screen window that received the original screen event.

Parameters
localX

Corresponds to SCREEN_PROPERTY_SOURCE_POSITION, mapped to the webpage viewable area coordinate system.

localY

Corresponds to SCREEN_PROPERTY_SOURCE_POSITION, mapped to the webpage viewable area coordinate system.

screenX

Corresponds to SCREEN_PROPERTY_POSITION.

screenY

Corresponds to SCREEN_PROPERTY_POSITION.

id

Corresponds to SCREEN_PROPERTY_TOUCH_ID.

pressure

Corresponds to SCREEN_PROPERTY_TOUCH_PRESSURE.

orientation

Corresponds to SCREEN_PROPERTY_TOUCH_ORIENTATION.

sequenceId

Corresponds to SCREEN_PROPERTY_SEQUENCE_ID.

timestamp

Corresponds to SCREEN_PROPERTY_TIMESTAMP.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::Event * createKeyEvent (
  • intscan,
  • intsym,
  • intcap,
  • intflags,
  • intmodifiers,
  • intsequenceId,
  • long longtimestamp )

Creates a key event.

The event returned can be injected using handleEvent(Event*) when the app receives a screen_event_t of type SCREEN_EVENT_KEYBOARD. The definitions of these values are found in screen/screen.h.

Parameters
scan

Corresponds to SCREEN_PROPERTY_KEY_SCAN.

sym

Corresponds to SCREEN_PROPERTY_KEY_SYM.

cap

Corresponds to SCREEN_PROPERTY_KEY_CAP.

flags

Corresponds to SCREEN_PROPERTY_KEY_FLAGS.

modifiers

Corresponds to SCREEN_PROPERTY_KEY_MODIFIERS.

sequenceId

Corresponds to SCREEN_PROPERTY_SEQUENCE_ID.

timestamp

Corresponds to SCREEN_PROPERTY_TIMESTAMP.

Return:

An Event representing a key event. Ownership of the event is transferred to the caller.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::Event * createMouseEvent (
  • intbuttonState,
  • intlocalX,
  • intlocalY,
  • intscreenX,
  • intscreenY,
  • intwheelDelta,
  • intwheelTicks )

Creates a mouse event.

The event returned can be injected using handleEvent(Event*) when the app receives a screen_event_t of type SCREEN_EVENT_POINTER. The definitions of these values are found in screen/screen.h.

The position of the screen event needs to be converted to the webpage viewable area before passing it as the localX and localY parameters of this method. Initially, the viewable area of the webpage is positioned at (0, 0) and the webpage uses an 1:1 scale, so conversion to the webpage viewable area coordinate system is straight forward. However, if a WebPageCompositor has been connected to the WebPage, the viewable area of the webpage may have been changed using the compositor APIs and the application is responsible for mapping the screen coordinates to the currently viewable area. This mapping also depends on where the web page is rendered relative to the screen window that received the original screen event.

Parameters
buttonState

Corresponds to SCREEN_PROPERTY_BUTTONS.

localX

Corresponds to SCREEN_PROPERTY_SOURCE_POSITION, mapped to the webpage viewable area coordinate system.

localY

Corresponds to SCREEN_PROPERTY_SOURCE_POSITION, mapped to the webpage viewable area coordinate system.

screenX

Corresponds to SCREEN_PROPERTY_POSITION.

screenY

Corresponds to SCREEN_PROPERTY_POSITION.

wheelDelta

wheelTicks converted to a number of pixels the webpage should scroll when it receives a wheel event.

wheelTicks

Corresponds to SCREEN_PROPERTY_MOUSE_WHEEL.

Return:

An Event representing a mouse event. Ownership of the event is transferred to the caller.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bb::cascades::Event * createTouchEvent (
  • inttouchType)

Creates a touch event.

The event returned can be injected using handleEvent(Event*) when the app receives a screen_event_t of type SCREEN_EVENT_MTOUCH_TOUCH, MOVE or RELEASE.

You can add touch points to the event using c addTouchPoint().

TouchType::Down, Move, and Up events correspond to SCREEN_EVENT_MTOUCH_TOUCH, MOVE or RELEASE, respectively.

TouchType::Cancel events are used in situations where an Up event will never come, for example when the app decides to stop sending events for an ongoing touch interaction and instead handle the rest of the sequence without any involvement of the webpage.

An example can clarify this. Consider a scenario where touch events are used to interact with the webpage, but also used to scroll the webpage. A touch move should first be sent to handleEvent(Event*), and the caller should wait for eventHandled() signal to be emitted. If the finger moves a certain distance from the touch down point, the app may want to start scrolling instead. The webpage will expect the sequence to complete, and a Cancel event should be injected to accomplish that.

See also:

addTouchPoint().

Parameters
touchType

A member of the TouchType::Type enum, or SCREEN_EVENT_MTOUCH_TOUCH, MOVE or RELEASE.

Return:

An Event representing a touch event. Ownership of the event is transferred to the caller.

Since:

BlackBerry 10.0.0

Public Slots

void connectToWebPage (

Connects to a WebPage created on the main thread.

Since:

BlackBerry 10.0.0

void handleEvent (

Injects a touch, mouse or key event into the connected WebPage.

The event to handle can be a specialized event created using createTouchEvent(), createMouseEvent() or createKeyEvent(). It can also be a TouchEvent.

The event is handled asynchronously. The WebPageEventHandler does not assume ownership of the event, but the event must not be deleted until the eventHandled() signal is emitted for the event.

If the event is accepted, the QEvent::isAccepted() flag will be set on the event and you can check the status of that flag in a slot connected to eventHandled() signal.

An example can clarify this. Consider a scenario where touch events are used to interact with the webpage, but also used to scroll the webpage. A touch move should first be sent to handleEvent(Event*), and the caller should wait for the eventHandled() signal to be emitted. Then the QEvent::isAccepted() flag should be checked. If it's found that the event is accepted, any default action associated with the event, in this case scrolling, should not be performed. Otherwise, go ahead and call WebPageCompositor::scrollToPoint() to scroll the webpage.

Parameters
event

An Event created using createTouchEvent(), createMouseEvent(), createKeyEvent() or a TouchEvent.

Since:

BlackBerry 10.0.0

void setKeyboardFocus (
  • boolfocus)

Assigns keyboard focus to the connected WebPage.

Since:

BlackBerry 10.0.0

Signals

void connectionFailed ()

Emitted when connection failed.

Since:

BlackBerry 10.0.0

void connectionSucceeded ()

Emitted when successfully connected to a webpage.

Since:

BlackBerry 10.0.0

void eventHandled (

Emitted asynchronously when the connected WebPage finishes processing an event previously injected by calling handleEvent(Event*).

At a minimum, a slot connected to this signal should delete the event.

Example slot implementation:

void MyClass::onEventHandled(Event* event)
{
    if (event->isAccepted()) {
        // Prevent any default action the app would otherwise take, like scrolling
        // ...
    }
    delete event;
}
Since:

BlackBerry 10.0.0

void keyboardHideRequested ()

Emitted when interaction with the webpage causes it to request the virtual keyboard to be hidden.

Since:

BlackBerry 10.0.0

void keyboardShowRequested (
  • intlayout,
  • intenterKey )

Emitted when interaction with the webpage causes it to request the virtual keyboard to be shown.

Parameters
layout

One of the virtualkeyboard_layout_t values from bps/virtualkeyboard.h.

enterKey

One of the virtualkeyboard_enter_t value from bps/virtualkeyboard.h.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus