source: trunk/src/3rdparty/webkit/WebKit/qt/docs/qtwebkit-bridge.qdoc@ 846

/*!
    \inmodule QtWebKit
    \page qtwebkit-bridge.html
    \title The QtWebKit Bridge
    \contentspage QtWebKit
    \section1 Overview
    \section2 The technology

    The QtWebKit bridge is a mechanism that extends WebKit's JavaScript environment to access native
    objects that are represented as \l{QObject}s. It takes advantage of the \l{QObject} introspection,
    a part of the \l{Object Model}, which makes it easy to integrate with the dynamic JavaScript environment,
    for example \l{QObject} properties map directly to JavaScript properties.

    For example, both JavaScript and QObjects have properties: a construct that represent a getter/setter
    pair under one name.

    \section2 Use Cases

    There are two main use cases for the QtWebKit bridge. Web content in a native application, and Thin Clients.

    \section3 Web Content in a Native Application

    This is a common use case in classic Qt application, and a design pattern used by several modern
    applications. For example, an application that contains a media-player, playlist manager, and music store.
    The playlist manager is usually best authored as a classic desktop application,
    with the native-looking robust \l{QWidget}s helping with producing that application.
    The media-player control, which usually looks custom, can be written using the \l{Graphics View framework}
    or with in a declarative way with \l{QtDeclarative}. The music store, which shows dynamic content
    from the internet and gets modified rapidly, is best authored in HTML and maintained on the server.

    With the QtWebKit bridge, that music store component can interact with native parts of the application,
    for example, if a file needs to be saved to a specific location.

    \section3 Thin Client

    Another use case is using Qt as a native backend to a full web application,
    referred to here as a thin client. In this use-case, the entire UI is driven by
    HTML, JavaScript and CSS, and native Qt-based components are used to allow that application
    access to native features not usually exposed to the web, or to enable helper components that
    are best written with C++.

    An example for such a client is a UI for a video-on-demand service on a TV. The entire content and
    UI can be kept on the server, served dynamically through HTTP and rendered with WebKit, with additional
    native components for accessing hardware-specific features like extracting the list of images
    out of the video.

    \section2 Difference from Other Bridge Technologies

    Of course QtWebKit is not the only bridge technology out there. NPAPI, for example,
    is a long-time standard or web-native bridging. Due to Qt's meta-object system, full applications
    built partially with web-technologies are much easier to develop. NPAPI, however, is more geared
    towards cross-browser plugins, due to it being an accepted standard.

    When developing a plugin for a browser, NPAPI is recommended. When developing a full application
    that utilizes HTML-rendering, the QtWebKit bridge is recommended.

    \section2 Relationship with QtScript

    The QtWebKit bridge is similar to \l{QtScript}, especially to some of the features described in the
    \l{Making Applications Scriptable} page. However, as of Qt 4.7, full QtScript API is not supported for web applications.
    That is planned as an enhancement for future versions. You might notice that some of the features
    described here are an exact copy of the ones described in the \l{Making Applications Scriptable} page. That is because
    the QtWebKit bridge is a subset of that functionality, and this page tries to capture the full
    capabilities available through the QtWebKit bridge specifically.

    \section1 Accessing QObjects

    \section2 Creating the link via QWebFrame

    By default, no QObjects are accessible through the web environment, for security reasons.
    To enable web content access for a native QObject, the application must explicitly grant it access,
    using the following call:

    \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 0

    See \l{QWebFrame::addToJavaScriptWindowObject()} for more information.

    \section2 Using Signals and Slots

    The QtWebKit bridge adapts Qt's central \l{Signals and Slots} feature for