2 Copyright (C) 2009-2010 ProFUSION embedded systems
3 Copyright (C) 2009-2010 Samsung Electronics
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.
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.
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.
23 * @brief Collection of web navigation history API.
39 * @brief The history (back-forward list) associated with a given ewk_view.
41 * Changing the history affects immediately the view, changing the
42 * current uri, for example.
44 * When ewk_view is navigated or uris are set, history automatically
45 * updates. That's why no direct access to history structure is
48 typedef struct _Ewk_History Ewk_History;
51 * Represents one item from Ewk_History.
53 typedef struct _Ewk_History_Item Ewk_History_Item;
58 * Clear the current history, if there is any.
60 * @param history which history instance to modify.
62 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
64 EAPI Eina_Bool ewk_history_clear(Ewk_History *history);
67 * Go forward in history one item, if possible.
69 * @param history which history instance to modify.
71 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
73 EAPI Eina_Bool ewk_history_forward(Ewk_History *history);
76 * Go back in history one item, if possible.
78 * @param history which history instance to modify.
80 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
82 EAPI Eina_Bool ewk_history_back(Ewk_History *history);
85 * Adds the given item to history.
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().
91 * @param history which history instance to modify.
92 * @param item reference to add to history. Unmodified. Must @b not be @c NULL.
94 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
96 EAPI Eina_Bool ewk_history_history_item_add(Ewk_History *history, const Ewk_History_Item *item);
99 * Sets the given item as current in history (go to item).
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().
105 * @param history which history instance to modify.
106 * @param item reference to go to history. Unmodified. Must @b not be @c NULL.
108 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
110 EAPI Eina_Bool ewk_history_history_item_set(Ewk_History *history, const Ewk_History_Item *item);
113 * Get the first item from back list, if any.
115 * @param history which history instance to query.
117 * @return the @b newly allocated item instance. This memory must be
118 * released with ewk_history_item_free() after use.
120 EAPI Ewk_History_Item *ewk_history_history_item_back_get(const Ewk_History *history);
123 * Get the current item in history, if any.
125 * @param history which history instance to query.
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.
130 EAPI Ewk_History_Item *ewk_history_history_item_current_get(const Ewk_History *history);
133 * Get the first item from forward list, if any.
135 * @param history which history instance to query.
137 * @return the @b newly allocated item instance. This memory must be
138 * released with ewk_history_item_free() after use.
140 EAPI Ewk_History_Item *ewk_history_history_item_forward_get(const Ewk_History *history);
143 * Get item at given position, if any at that index.
145 * @param history which history instance to query.
146 * @param index position of item to get.
148 * @return the @b newly allocated item instance. This memory must be
149 * released with ewk_history_item_free() after use.
151 EAPI Ewk_History_Item *ewk_history_history_item_nth_get(const Ewk_History *history, int index);
154 * Queries if given item is in history.
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().
160 * @param history which history instance to modify.
161 * @param item reference to check in history. Must @b not be @c NULL.
163 * @return @c EINA_TRUE if in history, @c EINA_FALSE if not or failure.
165 EAPI Eina_Bool ewk_history_history_item_contains(const Ewk_History *history, const Ewk_History_Item *item);
168 * Get the whole forward list.
170 * @param history which history instance to query.
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.
177 * @see ewk_history_item_list_free()
178 * @see ewk_history_forward_list_get_with_limit()
180 EAPI Eina_List *ewk_history_forward_list_get(const Ewk_History *history);
183 * Get the forward list within the given limit.
185 * @param history which history instance to query.
186 * @param limit the maximum number of items to return.
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.
193 * @see ewk_history_item_list_free()
194 * @see ewk_history_forward_list_length()
195 * @see ewk_history_forward_list_get()
197 EAPI Eina_List *ewk_history_forward_list_get_with_limit(const Ewk_History *history, int limit);
200 * Get the whole size of forward list.
202 * @param history which history instance to query.
204 * @return number of elements in whole list.
206 * @see ewk_history_forward_list_get_with_limit()
208 EAPI int ewk_history_forward_list_length(const Ewk_History *history);
211 * Get the whole back list.
213 * @param history which history instance to query.
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.
220 * @see ewk_history_item_list_free()
221 * @see ewk_history_back_list_get_with_limit()
223 EAPI Eina_List *ewk_history_back_list_get(const Ewk_History *history);
226 * Get the back list within the given limit.
228 * @param history which history instance to query.
229 * @param limit the maximum number of items to return.
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.
236 * @see ewk_history_item_list_free()
237 * @see ewk_history_back_list_length()
238 * @see ewk_history_back_list_get()
240 EAPI Eina_List *ewk_history_back_list_get_with_limit(const Ewk_History *history, int limit);
243 * Get the whole size of back list.
245 * @param history which history instance to query.
247 * @return number of elements in whole list.
249 * @see ewk_history_back_list_get_with_limit()
251 EAPI int ewk_history_back_list_length(const Ewk_History *history);
254 * Get maximum capacity of given history.
256 * @param history which history instance to query.
258 * @return maximum number of entries this history will hold.
260 EAPI int ewk_history_limit_get(Ewk_History *history);
263 * Set maximum capacity of given history.
265 * @param history which history instance to modify.
266 * @param limit maximum size to allow.
268 * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
270 EAPI Eina_Bool ewk_history_limit_set(const Ewk_History *history, int limit);
273 * Create a new history item with given URI and title.
275 * @param uri where this resource is located.
276 * @param title resource title.
278 * @return newly allocated history item or @c NULL on errors. You must
279 * free this item with ewk_history_item_free().
281 EAPI Ewk_History_Item *ewk_history_item_new(const char *uri, const char *title);
284 * Free given history item instance.
286 * @param item what to free.
288 EAPI void ewk_history_item_free(Ewk_History_Item *item);
291 * Free given list and associated history items instances.
293 * @param history_items list of items to free (both list nodes and
296 EAPI void ewk_history_item_list_free(Eina_List *history_items);
299 * Query title for given history item.
301 * @param item history item to query.
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
309 EAPI const char *ewk_history_item_title_get(const Ewk_History_Item *item);
312 * Query alternate title for given history item.
314 * @param item history item to query.
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
322 EAPI const char *ewk_history_item_title_alternate_get(const Ewk_History_Item *item);
325 * Set alternate title for given history item.
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.
331 EAPI void ewk_history_item_title_alternate_set(Ewk_History_Item *item, const char *title);
334 * Query URI for given history item.
336 * @param item history item to query.
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
344 EAPI const char *ewk_history_item_uri_get(const Ewk_History_Item *item);
347 * Query original URI for given history item.
349 * @param item history item to query.
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
357 EAPI const char *ewk_history_item_uri_original_get(const Ewk_History_Item *item);
360 * Query last visited time for given history item.
362 * @param item history item to query.
364 * @return the time in seconds this item was visited.
366 EAPI double ewk_history_item_time_last_visited_get(const Ewk_History_Item *item);
369 * Get the icon (aka favicon) associated with this history item.
371 * @note in order to have this working, one must open icon database
372 * with ewk_settings_icon_database_path_set().
374 * @param item history item to query.
376 * @return the surface reference or @c NULL on errors. Note that the
377 * reference may be to a standard fallback icon.
379 EAPI cairo_surface_t *ewk_history_item_icon_surface_get(const Ewk_History_Item *item);
382 * Add an Evas_Object of type 'image' to given canvas with history item icon.
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.
388 * @note in order to have this working, one must open icon database
389 * with ewk_settings_icon_database_path_set().
391 * @param item history item to query.
392 * @param canvas evas instance where to add resulting object.
394 * @return newly allocated Evas_Object instance or @c NULL on
395 * errors. Delete the object with evas_object_del().
397 EAPI Evas_Object *ewk_history_item_icon_object_add(const Ewk_History_Item *item, Evas *canvas);
400 * Query if given item is still in page cache.
402 * @param item history item to query.
404 * @return @c EINA_TRUE if in cache, @c EINA_FALSE otherwise.
406 EAPI Eina_Bool ewk_history_item_page_cache_exists(const Ewk_History_Item *item);
409 * Query number of times item was visited.
411 * @param item history item to query.
413 * @return number of visits.
415 EAPI int ewk_history_item_visit_count(const Ewk_History_Item *item);
418 * Query if last visit to item was failure or not.
420 * @param item history item to query.
422 * @return @c EINA_TRUE if last visit was failure, @c EINA_FALSE if it
425 EAPI Eina_Bool ewk_history_item_visit_last_failed(const Ewk_History_Item *item);
430 #endif // ewk_history_h