2 Copyright (C) 2016 Samsung Electronics
3 Copyright (C) 2012 Intel Corporation. All rights reserved.
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 This file describes the Chromium-efl main smart object.
25 * This object provides view related APIs of Chromium to EFL objects.
35 #include "ewk_back_forward_list.h"
36 #include "ewk_context.h"
37 #include "ewk_context_menu.h"
38 #include "ewk_settings.h"
50 * @brief Request to set the current page's visibility.
52 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
54 * @param[in] o View object to set the visibility.
55 * @param[in] enable EINA_TRUE to set on the visibility of the page,
56 * EINA_FALSE otherwise.
58 * @return @c EINA_TRUE on success, othetwise @c EINA_FALSE
60 EXPORT_API Eina_Bool ewk_view_visibility_set(const Evas_Object* o, Eina_Bool enable);
63 * @brief Sends the orientation of the device.
65 * If orientation value is changed, orientationchanged event will occur.
67 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
69 * @param[in] o View object to receive orientation event.
70 * @param[in] orientation The new orientation of the device. (degree)
72 * orientation will be 0 degrees when the device is oriented to natural position
73 * ,-90 degrees when it's left side is at the top
74 * , 90 degrees when it's right side is at the top
75 * ,180 degrees when it is upside down.
77 EXPORT_API void ewk_view_orientation_send(Evas_Object *o, int orientation);
81 * @brief Returns the selection text.
83 * @details Returned string becomes invalidated upon next call to this api.
87 * @param[in] o View object to get selection text.
89 * @return @c selection text, otherwise @c NULL
92 EXPORT_API const char* ewk_view_text_selection_text_get(Evas_Object* o);
96 * @brief Clears the current selection.
100 * @param[in] o View object with selection in progress
102 * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
105 EXPORT_API Eina_Bool ewk_view_text_selection_clear(Evas_Object* o);
108 * @brief Creates a new EFL Chromium view object.
110 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
112 * @param[in] e The canvas object where to create the view object
114 * @return The view object on success,\n
115 * otherwise @c NULL on failure
117 EXPORT_API Evas_Object* ewk_view_add(Evas* e);
120 * @brief Creates a new EFL web view object in incognito mode.
124 * @param[in] e The canvas object where to create the view object
126 * @return The view object on success,\n
127 * otherwise @c NULL on failure
129 EXPORT_API Evas_Object *ewk_view_add_in_incognito_mode(Evas *e);
132 * @brief Gets the #Ewk_Context of this view.
134 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
136 * @param[in] o The view object to get the #Ewk_Context
138 * @return The #Ewk_Context of this view,\n
139 * otherwise @c NULL on failure
141 EXPORT_API Ewk_Context* ewk_view_context_get(const Evas_Object* o);
144 * @brief Asks the object to load the given URL.
146 * @remarks You can only be sure that url changed after ewk view\n
147 * smart callback 'url,changed' is called. This is important for\n
148 * EWK API functions which operate on pages.
150 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
152 * @param[in] o The view object to load @a url
153 * @param[in] url The uniform resource identifier to load
155 * @return @c EINA_TRUE if @a o is valid, irrespective of load,\n
156 * otherwise @c EINA_FALSE on failure
158 EXPORT_API Eina_Bool ewk_view_url_set(Evas_Object* o, const char* url);
161 * @brief Returns the current URL string of the view object.
163 * @details It returns an internal string that should not be modified.\n
164 * The string is guaranteed to be stringshared.
166 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
168 * @param[in] o The view object to get the current URL
170 * @return The current URL on success,\n
171 * otherwise @c NULL on failure
173 EXPORT_API const char* ewk_view_url_get(const Evas_Object* o);
176 * @brief Asks the main frame to reload the current document.
178 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
180 * @param[in] o The view object to reload the current document
182 * @return @c EINA_TRUE on success,\n
183 * otherwise @c EINA_FALSE
185 EXPORT_API Eina_Bool ewk_view_reload(Evas_Object* o);
188 * @brief Asks the main frame to stop loading.
190 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
192 * @param[in] o The view object to stop loading
194 * @return @c EINA_TRUE on success,\n
195 * otherwise @c EINA_FALSE
197 EXPORT_API Eina_Bool ewk_view_stop(Evas_Object* o);
200 * @brief Gets the #Ewk_Settings of this view.
202 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
204 * @param[in] o The view object to get the #Ewk_Settings
206 * @return The #Ewk_Settings of this view,\n
207 * otherwise @c NULL on failure
209 EXPORT_API Ewk_Settings* ewk_view_settings_get(const Evas_Object* o);
212 * @brief Asks the main frame to navigate back in history.
214 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
216 * @param[in] o The view object to navigate back
218 * @return @c EINA_TRUE on success,\n
219 * otherwise @c EINA_FALSE
221 EXPORT_API Eina_Bool ewk_view_back(Evas_Object* o);
224 * @brief Asks the main frame to navigate forward in history.
226 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
228 * @param[in] o The view object to navigate forward
230 * @return @c EINA_TRUE on success,\n
231 * otherwise @c EINA_FALSE
233 EXPORT_API Eina_Bool ewk_view_forward(Evas_Object* o);
235 * @brief Checks whether it is possible to navigate backwards one item in
238 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
240 * @param[in] o The view object to query if backward navigation is possible
242 * @return @c EINA_TRUE if it is possible to navigate backwards in history,\n
243 * otherwise @c EINA_FALSE
245 EXPORT_API Eina_Bool ewk_view_back_possible(Evas_Object* o);
248 * @brief Checks whether it is possible to navigate forwards one item in
251 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
253 * @param[in] o The view object to query if forward navigation is possible
255 * @return @c EINA_TRUE if it is possible to navigate forwards in history,\n
256 * otherwise @c EINA_FALSE
258 EXPORT_API Eina_Bool ewk_view_forward_possible(Evas_Object* o);
261 * @brief Gets the back-forward list associated with this view.
263 * @details The returned instance is unique for this view and thus multiple
265 * to this function with the same view as a parameter returns the
267 * This handle is alive while the view is alive, thus one might want\n
268 * to listen for EVAS_CALLBACK_DEL on a given view (@a o) to know\n
269 * when to stop using the returned handle.
271 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
273 * @param[in] o The view object to get the back-forward navigation list
275 * @return The back-forward list instance handle associated with this view
277 EXPORT_API Ewk_Back_Forward_List* ewk_view_back_forward_list_get(const Evas_Object* o);
280 * @brief Clears the back-forward list of a page.
282 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
284 * @param[in] o The view object to clear the back-forward list
286 EXPORT_API void ewk_view_back_forward_list_clear(const Evas_Object* o);
289 * @brief Gets the current title of the main frame.
291 * @details It returns an internal string that should not be modified.\n
292 * The string is guaranteed to be stringshared.
294 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
296 * @param[in] o The view object to get the current title
298 * @return The current title on success,\n
299 * otherwise @c NULL on failure
301 EXPORT_API const char* ewk_view_title_get(const Evas_Object* o);
304 * @brief Gets the current load progress of the page.
306 * @details The progress estimation from @c 0.0 to @c 1.0.
308 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
310 * @param[in] o The view object to get the current progress
312 * @return The load progress of the page, value from @c 0.0 to @c 1.0,\n
313 * otherwise @c -1.0 on failure
315 EXPORT_API double ewk_view_load_progress_get(const Evas_Object* o);
318 * @brief Requests to set the user agent string.
320 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
322 * @param[in] o The view object to set the user agent string
323 * @param[in] user_agent The user agent string to set,\n
324 * otherwise @c NULL to restore the default one
326 * @return @c EINA_TRUE on success,\n
327 * otherwise @c EINA_FALSE on failure
329 EXPORT_API Eina_Bool ewk_view_user_agent_set(Evas_Object* o, const char* user_agent);
332 * @brief Returns the user agent string.
334 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
336 * @param[in] o The view object to get the user agent string
338 * @return The user agent string
340 EXPORT_API const char* ewk_view_user_agent_get(const Evas_Object* o);
343 * @brief Gets the last known content's size.
345 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
347 * @param[in] o The view object to get the content's size
348 * @param[in] width The width pointer to store the content's size width,
350 * @param[in] height The height pointer to store the content's size height,
353 * @return @c EINA_TRUE on success,\n
354 * otherwise @c EINA_FALSE on failure and\n
355 * @a width and @a height are zeroed
357 EXPORT_API Eina_Bool ewk_view_contents_size_get(Evas_Object* o, Evas_Coord* width, Evas_Coord* height);
360 * @brief Callback for ewk_view_script_execute().
362 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
364 * @param[in] o The view object
365 * @param[in] result_value The value returned by the script\n
366 * If executed script returns a value, it would be @a result_value\n
367 * otherwise @c NULL if there is no value returned by the script
368 * @param[in] user_data The user_data will be passsed when
369 * ewk_view_script_execute() is called
371 typedef void (*Ewk_View_Script_Execute_Cb)(Evas_Object* o, const char* result_value, void* user_data);
374 * @brief Requests the execution of the given script.
376 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
378 * @remarks This allows to use @c NULL for the callback parameter\n
379 * So, if the result data from the script is not required,
380 * @c NULL might be used for the callback parameter\n
381 * Also, @a script should be valid statement according to JavaScript language\n
382 * If @a script is empty, NULL or invalid statement, this function returns @c EINA_FALSE
384 * @param[in] o The view object to execute the script
385 * @param[in] script The JavaScript code string to execute
386 * @param[in] callback The result callback
387 * @param[in] user_data The user data
389 * @return @c EINA_TRUE on success,\n
390 * otherwise @c EINA_FALSE on failure
392 EXPORT_API Eina_Bool ewk_view_script_execute(Evas_Object* o, const char* script, Ewk_View_Script_Execute_Cb callback, void* user_data);
395 * @brief Scales the current page, centered at the given point.
397 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
399 * @param[in] o The view object to set the zoom level
400 * @param[in] scale_factor A new level to set
401 * @param[in] cx The x value of the center coordinate
402 * @param[in] cy The y value of the center coordinate
404 * @return @c EINA_TRUE on success,\n
405 * otherwise EINA_FALSE
407 EXPORT_API Eina_Bool ewk_view_scale_set(const Evas_Object* view, double scale_factor, int x, int y);
410 * @brief Gets the current scale factor of the page.
412 * @details It returns the previous scale factor after ewk_view_scale_set() is
413 * called immediately\n
414 * until the scale factor of the page is really changed.
416 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
418 * @param[in] o The view object to get the scale factor of
420 * @return The current scale factor in use on success,\n
421 * otherwise @c -1.0 on failure
423 EXPORT_API double ewk_view_scale_get(const Evas_Object* o);
426 * @brief Exits fullscreen when the back key is pressed.
428 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
430 * @param[in] o The view object to exit the fullscreen mode
432 * @return @c EINA_TRUE on success,\n
433 * otherwise @c EINA_FALSE
435 EXPORT_API Eina_Bool ewk_view_fullscreen_exit(Evas_Object* o);
438 * @brief Suspends the operation associated with the view object.
440 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
442 * @param[in] o The view object to suspend
444 EXPORT_API void ewk_view_suspend(Evas_Object* o);
447 * @brief Resumes the operation associated with the view object after calling
448 * ewk_view_suspend().
450 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
452 * @param[in] o The view object to resume
454 EXPORT_API void ewk_view_resume(Evas_Object* o);
457 * \enum Ewk_Http_Method
458 * @brief Enumeration that provides HTTP method options.
459 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
461 enum Ewk_Http_Method {
462 EWK_HTTP_METHOD_GET, /**< Get */
463 EWK_HTTP_METHOD_HEAD, /**< Head */
464 EWK_HTTP_METHOD_POST, /**< Post */
465 EWK_HTTP_METHOD_PUT, /**< Put */
466 EWK_HTTP_METHOD_DELETE, /**< Delete */
470 * @brief Enumeration that creates a type name for the #Ewk_Http_Method.
471 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
473 typedef enum Ewk_Http_Method Ewk_Http_Method;
476 * @brief Requests loading of the given request data.
478 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
480 * @param[in] o The view object to load
481 * @param[in] url The uniform resource identifier to load
482 * @param[in] method The http method
483 * @param[in] headers The http headers
484 * @param[in] body The http body data
486 * @return @c EINA_TRUE on a successful request,\n
487 * otherwise @c EINA_FALSE on failure
489 EXPORT_API Eina_Bool ewk_view_url_request_set(Evas_Object* o, const char* url, Ewk_Http_Method method, Eina_Hash* headers, const char* body);
493 * @brief Requests loading the given contents by MIME type into the view object.
497 * @param[in] o The view object to load
498 * @param[in] contents The content to load
499 * @param[in] contents_size The size of @a contents (in bytes)
500 * @param[in] mime_type The type of @a contents,
501 * if @c 0 is given "text/html" is assumed
502 * @param[in] encoding The encoding for @a contents,
503 * if @c 0 is given "UTF-8" is assumed
504 * @param[in] base_uri The base URI to use for relative resources,
505 * may be @c 0,\n if provided @b must be an absolute URI
507 * @return @c EINA_TRUE on a successful request,\n
508 * otherwise @c EINA_FALSE on errors
511 EXPORT_API Eina_Bool ewk_view_contents_set(Evas_Object* o, const char* contents, size_t contents_size, char* mime_type, char* encoding, char* base_uri);
514 * @brief Scrolls the webpage of view by dx and dy.
516 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
518 * @param[in] o The view object to scroll
519 * @param[in] dx The horizontal offset to scroll
520 * @param[in] dy The vertical offset to scroll
522 EXPORT_API void ewk_view_scroll_by(Evas_Object* o, int dx, int dy);
525 * @brief Gets the current scroll position of the given view.
527 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
529 * @param[in] o The view object to get the current scroll position
530 * @param[in] x The pointer to store the horizontal position, may be @c NULL
531 * @param[in] y The pointer to store the vertical position, may be @c NULL
533 * @return @c EINA_TRUE on success,\n
534 * otherwise @c EINA_FALSE
536 EXPORT_API Eina_Bool ewk_view_scroll_pos_get(Evas_Object* o, int* x, int* y);
539 * @brief Sets an absolute scroll of the given view.
541 * @details Both values are from zero to the contents size minus
544 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
546 * @param[in] o The view object to scroll
547 * @param[in] x The horizontal position to scroll
548 * @param[in] y The vertical position to scroll
550 * @return @c EINA_TRUE on success,\n
551 * otherwise @c EINA_FALSE
553 EXPORT_API Eina_Bool ewk_view_scroll_set(Evas_Object* o, int x, int y);
556 * Enum values used to specify search options.
557 * @brief Enumeration that provides the option to find text.
558 * @details It contains enum values used to specify search options.
559 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
561 enum Ewk_Find_Options {
562 EWK_FIND_OPTIONS_NONE, /**< No search flags, this means a case sensitive, no wrap, forward only search */
563 EWK_FIND_OPTIONS_CASE_INSENSITIVE = 1 << 0, /**< Case insensitive search */
564 EWK_FIND_OPTIONS_AT_WORD_STARTS = 1 << 1, /**< Search text only at the beginning of the words */
565 EWK_FIND_OPTIONS_TREAT_MEDIAL_CAPITAL_AS_WORD_START = 1 << 2, /**< Treat capital letters in the middle of words as word start */
566 EWK_FIND_OPTIONS_BACKWARDS = 1 << 3, /**< Search backwards */
567 EWK_FIND_OPTIONS_WRAP_AROUND = 1 << 4, /**< If not present the search stops at the end of the document */
568 EWK_FIND_OPTIONS_SHOW_OVERLAY = 1 << 5, /**< Show overlay */
569 EWK_FIND_OPTIONS_SHOW_FIND_INDICATOR = 1 << 6, /**< Show indicator */
570 EWK_FIND_OPTIONS_SHOW_HIGHLIGHT = 1 << 7 /**< Show highlight */
574 * @brief Enumeration that creates a type name for the #Ewk_Find_Options.
575 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
577 typedef enum Ewk_Find_Options Ewk_Find_Options;
580 * @brief Searches and highlights the given string in the document.
582 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
584 * @param[in] o The view object to find text
585 * @param[in] text The text to find
586 * @param[in] options The options to find
587 * @param[in] max_match_count The maximum match count to find, unlimited if @c 0
589 * @return @c EINA_TRUE on success,\n
590 * otherwise EINA_FALSE on errors
592 EXPORT_API Eina_Bool ewk_view_text_find(Evas_Object* o, const char* text, Ewk_Find_Options options, unsigned max_match_count);
595 * @brief Loads the specified @a html string as the content of the view.
597 * @details External objects such as stylesheets or images referenced
598 * in the HTML\n document are located relative to @a baseUrl.\n
600 * If an @a unreachableUrl is passed it is used as the url for the loaded
601 * content.\n This is typically used to display error pages for a failed load.
603 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 2.3.1 @endif
605 * @param[in] o view object to load the HTML into
606 * @param[in] html HTML data to load
607 * @param[in] base_url Base URL used for relative paths to external objects
609 * @param[in] unreachable_url URL that could not be reached (optional)
611 * @return @c EINA_TRUE if it the HTML was successfully loaded,
612 * @c EINA_FALSE otherwise
614 EXPORT_API Eina_Bool ewk_view_html_string_load(Evas_Object* o, const char* html, const char* base_url, const char* unreachable_url);
617 * @brief A ScriptMessage contains information that sent from JavaScript running in a webpage.
621 struct _Ewk_Script_Message {
622 const char* name; /**< The name used to expose the object in JavaScript*/
623 void* body; /**< Message body */
627 * @brief A struct that creates a type name for the #Ewk_Script_Message.
630 typedef struct _Ewk_Script_Message Ewk_Script_Message;
633 * @brief Callback for ewk_view_javascript_message_handler_add().
637 * @param[in] o The view object
638 * @param[in] message The ScriptMessage returned by the script. \n
639 * It will be passsed when ewk_view_javascript_message_handler_add() is called.
641 typedef void (*Ewk_View_Script_Message_Cb)(Evas_Object* o, Ewk_Script_Message message);
644 * @brief Injects the supplied javascript message handler into webview.
648 * @remarks Certainly, specify privileges of using native API to users,
649 * if using native API affects system settings, stability or security.
650 * Privilege display name & description which will be noticed to user.
652 * @param[in] o The view object
653 * @param[in] callback The result callback
654 * @param[in] name The name used to expose the object in JavaScript
656 * @return @c EINA_TRUE on success,\n
657 * otherwise @c EINA_FALSE
659 EXPORT_API Eina_Bool ewk_view_javascript_message_handler_add(Evas_Object* o, Ewk_View_Script_Message_Cb callback, const char * name);
662 * @brief Requests the execution of given name & result to the JavaScript runtime.
666 * @param[in] o The view object
667 * @param[in] name The name used to expose the object in JavaScript
668 * @param[in] result The result to the JavaScript runtime
670 * @return @c EINA_TRUE on success,\n
671 * otherwise @c EINA_FALSE
673 EXPORT_API Eina_Bool ewk_view_evaluate_javascript(Evas_Object* o, const char* name, const char* result);