WebPageCompositor

Since: BlackBerry 10.0.0

#include <bb/cascades/WebPageCompositor>

A class that composites the internal scene graph of a WebPage.

The scene graph must be composited to a render target. Currently, an OpenGL texture can be used as the target. The texture can then be used in custom OpenGL rendering code to render the webpage as part of an OpenGL scene. See WebPageTexture for more information.

In addition to the web content, injected user input events may cause the webpage to have overlays. These include selection handles, fine cursor control handles, and other overlays. These can optionally be included in the output of the WebPageCompositor.

All operations on a WebPageCompositor are asynchronous, including rendering.

The WebPageCompositor API is very similar to that of ScrollView. Since it is a Control, the ScrollView has a size that it can use as a basis for contentScale and viewableArea calculations. The WebPageCompositor is not part of a layout system that adjusts its size like controls do, instead it has a viewport size that is set directly using setViewportSize(). The viewport size is used as a basis for contentScale and viewableArea calculations, and is typically set to the same size as the WebPageTexture used as the render target.

The viewable area of the page can be composited to a texture by calling renderToTexture(). If you want to include overlays in the rendering output, call renderToTexture(). Use scrollToPoint(), zoomToPoint(), and zoomToRect() to manage the viewable area.

When the webpage appearance changes, repaintRequested() is emitted. In a connected slot, the app should call renderToTexture(). When rendering is done, the texture emits the WebPageTexture::textureChanged() signal, which indicates that the texture is ready to be rendered using custom OpenGL code.

An instance of WebPageEventHandler can be used to inject input events to the webpage, and thus allow interaction with the web content. As a result of interaction, the webpage may request scrolling or zooming to take place by emitting scrollRequested() and zoomRequested(). The app can animate these transitions, or simply call scrollToPoint() or zoomToPoint() directly.

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.

See also:

WebPage, which represents a webpage that can be composited by this class.

,

WebPageTexture, which represents a texture that can be used as a render target when compositing.

,

WebPageEventHandler, which can be used to inject user input events to the webpage.

Example of multi-threaded use:
class MyThread : public QThread {
    Q_OBJECT

public:
    void run();

public Q_SLOTS:
    void onWebPageInitialized(const QString&);

private Q_SLOTS:
    void onRepaintRequested();
    void renderScene();

private:
    WebPageCompositor* m_compositor;
    WebPageTexture* m_texture;
};
void MyThread::run()
{
    // OpenGL initialization
    // ...
    // eglMakeCurrent(...);

    // Create compositor and texture
    m_compositor = new WebPageCompositor();
    QObject::connect(m_compositor,
            SIGNAL(repaintRequested()),
            this,
            SLOT(onRepaintRequested()));
    m_texture = new WebPageTexture(QSize(512, 512));
    QObject::connect(m_texture,
            SIGNAL(textureChanged()),
            this,
            SLOT(renderScene()));
    exec();
 }

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

void MyThread::onRepaintRequested() {
    m_compositor->renderToTexture(m_texture);
}

