Changes between Initial Version and Version 1 of EFLHistoryApiTutorial


Ignore:
Timestamp:
Sep 19, 2012 2:04:06 AM (10 years ago)
Author:
marcin.jabrzyk@gmail.com
Comment:

Initial version of the page.

Legend:

Unmodified
Added
Removed
Modified
  • EFLHistoryApiTutorial

    v1 v1  
     1----
     2
     3== Foreword ==
     4 
     5This tutorial is an effect of collaboration between Samsung Poland R&D Center and Silesian Univeristy of Technology.
     6It's a part of subject:  "Writing tutorial about a WebKit-Efl API"
     7
     8Author: Marcin Jabrzyk (marcin.jabrzyk [at] gmail.com)
     9
     10----
     11
     12== The History API ==
     13
     14
     15=== Introduction ===
     16The '''ewk_histroy.h''' file is a part of WebKit's history module.
     17It manages the browser history, in low and high level. It's closely
     18connected to presentation layer - EWK.
     19With use of that file the web browser made on WebKit can have a full history like any other modern browser.
     20
     21== Functionalities ==
     22* Managing the history (create, clear, free the memory)
     23* Provides the high level API to use history (forward, backward, get some item)
     24* Provides forwards and backwards history lists with provided limits
     25* Provides API to get to internal fields of history items
     26
     27== Logical connection diagram of Ewk History ==
     28
     29[[Image(http://i.imgur.com/aHUvt.png)]]
     30
     31== Files connection diagram of Ewk History ==
     32
     33[[Image(http://i.imgur.com/SKMaY.png)]]
     34
     35The diagram is split in four major parts,
     36
     371. 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)
     38* libcario is an multiplatform 2D graphics library
     39* WebKit (source path)/WebCore/ group of libraries this is the main group of dependences needed to use, to provide the history funcionality
     40* WebKit (source path)/efl/ewk/ group of libraries are the dependences from highest (presentation) layer.
     41
     42All of this files (just need to add ".h" to each name) creates the dependences of '''ewk_history''' API.
     43
     44== Example of use ==
     45
     46Here we have some very simplistic use case of EWK History API.
     47The source code presented here is copied from EWebLauncher example browser,
     48which is available in source code of WebKit's.
     49
     50We have two examples. First is mostly low level an concerned on debug abilities,
     51the second is a high level part which with minimal effort can be used in real
     52world web browser.
     53
     54{{{
     55static void
     56print_history(Eina_List *list)
     57{
     58    Eina_List *l;
     59    void *d;
     60
     61    if (!verbose)
     62       return;
     63
     64    printf("Session history contains:\n");
     65
     66    EINA_LIST_FOREACH(list, l, d) {
     67       Ewk_History_Item *item = (Ewk_History_Item*)d;
     68       cairo_surface_t *cs = ewk_history_item_icon_surface_get(item);
     69       char buf[PATH_MAX];
     70       int s = snprintf(buf, sizeof(buf), "/tmp/favicon-%s.png", ewk_history_item_uri_original_get(item));
     71       for (s--; s >= (int)sizeof("/tmp/favicon-"); s--) {
     72           if (!isalnum(buf[s]) && buf[s] != '.')
     73               buf[s] = '_';
     74       }
     75       cs = ewk_history_item_icon_surface_get(item);
     76
     77       if (cs && cairo_surface_status(cs) == CAIRO_STATUS_SUCCESS)
     78           cairo_surface_write_to_png(cs, buf);
     79       else
     80           buf[0] = '\0';
     81
     82       printf("* '%s' title='%s' icon='%s'\n",
     83              ewk_history_item_uri_original_get(item),
     84              ewk_history_item_title_get(item), buf);
     85    }
     86}
     87}}}
     88
     89Here we have a great example how to use EWK History API to list the whole history of our web browser.
     90We are using here a few of functions from API:
     91
     92* ewk_history_item_icon_surface_get(Ewk_History_Item *item ) - returns a image of favicon for a history item.
     93* ewk_history_item_uri_original_get(item) - returns an URI to a web page for a history item.
     94* ewk_history_item_title_get(item) - returns a title of the web page
     95
     96This is mostly a debug code, and it is used on that role in EWebLauncher (try run it with --verbose), but
     97some mechanisms which can be used to make eg. a toolbar with history elemnets.
     98
     99{{{
     100static void on_key_down(void *data, Evas *e, Evas_Object *obj, void *event_info){
     101
     102[..]
     103    } else if (!strcmp(ev->key, "F1")) {
     104        info("Back (F1) was pressed\n");
     105        if (ewk_view_back_possible(obj)) {
     106            Ewk_History *history = ewk_view_history_get(obj);
     107            Eina_List *list = ewk_history_back_list_get(history);
     108            print_history(list);
     109            ewk_history_item_list_free(list);
     110            ewk_view_back(obj);
     111        } else
     112            info("Back ignored: No back history\n");
     113    } else if (!strcmp(ev->key, "F2")) {
     114        info("Forward (F2) was pressed\n");
     115        if (ewk_view_forward_possible(obj)) {
     116            Ewk_History *history = ewk_view_history_get(obj);
     117            Eina_List *list = ewk_history_forward_list_get(history);
     118            print_history(list);
     119            ewk_history_item_list_free(list);
     120            ewk_view_forward(obj);
     121        } else
     122            info("Forward ignored: No forward history\n");
     123[..]
     124}}}
     125
     126Here 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.
     127The API calls used:
     128
     129* 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.
     130* ewk_view_history_get(obj) - returns a Ewk_History structure extracted from web browser session
     131* 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
     132* ewk_history_item_list_free(Eina_List* list) - cleans a memory allocated in ewk_history_back_list_get
     133* ewk_view_back(Evas_Object* obj)/ewk_view_forward(Evas_Object* obj) - changes current webpage to past or forward item
     134
     135== Sources ==
     136
     137
     138* WebKit/Source/WebKit/efl/ewk/
     139* WebKit/Tools/EWebLauncher/