Changes between Initial Version and Version 1 of EFLHistoryApiTutorial

Timestamp:

Sep 19, 2012, 2:04:06 AM (12 years ago)

Author:

marcin.jabrzyk@gmail.com

Comment:

Initial version of the page.

EFLHistoryApiTutorial

@@ +1 @@
+----
+
+== 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_histroy.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 ==
+
+[[Image(http://i.imgur.com/aHUvt.png)]]
+
+== Files connection diagram of Ewk History ==
+
+[[Image(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) 
+* libcario 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/