wiki:EFLHistoryApiTutorial

Foreword

This tutorial is an effect of collaboration between Samsung Poland R&D Center and Silesian Univeristy of Technology. It's a part of subject: "Writing tutorial about a WebKit-Efl API"

Author: Marcin Jabrzyk (marcin.jabrzyk [at] gmail.com)


The History API

Introduction

The ewk_history.h file is a part of WebKit's history module. It manages the browser history, in low and high level. It's closely connected to presentation layer - EWK. With use of that file the web browser made on WebKit can have a full history like any other modern browser.

Functionalities

  • Managing the history (create, clear, free the memory)
  • Provides the high level API to use history (forward, backward, get some item)
  • Provides forwards and backwards history lists with provided limits
  • Provides API to get to internal fields of history items

Logical connection diagram of Ewk History

http://i.imgur.com/aHUvt.png

Files connection diagram of Ewk History

http://i.imgur.com/SKMaY.png

The diagram is split in four major parts,

  1. EFL_Libraries - the system-global EFL libraries needed to be used. The ewk_history.h includes only Eina, Evas (there are more dependences in them)
  • libcairo is an multiplatform 2D graphics library
  • WebKit (source path)/WebCore/ group of libraries this is the main group of dependences needed to use, to provide the history funcionality
  • WebKit (source path)/efl/ewk/ group of libraries are the dependences from highest (presentation) layer.

All of this files (just need to add ".h" to each name) creates the dependences of ewk_history API.

Example of use

Here we have some very simplistic use case of EWK History API. The source code presented here is copied from EWebLauncher example browser, which is available in source code of WebKit's.

We have two examples. First is mostly low level an concerned on debug abilities, the second is a high level part which with minimal effort can be used in real world web browser.

static void
print_history(Eina_List *list)
{
    Eina_List *l;
    void *d;

    if (!verbose)
       return;

    printf("Session history contains:\n");

    EINA_LIST_FOREACH(list, l, d) {
       Ewk_History_Item *item = (Ewk_History_Item*)d;
       cairo_surface_t *cs = ewk_history_item_icon_surface_get(item);
       char buf[PATH_MAX];
       int s = snprintf(buf, sizeof(buf), "/tmp/favicon-%s.png", ewk_history_item_uri_original_get(item));
       for (s--; s >= (int)sizeof("/tmp/favicon-"); s--) {
           if (!isalnum(buf[s]) && buf[s] != '.')
               buf[s] = '_';
       }
       cs = ewk_history_item_icon_surface_get(item);

       if (cs && cairo_surface_status(cs) == CAIRO_STATUS_SUCCESS)
           cairo_surface_write_to_png(cs, buf);
       else
           buf[0] = '\0';

       printf("* '%s' title='%s' icon='%s'\n",
              ewk_history_item_uri_original_get(item),
              ewk_history_item_title_get(item), buf);
    }
}

Here we have a great example how to use EWK History API to list the whole history of our web browser. We are using here a few of functions from API:

  • ewk_history_item_icon_surface_get(Ewk_History_Item *item ) - returns a image of favicon for a history item.
  • ewk_history_item_uri_original_get(item) - returns an URI to a web page for a history item.
  • ewk_history_item_title_get(item) - returns a title of the web page

This is mostly a debug code, and it is used on that role in EWebLauncher (try run it with --verbose), but some mechanisms which can be used to make eg. a toolbar with history elemnets.

static void on_key_down(void *data, Evas *e, Evas_Object *obj, void *event_info){

[..]
    } else if (!strcmp(ev->key, "F1")) {
        info("Back (F1) was pressed\n");
        if (ewk_view_back_possible(obj)) {
            Ewk_History *history = ewk_view_history_get(obj);
            Eina_List *list = ewk_history_back_list_get(history);
            print_history(list);
            ewk_history_item_list_free(list);
            ewk_view_back(obj);
        } else
            info("Back ignored: No back history\n");
    } else if (!strcmp(ev->key, "F2")) {
        info("Forward (F2) was pressed\n");
        if (ewk_view_forward_possible(obj)) {
            Ewk_History *history = ewk_view_history_get(obj);
            Eina_List *list = ewk_history_forward_list_get(history);
            print_history(list);
            ewk_history_item_list_free(list);
            ewk_view_forward(obj);
        } else
            info("Forward ignored: No forward history\n");
[..]

Here is a second example of using a EWK History API in real world application. In EWebLauncher F1 and F2 key's have history functionalities. F1 goes 1 page back, and F2 goes forward. As you can see the use of EWK History API is very simple in that case. The API calls used:

  • ewk_view_back_possible(Evas_Object* obj), ewk_view_forward_possible(Evas_Object* obj) - returns true if its possible to go backward/forward in particular web browser session.
  • ewk_view_history_get(obj) - returns a Ewk_History structure extracted from web browser session
  • ewk_history_back_list_get(Ewk_History* history)/ewk_history_forward_list_get(Ewk_History* history) - returns a Eina_List structure from a Ewk_History - in this particular case it is used to provide a debug informations
  • ewk_history_item_list_free(Eina_List* list) - cleans a memory allocated in ewk_history_back_list_get
  • ewk_view_back(Evas_Object* obj)/ewk_view_forward(Evas_Object* obj) - changes current webpage to past or forward item

Sources

  • WebKit/Source/WebKit/efl/ewk/
  • WebKit/Tools/EWebLauncher/
Last modified 3 years ago Last modified on Jun 16, 2014 2:23:19 AM