OWBAL Porting Guide

  1. Doduo
    1. Types
    2. High level API
      1. a basic main implementation
      2. WebViewPrivate implementation
    3. WKAL implementation
      1. Events
      2. Fonts
      3. Graphics
      4. Network
      5. Widgets
    4. OWBAL implementation
      1. Database
      2. FileSystem
      3. Image decoder
      4. Internationalization
      5. Media
      6. Threads
      7. Timers
    5. Plugins (NPAPI) implementation
    6. Integrate your port into CMake …
    7. Support
  2. pre-Doduo release

Doduo

Doduo porting guide is currently not complete so there are missing part which will be added soon. Good wills are always welcome to help.

Types

In Doduo release one of the most important file is BAL/Base/MyPort/BALTypeMyPort.h. This file must be filled to make your structure/Class match OWBAL/WKAL/WebCore structure. A typical example is if you want to do a graphics DirectFB implementation, then you will have to create `BAL/Base/DirectFB/BALTypeDirectFB.h file and define in your file something like: 

typedef DFBRectangle BalRectangle;
typedef IDirectFBSurface PlatformGraphicsContext;

This is an example so this code is incomplete, and you have to set other types to archieve a full DirectFB implementation.

High level API

This part covers high level API implementation. It means that it will describe how your browser application will interact with webkit library to render a web page.
This section is only focused on a basic implementation. It will not teach you how to implement bookmark/history management or things like that. If you want more information about such features, just have a look at our high level API.

a basic main implementation

First you have to create WebKitTools/OWBLauncher/Myport/main.cpp file. Just have a look at what is done elsewhere, for example in WebKitTools/OWBLauncher/SDL/main.cpp, to have an idea of what must be done.
The primary goal is to create a graphics surface and the pass it to the webView so at this point you should be able to display an empty window.
Note for Blastoise developers: main() is now responsible to graphics initialization. So Doduo main() should include a code which is quite similar to what was done in BCGraphicsDeviceSDL::initialize() in Blastoise release. This way to proceed is more flexible as any application can initialize a surface and then use WebKit facilities to render a web page inside it.
You will also have to have a main loop to dispatch events to the webView and send your events to the following set of methods:

  • void onExpose(BalEventExpose)

Expose event is mandatory. Without such events, you will not be able to refresh your page. If your event (or graphics) library does not provide such facilities, you can use an observer design pattern.

  • void onKeyDown(BalEventKey)
  • void onKeyUp(BalEventKey)

These 2 methods are used for keyboard management.

  • void onMouseMotion(BalEventMotion)
  • void onMouseButtonDown(BalEventButton)
  • void onMouseButtonUp(BalEventButton)
  • void onScroll(BalEventScroll)

These 4 methods are used to manage mouse events.

  • void onResize(BalResizeEvent)

This method is optional. I mean it is only useful if you target to resize your webview.

  • void onQuit(BalQuitEvent)

This method is also optional. It is only useful if you have to de-intialize specific things.

  • void onUserEvent(BalUserEvent)

This method is only useful if you have specific events which can not be handled by the previous methods.

WebViewPrivate implementation

WebViewPrivate is useful to implement specific part in WebView. As a matter of fact a GTK port will not manage events the same way than a SDL port. That's why a WebViewPrivate has been created.
In this file, you just have to implement previous event methods:

  • void onExpose(BalEventExpose)

This method simply does the page layout if needed and then paint the region to update. In an ideal implementation BalEventExpose may contain the dirty region to update. If that is not the case, you can always use dirtyRegion which you should have set to the correct value in the widget implementation part.

  • void onKeyDown(BalEventKey)
  • void onKeyUp(BalEventKey)

Basicly these methods simply send events to WebCore event handler. Nonetheless you may want to bind here some specific key to some specific action. For example, you can bind Escape key to a quit event: 

switch (event.key) {
case Escape_key:
    BalEventQuit ev;
    //fill quit event
    view->onQuit(ev);
    return;
}

Another worthy point of view may be to say, as event loop is in my application, I will bind key to specific WebKit actions in my event loop.

  • void onMouseMotion(BalEventMotion)
  • void onMouseButtonDown(BalEventButton)
  • void onMouseButtonUp(BalEventButton)
  • void onScroll(BalEventScroll)

For mouse events, you just have to forward them to WebCore event handler.

  • void onResize(BalResizeEvent)

Implementation to resize your WebView.

  • void onQuit(BalQuitEvent)

Specific things to do before quitting. For example you can save current page and then display this page on next restart.

  • void onUserEvent(BalUserEvent)

This implementation depends on how you defined a user event.

WKAL implementation

Events

To implement events, you just have to fill BCPlatformKeyboardEventMyport.cpp, BCPlatformMouseEventMyport.cpp and BCPlatformMouseWheelEventMyport.cpp in your BAL/WKAL/Concretizations/Events/MyPort directory. The main idea is to translate your events into WebCore events.
For keyboard events, have a look at KeyboardCodes.h to know matching keycode.
A common mistake in mouse event implementation is to forget to increase click count when a mouse button down occurs.

Fonts

Fonts implementation is really a complex part, if you do not have some background read at least this page to know basis.
Font implementation is required even if you do not draw font. I mean even if you do not implement everything i.e. methods like Font::drawGlyph() which is only used to draw glyphs. Be warned that if you do not implement fonts, you may get some segfaults due to some ASSERTION FAILED. To complete...

Graphics

Graphics context

The most important in Graphics is of course GraphicsContext implementation. (To complete...)
A very helpful implementation is BCIntRectMyPort.cpp which will allow you to do a direct implicit conversion between a BalRectangle, defined in your BAL/Base/MyPort/BALTypesMyPort.h file, and a WebCore::IntRect.

Display decoded image

The next sensitive part is about image drawing.
First you need to do modifications in BCImageSourceMyPort.cpp in method ImageSource::createFrameAtIndex() to create a NativeImagePtr from a RGBA32Buffer. NativeImagePtr is in fact a BalSurface. So you have to set a specific type for BalSurface in your BAL/Base/MyPort/BALTypesMyPort.h file.
Then you just have to implement BCImageMyPort.cpp file. The important methods are:

  • BitmapImage::BitmapImage() which is the constructor. It stores information about decoded image.
  • BitmapImage::draw() which simply draws a decoded image.
  • Image::drawPattern() which draws a part of an image. A good test to know wether this method is correctly implemented is http://www.deviantart.com/. If the rendering is ok, it means that drawPattern is probably good. Nonetheless it does not certify that the whole drawPattern implementation is ok.

From this point, if everything is implemented correctly, you should be able to display images correctly with a progressive decoding. If you want to get rid of progressive and want for a reason or another only display images when all image data are received and decoded, you can modify ImageSource::setData() method by doing a modification like this: 

if (allDataReceived)
    m_decoder->setData(data, allDataReceived);

Network

To complete...

Widgets

OWBAL implementation

Database

This implementation is optional. It is only required if you want to enable some HTML5 features.

FileSystem

Image decoder

Internationalization

Media

This implementation is optional. It is only required if you want to enable HTML5 video tag feature.

Threads

Timers

Plugins (NPAPI) implementation

Preliminary note: This part is not easy if you do not want a Gtk+ dependency. As a matter of fact, some plugins like Flash plugin from Adobe have a direct dependency to gtk+ (see this link if you do not believe me).

Integrate your port into CMake build

To be done. A huge CMake refactoring is planned, so this part will not be documented before this refactoring is done.

Support

Pleyo supports customers in optimized porting. Don't hesitate to contact them

pre-Doduo release

The following information are outdated since they are mostly related to Blastoise and RP2 releases. However, you may find here some useful information

Quick introduction to OWBAL :

  • where does it come from
  • how is it structured
  • level of abstraction choice, change log
  • implementation choice (virtual class)

Who is this guide aimed to?

  • Embedded systems developers, no C++ knowledge required
  • People needing to estimate the cost of OWBAL on their systems

The document is available in two formats. The current version is the "RP2".

Attachments