void MyThread::renderScene() {
    // eglMakeCurrent(...);
    glBindTexture(GL_TEXTURE_2D, m_texture->textureId());
    // ...
    // eglSwapBuffers(...);
}
 int main(int argc, char **argv)
{
    Application app(argc, argv);

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

    thread->start();

    WebPage* webPage = new WebPage();
    QObject::connect(webPage,
                     SIGNAL(initialized(const QString&)),
                     thread,
                     SLOT(onWebPageInitialized(const QString&)));
    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 {
    // ...
    attachedObjects: [
        WebPage {
            id: page
            url: "http://www.example.com"
            onInitialized: {
                compositor.connectToWebPage(uniqueId);
                compositor.renderToTexture(texture);
            }
        },
        WebPageCompositor {
            id: compositor
            onRepaintRequested: {
                renderToTexture(texture);
            }
        },
        WebPageTexture {
            id: texture
            size: Qt.size(512, 512)
            onTextureChanged: {
                // Call native code to render the texture using OpenGL
            }
        }
    ]
}
Add the following lines to the C++ main program to register WebPageCompositor:
qmlRegisterType<bb::cascades::WebPage>("WebPageComponent", 1, 0,"WebPage");
qmlRegisterType<bb::cascades::WebPageCompositor>("WebPageComponent", 1, 0,"WebPageCompositor");
qmlRegisterType<bb::cascades::WebPageTexture>("WebPageComponent", 1, 0,"WebPageTexture");


Overview

QML properties

contentScale: double [read-only]
contentSize: QSize [read-only]
regionOfInterest: QRectF [read-only]
viewableArea: QRectF [read-only]
viewportSize: QSize

Properties Index

Public Functions Index

WebPageCompositor (QObject *parent=0)
virtual ~WebPageCompositor ()
doublecontentScale () const
QSizecontentSize () const
QRectFregionOfInterest () const
Q_INVOKABLE voidrenderToTexture (bb::cascades::WebPageTexture *texture, bool includeOverlays=false)
QRectFviewableArea () const
QSizeviewportSize () const

Public Slots Index

voidconnectToWebPage (const QString &uniqueId)
voidresetViewableArea ()
voidscrollToPoint (float x, float y)
voidsetViewportSize (const QSize &size)
voidzoomToPoint (float x, float y, double contentScale)
voidzoomToRect (const QRectF &rect)

Signals Index

voidconnectionFailed ()
voidconnectionSucceeded ()
voidcontentScaleChanged (double newContentScale)
voidcontentSizeChanged (const QSize &newContentSize)
voidregionOfInterestChanged (const QRectF &newRegionOfInterest) const
voidrepaintRequested ()
voidscrollRequested (float x, float y)
voidviewableAreaChanged (const QRectF &newViewableArea, double newContentScale)
voidviewportSizeChanged (const QSize &newViewportSize)
voidzoomRequested (float x, float y, double contentScale)

Properties

double contentScale[read-only]

The scale used when rasterizing the webpage, to increase the detail level of text and vector graphics.

Since:

BlackBerry 10.0.0

QSize contentSize[read-only]

The size of the entire webpage.

Since:

BlackBerry 10.0.0

QRectF regionOfInterest[read-only]

A part of the webpage that should be kept visible, for example, due to text input.

Since:

BlackBerry 10.0.0

QRectF viewableArea[read-only]

The area which is currently being shown in the viewport.

Since:

BlackBerry 10.0.0

QSize viewportSize

The size of the viewport.

The viewport size is typically set to the same size as the WebPageTexture used as the render target.

However, the actual size of the render target is decoupled from the logical viewport size used by the WebPageCompositor in its calculations.

Since:

BlackBerry 10.0.0

Public Functions

WebPageCompositor (

Constructs a WebPageCompositor.

The WebPageCompositor must be connected to a WebPage before any methods can be called on it.

Parameters
parent

Optional parent for this object.

Since:

BlackBerry 10.0.0

virtual~WebPageCompositor ()

Destructor.

double contentScale ()

Gets the scale used when rasterizing the webpage, to increase the detail level of text and vector graphics.

Return:

The scale used when rasterizing the webpage.

Since:

BlackBerry 10.0.0

QSize contentSize ()

Gets the size of the webpage.

Return:

The size of the entire webpage.

Since:

BlackBerry 10.0.0

QRectF regionOfInterest ()

Gets the area of the webpage that should be kept visible.

For example, the region of interest changes during text input to indicate where text is being inserted on the webpage, so the application can scroll the webpage to make the text visible.

If there currently is no region of interest, an empty rectangle is returned.

Return:

A part of the webpage that should be kept visible.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void renderToTexture (

Renders part of the webpage to the entire texture based on the current viewable area.

The texture will be cleared to the color specified by WebSettings::background() before rendering.

In addition to the web content, injected user input events may cause the webpage to have overlays. These include selection handles, fine cursor control handles, and other overlays.

If you want to render a thumbnail of the webpage, you can leave out the overlays.

Parameters
texture

An instance of WebPageTexture representing the texture to use as render target.

includeOverlays

Whether to include overlays.

Since:

BlackBerry 10.0.0

QRectF viewableArea ()

Gets the viewable area of the webpage.

Return:

The viewable area.

Since:

BlackBerry 10.0.0

QSize viewportSize ()

Gets the size of the viewport.

Return:

The viewport size.

Since:

BlackBerry 10.0.0

Public Slots

void connectToWebPage (

Connects to a WebPage created on the main thread.

Since:

BlackBerry 10.0.0

void resetViewableArea ()

Resets the content scale to 1.0 and resets the viewable area to a rectangle located at 0, 0 and with a size equal to the viewport size.

Since:

BlackBerry 10.0.0

void scrollToPoint (
  • floatx,
  • floaty )

Moves the viewable area to the specified position.

Parameters
x

The new x coordinate of the viewable area.

y

The new y coordinate of the viewable area.

Since:

BlackBerry 10.0.0

void setViewportSize (

Sets the size of the viewport.

The viewport size is typically set to the same size as the WebPageTexture used as the render target.

Parameters
size

The new viewport size.

Since:

BlackBerry 10.0.0

void zoomToPoint (
  • floatx,
  • floaty,
  • doublecontentScale )

Moves the center of the viewable area to the specified position, and adjusts the scale.

If the scale changed, the size of the viewable area is updated accordingly.

Parameters
x

The new x coordinate of the viewable area.

y

The new y coordinate of the viewable area.

contentScale

The new scale.

Since:

BlackBerry 10.0.0

void zoomToRect (

Sets the viewable area to the specified rectangle.

If the size of the viewable area changed, the scale is updated accordingly.

Parameters
rect

The new viewable area.

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 contentScaleChanged (
  • doublenewContentScale)

Emitted when the content scale changes.

Since:

BlackBerry 10.0.0

void contentSizeChanged (
  • const QSize &newContentSize)

Emitted when the content size changes.

Since:

BlackBerry 10.0.0

void regionOfInterestChanged (
  • const QRectF &newRegionOfInterest)

Emitted when the region of interest changes.

Since:

BlackBerry 10.0.0

void repaintRequested ()

Emitted when the appearance of the webpage changes.

A slot connected to this signal will typically call renderToTexture().

Since:

BlackBerry 10.0.0

void scrollRequested (
  • floatx,
  • floaty )

Emitted when the webpage wants to scroll to a new position.

This signal can be emitted due to interaction with the webpage, or JavaScript code executing on the webpage.

You can perform a smooth animation to the new scroll position, or simply jump to the new position.

Parameters
x

The new top left corner of the viewable area.

y

The new top left corner of the viewable area.

Since:

BlackBerry 10.0.0

void viewableAreaChanged (
  • const QRectF &newViewableArea,
  • doublenewContentScale )

Emitted when the viewable area changes.

Since:

BlackBerry 10.0.0

void viewportSizeChanged (
  • const QSize &newViewportSize)

Emitted when the viewport size changes.

Since:

BlackBerry 10.0.0

void zoomRequested (
  • floatx,
  • floaty,
  • doublecontentScale )

Emitted when the webpage wants to scroll to a new position.

This signal can be emitted due to interaction with the webpage.

You can perform a smooth animation to the new scroll position and scale, or simply jump there.

Parameters
x

The new center of the viewable area.

y

The new center of the viewable area.

contentScale

The new content scale.

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