debian/libwebkit-engine-dev/usr/include/ewebkit-0/ewk_history.h

   1 /*
   2     Copyright (C) 2009-2010 ProFUSION embedded systems
   3     Copyright (C) 2009-2010 Samsung Electronics
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License as published by the Free Software Foundation; either
   8     version 2 of the License, or (at your option) any later version.
   9
  10     This library is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13     Library General Public License for more details.
  14
  15     You should have received a copy of the GNU Library General Public License
  16     along with this library; see the file COPYING.LIB.  If not, write to
  17     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18     Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file    ewk_history.h
  23  * @brief   Collection of web navigation history API.
  24  */
  25
  26 #ifndef ewk_history_h
  27 #define ewk_history_h
  28
  29 #include <Eina.h>
  30 #include <Evas.h>
  31 #include <cairo.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @file ewk_history.h
  39  * @brief The history (back-forward list) associated with a given ewk_view.
  40  *
  41  * Changing the history affects immediately the view, changing the
  42  * current uri, for example.
  43  *
  44  * When ewk_view is navigated or uris are set, history automatically
  45  * updates. That's why no direct access to history structure is
  46  * allowed.
  47  */
  48 typedef struct _Ewk_History         Ewk_History;
  49
  50 /**
  51  * Represents one item from Ewk_History.
  52  */
  53 typedef struct _Ewk_History_Item    Ewk_History_Item;
  54
  55
  56
  57 /**
  58  * Clear the current history, if there is any.
  59  *
  60  * @param history which history instance to modify.
  61  *
  62  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
  63  */
  64 EAPI Eina_Bool         ewk_history_clear(Ewk_History *history);
  65
  66 /**
  67  * Go forward in history one item, if possible.
  68  *
  69  * @param history which history instance to modify.
  70  *
  71  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
  72  */
  73 EAPI Eina_Bool         ewk_history_forward(Ewk_History *history);
  74
  75 /**
  76  * Go back in history one item, if possible.
  77  *
  78  * @param history which history instance to modify.
  79  *
  80  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
  81  */
  82 EAPI Eina_Bool         ewk_history_back(Ewk_History *history);
  83
  84 /**
  85  * Adds the given item to history.
  86  *
  87  * Memory handling: This will not modify or even take references to
  88  * given item (Ewk_History_Item), so you should still handle it with
  89  * ewk_history_item_free().
  90  *
  91  * @param history which history instance to modify.
  92  * @param item reference to add to history. Unmodified. Must @b not be @c NULL.
  93  *
  94  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
  95  */
  96 EAPI Eina_Bool         ewk_history_history_item_add(Ewk_History *history, const Ewk_History_Item *item);
  97
  98 /**
  99  * Sets the given item as current in history (go to item).
 100  *
 101  * Memory handling: This will not modify or even take references to
 102  * given item (Ewk_History_Item), so you should still handle it with
 103  * ewk_history_item_free().
 104  *
 105  * @param history which history instance to modify.
 106  * @param item reference to go to history. Unmodified. Must @b not be @c NULL.
 107  *
 108  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
 109  */
 110 EAPI Eina_Bool         ewk_history_history_item_set(Ewk_History *history,  const Ewk_History_Item *item);
 111
 112 /**
 113  * Get the first item from back list, if any.
 114  *
 115  * @param history which history instance to query.
 116  *
 117  * @return the @b newly allocated item instance. This memory must be
 118  *         released with ewk_history_item_free() after use.
 119  */
 120 EAPI Ewk_History_Item *ewk_history_history_item_back_get(const Ewk_History *history);
 121
 122 /**
 123  * Get the current item in history, if any.
 124  *
 125  * @param history which history instance to query.
 126  *
 127  * @return the @b newly allocated item instance or @c NULL on error. This memory
 128  *         must be released with ewk_history_item_free() after use.
 129  */
 130 EAPI Ewk_History_Item *ewk_history_history_item_current_get(const Ewk_History *history);
 131
 132 /**
 133  * Get the first item from forward list, if any.
 134  *
 135  * @param history which history instance to query.
 136  *
 137  * @return the @b newly allocated item instance. This memory must be
 138  *         released with ewk_history_item_free() after use.
 139  */
 140 EAPI Ewk_History_Item *ewk_history_history_item_forward_get(const Ewk_History *history);
 141
 142 /**
 143  * Get item at given position, if any at that index.
 144  *
 145  * @param history which history instance to query.
 146  * @param index position of item to get.
 147  *
 148  * @return the @b newly allocated item instance. This memory must be
 149  *         released with ewk_history_item_free() after use.
 150  */
 151 EAPI Ewk_History_Item *ewk_history_history_item_nth_get(const Ewk_History *history, int index);
 152
 153 /**
 154  * Queries if given item is in history.
 155  *
 156  * Memory handling: This will not modify or even take references to
 157  * given item (Ewk_History_Item), so you should still handle it with
 158  * ewk_history_item_free().
 159  *
 160  * @param history which history instance to modify.
 161  * @param item reference to check in history. Must @b not be @c NULL.
 162  *
 163  * @return @c EINA_TRUE if in history, @c EINA_FALSE if not or failure.
 164  */
 165 EAPI Eina_Bool         ewk_history_history_item_contains(const Ewk_History *history, const Ewk_History_Item *item);
 166
 167 /**
 168  * Get the whole forward list.
 169  *
 170  * @param history which history instance to query.
 171  *
 172  * @return a newly allocated list of @b newly allocated item
 173  *         instance. This memory of each item must be released with
 174  *         ewk_history_item_free() after use. use
 175  *         ewk_history_item_list_free() for convenience.
 176  *
 177  * @see ewk_history_item_list_free()
 178  * @see ewk_history_forward_list_get_with_limit()
 179  */
 180 EAPI Eina_List        *ewk_history_forward_list_get(const Ewk_History *history);
 181
 182 /**
 183  * Get the forward list within the given limit.
 184  *
 185  * @param history which history instance to query.
 186  * @param limit the maximum number of items to return.
 187  *
 188  * @return a newly allocated list of @b newly allocated item
 189  *         instance. This memory of each item must be released with
 190  *         ewk_history_item_free() after use. use
 191  *         ewk_history_item_list_free() for convenience.
 192  *
 193  * @see ewk_history_item_list_free()
 194  * @see ewk_history_forward_list_length()
 195  * @see ewk_history_forward_list_get()
 196  */
 197 EAPI Eina_List        *ewk_history_forward_list_get_with_limit(const Ewk_History *history, int limit);
 198
 199 /**
 200  * Get the whole size of forward list.
 201  *
 202  * @param history which history instance to query.
 203  *
 204  * @return number of elements in whole list.
 205  *
 206  * @see ewk_history_forward_list_get_with_limit()
 207  */
 208 EAPI int               ewk_history_forward_list_length(const Ewk_History *history);
 209
 210 /**
 211  * Get the whole back list.
 212  *
 213  * @param history which history instance to query.
 214  *
 215  * @return a newly allocated list of @b newly allocated item
 216  *         instance. This memory of each item must be released with
 217  *         ewk_history_item_free() after use. use
 218  *         ewk_history_item_list_free() for convenience.
 219  *
 220  * @see ewk_history_item_list_free()
 221  * @see ewk_history_back_list_get_with_limit()
 222  */
 223 EAPI Eina_List        *ewk_history_back_list_get(const Ewk_History *history);
 224
 225 /**
 226  * Get the back list within the given limit.
 227  *
 228  * @param history which history instance to query.
 229  * @param limit the maximum number of items to return.
 230  *
 231  * @return a newly allocated list of @b newly allocated item
 232  *         instance. This memory of each item must be released with
 233  *         ewk_history_item_free() after use. use
 234  *         ewk_history_item_list_free() for convenience.
 235  *
 236  * @see ewk_history_item_list_free()
 237  * @see ewk_history_back_list_length()
 238  * @see ewk_history_back_list_get()
 239  */
 240 EAPI Eina_List        *ewk_history_back_list_get_with_limit(const Ewk_History *history, int limit);
 241
 242 /**
 243  * Get the whole size of back list.
 244  *
 245  * @param history which history instance to query.
 246  *
 247  * @return number of elements in whole list.
 248  *
 249  * @see ewk_history_back_list_get_with_limit()
 250  */
 251 EAPI int               ewk_history_back_list_length(const Ewk_History *history);
 252
 253 /**
 254  * Get maximum capacity of given history.
 255  *
 256  * @param history which history instance to query.
 257  *
 258  * @return maximum number of entries this history will hold.
 259  */
 260 EAPI int               ewk_history_limit_get(Ewk_History *history);
 261
 262 /**
 263  * Set maximum capacity of given history.
 264  *
 265  * @param history which history instance to modify.
 266  * @param limit maximum size to allow.
 267  *
 268  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 269  */
 270 EAPI Eina_Bool         ewk_history_limit_set(const Ewk_History *history, int limit);
 271
 272 /**
 273  * Create a new history item with given URI and title.
 274  *
 275  * @param uri where this resource is located.
 276  * @param title resource title.
 277  *
 278  * @return newly allocated history item or @c NULL on errors. You must
 279  *         free this item with ewk_history_item_free().
 280  */
 281 EAPI Ewk_History_Item *ewk_history_item_new(const char *uri, const char *title);
 282
 283 /**
 284  * Free given history item instance.
 285  *
 286  * @param item what to free.
 287  */
 288 EAPI void              ewk_history_item_free(Ewk_History_Item *item);
 289
 290 /**
 291  * Free given list and associated history items instances.
 292  *
 293  * @param history_items list of items to free (both list nodes and
 294  *        item instances).
 295  */
 296 EAPI void              ewk_history_item_list_free(Eina_List *history_items);
 297
 298 /**
 299  * Query title for given history item.
 300  *
 301  * @param item history item to query.
 302  *
 303  * @return the title pointer, that may be @c NULL. This pointer is
 304  *         guaranteed to be eina_stringshare, so whenever possible
 305  *         save yourself some cpu cycles and use
 306  *         eina_stringshare_ref() instead of eina_stringshare_add() or
 307  *         strdup().
 308  */
 309 EAPI const char       *ewk_history_item_title_get(const Ewk_History_Item *item);
 310
 311 /**
 312  * Query alternate title for given history item.
 313  *
 314  * @param item history item to query.
 315  *
 316  * @return the alternate title pointer, that may be @c NULL. This
 317  *         pointer is guaranteed to be eina_stringshare, so whenever
 318  *         possible save yourself some cpu cycles and use
 319  *         eina_stringshare_ref() instead of eina_stringshare_add() or
 320  *         strdup().
 321  */
 322 EAPI const char       *ewk_history_item_title_alternate_get(const Ewk_History_Item *item);
 323
 324 /**
 325  * Set alternate title for given history item.
 326  *
 327  * @param item history item to query.
 328  * @param title new alternate title to use for given item. No
 329  *        references are kept after this function returns.
 330  */
 331 EAPI void              ewk_history_item_title_alternate_set(Ewk_History_Item *item, const char *title);
 332
 333 /**
 334  * Query URI for given history item.
 335  *
 336  * @param item history item to query.
 337  *
 338  * @return the URI pointer, that may be @c NULL. This pointer is
 339  *         guaranteed to be eina_stringshare, so whenever possible
 340  *         save yourself some cpu cycles and use
 341  *         eina_stringshare_ref() instead of eina_stringshare_add() or
 342  *         strdup().
 343  */
 344 EAPI const char       *ewk_history_item_uri_get(const Ewk_History_Item *item);
 345
 346 /**
 347  * Query original URI for given history item.
 348  *
 349  * @param item history item to query.
 350  *
 351  * @return the original URI pointer, that may be @c NULL. This pointer
 352  *         is guaranteed to be eina_stringshare, so whenever possible
 353  *         save yourself some cpu cycles and use
 354  *         eina_stringshare_ref() instead of eina_stringshare_add() or
 355  *         strdup().
 356  */
 357 EAPI const char       *ewk_history_item_uri_original_get(const Ewk_History_Item *item);
 358
 359 /**
 360  * Query last visited time for given history item.
 361  *
 362  * @param item history item to query.
 363  *
 364  * @return the time in seconds this item was visited.
 365  */
 366 EAPI double            ewk_history_item_time_last_visited_get(const Ewk_History_Item *item);
 367
 368 /**
 369  * Get the icon (aka favicon) associated with this history item.
 370  *
 371  * @note in order to have this working, one must open icon database
 372  *       with ewk_settings_icon_database_path_set().
 373  *
 374  * @param item history item to query.
 375  *
 376  * @return the surface reference or @c NULL on errors. Note that the
 377  *         reference may be to a standard fallback icon.
 378  */
 379 EAPI cairo_surface_t  *ewk_history_item_icon_surface_get(const Ewk_History_Item *item);
 380
 381 /**
 382  * Add an Evas_Object of type 'image' to given canvas with history item icon.
 383  *
 384  * This is an utility function that creates an Evas_Object of type
 385  * image set to have fill always match object size
 386  * (evas_object_image_filled_add()), saving some code to use it from Evas.
 387  *
 388  * @note in order to have this working, one must open icon database
 389  *       with ewk_settings_icon_database_path_set().
 390  *
 391  * @param item history item to query.
 392  * @param canvas evas instance where to add resulting object.
 393  *
 394  * @return newly allocated Evas_Object instance or @c NULL on
 395  *         errors. Delete the object with evas_object_del().
 396  */
 397 EAPI Evas_Object      *ewk_history_item_icon_object_add(const Ewk_History_Item *item, Evas *canvas);
 398
 399 /**
 400  * Query if given item is still in page cache.
 401  *
 402  * @param item history item to query.
 403  *
 404  * @return @c EINA_TRUE if in cache, @c EINA_FALSE otherwise.
 405  */
 406 EAPI Eina_Bool         ewk_history_item_page_cache_exists(const Ewk_History_Item *item);
 407
 408 /**
 409  * Query number of times item was visited.
 410  *
 411  * @param item history item to query.
 412  *
 413  * @return number of visits.
 414  */
 415 EAPI int               ewk_history_item_visit_count(const Ewk_History_Item *item);
 416
 417 /**
 418  * Query if last visit to item was failure or not.
 419  *
 420  * @param item history item to query.
 421  *
 422  * @return @c EINA_TRUE if last visit was failure, @c EINA_FALSE if it
 423  *         was fine.
 424  */
 425 EAPI Eina_Bool         ewk_history_item_visit_last_failed(const Ewk_History_Item *item);
 426
 427 #ifdef __cplusplus
 428 }
 429 #endif
 430 #endif // ewk_history_h