[webkit-qt] Road towards initial WebKit2 API for Qt 5.0

[Simon Hausmann]

Hi,

The QML WebKit 2 API in trunk is under heavy development. In various face-to-
face workshops we've had plenty of good discussions around the scope, mistakes 
to learn from WebKit1 and how we do things in the future. I'd like to  give a 
summary on some of these aspects. This may be news to some and old snow from 
yesterday for others (if you live in a place where there is snow :)

1) Levels of API

Instead of one public C++ API like in WebKit2 we'd like to try something else, 
three levels of API:

   * The API we consider stable, supported and subject to backwards 
compatibility (using qml type revisions) is QML based.

   * We have experimental QML based API that is subject to change. An 
experiment in a laboratory can succeed or it can fail, and likewise should our 
API experiments. If an API in the experimental import is a success we should 
make it public and declare it stable (move out of experimental). We have to 
yet formally define criteria here, but roughly speaking it should be a 
combination of these two:

     a) Somebody actually _needs_ the functionality in question
     b) There is evidence - for example through an actual application - that 
the API works and is right (the-way-its-mean-to-be kind).

   * We have private C++ API (the you're-on-your-own kind). Anything here  is 
never intended to go public and merely exists for example for WebKitTestRunner 
and other users who can deal with the fact that when such API changes only 
code in the WebKit repository that uses it will be adapted/fixed.


Note: I'm not against public C++ API per-se, but we don't have much of a 
playground here and so far I don't see any need to have for example 
QQuickWebView public. But who knows, perhaps we find out that for example the 
web context is something that just doesn't fit well with QML and it's better 
suited to be exposed in C++, perhaps the application code using it for example 
together with downloads would be driving that part from C++.


2) Scope and development

As a result of the above proposal for the levels we should add new APIs first 
to "experimental" and let them "cook" for a while. However we have to start 
_somewhere_, and so as the initial API for WebKit 2 in Qt 5 we should have 
something minimal that is good enough to the simple use-case for embedding a 
fully network/web/javascript-enabled component in applications. Anything 
needed beyond that should go through the "cooking" process of experimental.
This includes any functionality needed for real hybrid applications.

What we have right now is pretty close to that, so let me paste a "mock-up" of 
the current WebView API that gives us an idea of what's there:


WebView {

    property string title;
    property url url;
    property int loadProgress;

    property bool canGoBack;
    property bool canGoForward;
    property bool canStop; 
    property bool canReload;

    property Item page;

    // Not valid QML Syntax
    enum ErrorType {
        EngineError,
        NetworkError,
        HttpError,
        DownloadError
    };
 
    // Not valid QML Syntax
    enum NavigationRequestAction {
        AcceptRequest,
        IgnoreRequest,
        DownloadRequest
    };

    function goBack();
    function goForward();
    function stop();
    function reload();

    function load(url) {}
    function loadHtml(html, baseUrl) {}

    signal statusBarMessageChanged(message)
    signal loadStarted()
    signal loadSucceeded()
    signal loadFailed(errorType, errorCode, url)
    signal linkHovered(url, title)
    signal navigationRequested(request)

}

I'd like to iterate over this initial API in the coming weeks and today after 
a discussion with Laszlo we've filed a few bugs already:

    [Qt] Rename QQuickWebView::canStop property to just loading
    (https://bugs.webkit.org/show_bug.cgi?id=73813)

    [Qt] Improve QQuickWebView error handling API
    (https://bugs.webkit.org/show_bug.cgi?id=73815)

    [Qt] Extend QQuickWebview::navigationRequested API
    (https://bugs.webkit.org/show_bug.cgi?id=73818)

    [Qt] request parameter of QQuickWebView::navigationRequested is not a 
registered type
    (https://bugs.webkit.org/show_bug.cgi?id=73826)


One thing to note for example is the absence of "evaluateJavaScript". My 
feeling is that it should be asynchronous and we're lacking the code to 
properly deserialize the return value into QML's v8 based JS environment.
(The code exists in WebCore in theory, but we're not using it).

Any thoughts? Comments?


Simon