src/lib/elm_web.h

   1 /**
   2  * @defgroup Web Web
   3  * @ingroup Elementary
   4  *
   5  * @image html web_inheritance_tree.png
   6  * @image latex web_inheritance_tree.eps
   7  *
   8  * @image html img/widget/web/preview-00.png
   9  * @image latex img/widget/web/preview-00.eps
  10  *
  11  * A web widget is used for displaying web pages (HTML/CSS/JS)
  12  * using WebKit-EFL. You must have compiled Elementary with
  13  * ewebkit support.
  14  *
  15  * Signals that you can add callbacks for are:
  16  * @li "download,request": A file download has been requested. Event info is
  17  * a pointer to a Elm_Web_Download
  18  * @li "editorclient,contents,changed": Editor client's contents changed
  19  * @li "editorclient,selection,changed": Editor client's selection changed
  20  * @li "frame,created": A new frame was created. Event info is an
  21  * Evas_Object which can be handled with WebKit's ewk_frame API
  22  * @li "icon,received": An icon was received by the main frame
  23  * @li "inputmethod,changed": Input method changed. Event info is an
  24  * Eina_Bool indicating whether it's enabled or not
  25  * @li "js,windowobject,clear": JS window object has been cleared
  26  * @li "link,hover,in": Mouse cursor is hovering over a link. Event info
  27  * is a char *link[2], where the first string contains the URL the link
  28  * points to, and the second one the title of the link
  29  * @li "link,hover,out": Mouse cursor left the link
  30  * @li "load,document,finished": Loading of a document finished. Event info
  31  * is the frame that finished loading
  32  * @li "load,error": Load failed. Event info is a pointer to
  33  * Elm_Web_Frame_Load_Error
  34  * @li "load,finished": Load finished. Event info is NULL on success, on
  35  * error it's a pointer to Elm_Web_Frame_Load_Error
  36  * @li "load,newwindow,show": A new window was created and is ready to be
  37  * shown
  38  * @li "load,progress": Overall load progress. Event info is a pointer to
  39  * a double containing a value between 0.0 and 1.0
  40  * @li "load,provisional": Started provisional load
  41  * @li "load,started": Loading of a document started
  42  * @li "menubar,visible,get": Queries if the menubar is visible. Event info
  43  * is a pointer to Eina_Bool where the callback should set EINA_TRUE if
  44  * the menubar is visible, or EINA_FALSE in case it's not
  45  * @li "menubar,visible,set": Informs menubar visibility. Event info is
  46  * an Eina_Bool indicating the visibility
  47  * @li "popup,created": A dropdown widget was activated, requesting its
  48  * popup menu to be created. Event info is a pointer to Elm_Web_Menu
  49  * @li "popup,willdelete": The web object is ready to destroy the popup
  50  * object created. Event info is a pointer to Elm_Web_Menu
  51  * @li "ready": Page is fully loaded
  52  * @li "scrollbars,visible,get": Queries visibility of scrollbars. Event
  53  * info is a pointer to Eina_Bool where the visibility state should be set
  54  * @li "scrollbars,visible,set": Informs scrollbars visibility. Event info
  55  * is an Eina_Bool with the visibility state set
  56  * @li "statusbar,text,set": Text of the statusbar changed. Even info is
  57  * a string with the new text
  58  * @li "statusbar,visible,get": Queries visibility of the status bar.
  59  * Event info is a pointer to Eina_Bool where the visibility state should be
  60  * set.
  61  * @li "statusbar,visible,set": Informs statusbar visibility. Event info is
  62  * an Eina_Bool with the visibility value
  63  * @li "title,changed": Title of the main frame changed. Event info is a
  64  * string with the new title
  65  * @li "toolbars,visible,get": Queries visibility of toolbars. Event info
  66  * is a pointer to Eina_Bool where the visibility state should be set
  67  * @li "toolbars,visible,set": Informs the visibility of toolbars. Event
  68  * info is an Eina_Bool with the visibility state
  69  * @li "tooltip,text,set": Show and set text of a tooltip. Event info is
  70  * a string with the text to show
  71  * @li "uri,changed": URI of the main frame changed. Event info is a string
  72  * with the new URI
  73  * @li "view,resized": The web object internal's view changed sized
  74  * @li "windows,close,request": A JavaScript request to close the current
  75  * window was requested
  76  * @li "zoom,animated,end": Animated zoom finished
  77  *
  78  * available styles:
  79  * - default
  80  *
  81  * An example of use of web:
  82  *
  83  * - @ref web_example_01
  84  * - @ref web_example_02
  85  */
  86
  87 /**
  88  * @addtogroup Web
  89  * @{
  90  */
  91
  92 /**
  93  * Structure used to report load errors.
  94  *
  95  * Load errors are reported as signal by elm_web. All the strings are
  96  * temporary references and should @b not be used after the signal
  97  * callback returns. If it's required, make copies with strdup() or
  98  * eina_stringshare_add() (they are not even guaranteed to be
  99  * stringshared, so must use eina_stringshare_add() and not
 100  * eina_stringshare_ref()).
 101  */
 102 typedef struct _Elm_Web_Frame_Load_Error Elm_Web_Frame_Load_Error;
 103
 104 /**
 105  * Structure used to report load errors.
 106  *
 107  * Load errors are reported as signal by elm_web. All the strings are
 108  * temporary references and should @b not be used after the signal
 109  * callback returns. If it's required, make copies with strdup() or
 110  * eina_stringshare_add() (they are not even guaranteed to be
 111  * stringshared, so must use eina_stringshare_add() and not
 112  * eina_stringshare_ref()).
 113  */
 114 struct _Elm_Web_Frame_Load_Error
 115 {
 116    int          code; /**< Numeric error code */
 117    Eina_Bool    is_cancellation; /**< Error produced by canceling a request */
 118    const char  *domain; /**< Error domain name */
 119    const char  *description; /**< Error description (already localized) */
 120    const char  *failing_url; /**< The URL that failed to load */
 121    Evas_Object *frame; /**< Frame object that produced the error */
 122 };
 123
 124 /**
 125  * The possibles types that the items in a menu can be
 126  */
 127 typedef enum
 128 {
 129    ELM_WEB_MENU_SEPARATOR,
 130    ELM_WEB_MENU_GROUP,
 131    ELM_WEB_MENU_OPTION
 132 } Elm_Web_Menu_Item_Type;
 133
 134 /**
 135  * Structure describing the items in a menu
 136  */
 137 typedef struct _Elm_Web_Menu_Item Elm_Web_Menu_Item;
 138
 139 /**
 140  * Structure describing the items in a menu
 141  */
 142 struct _Elm_Web_Menu_Item
 143 {
 144    const char            *text; /**< The text for the item */
 145    Elm_Web_Menu_Item_Type type; /**< The type of the item */
 146 };
 147
 148 /**
 149  * Structure describing the menu of a popup
 150  *
 151  * This structure will be passed as the @c event_info for the "popup,create"
 152  * signal, which is emitted when a dropdown menu is opened. Users wanting
 153  * to handle these popups by themselves should listen to this signal and
 154  * set the @c handled property of the struct to @c EINA_TRUE. Leaving this
 155  * property as @c EINA_FALSE means that the user will not handle the popup
 156  * and the default implementation will be used.
 157  *
 158  * When the popup is ready to be dismissed, a "popup,willdelete" signal
 159  * will be emitted to notify the user that it can destroy any objects and
 160  * free all data related to it.
 161  *
 162  * @see elm_web_popup_selected_set()
 163  * @see elm_web_popup_destroy()
 164  *
 165  * @ingroup Web
 166  */
 167 typedef struct _Elm_Web_Menu Elm_Web_Menu;
 168
 169 /**
 170  * Structure describing the menu of a popup
 171  *
 172  * This structure will be passed as the @c event_info for the "popup,create"
 173  * signal, which is emitted when a dropdown menu is opened. Users wanting
 174  * to handle these popups by themselves should listen to this signal and
 175  * set the @c handled property of the struct to @c EINA_TRUE. Leaving this
 176  * property as @c EINA_FALSE means that the user will not handle the popup
 177  * and the default implementation will be used.
 178  *
 179  * When the popup is ready to be dismissed, a "popup,willdelete" signal
 180  * will be emitted to notify the user that it can destroy any objects and
 181  * free all data related to it.
 182  *
 183  * @see elm_web_popup_selected_set()
 184  * @see elm_web_popup_destroy()
 185  *
 186  * @ingroup Web
 187  */
 188 struct _Elm_Web_Menu
 189 {
 190    Eina_List *items; /**< List of #Elm_Web_Menu_Item */
 191    int        x; /**< The X position of the popup, relative to the elm_web object */
 192    int        y; /**< The Y position of the popup, relative to the elm_web object */
 193    int        width; /**< Width of the popup menu */
 194    int        height; /**< Height of the popup menu */
 195
 196    Eina_Bool  handled : 1; /**< Set to @c EINA_TRUE by the user to indicate that the popup has been handled and the default implementation should be ignored. Leave as @c EINA_FALSE otherwise. */
 197 };
 198
 199 typedef struct _Elm_Web_Download Elm_Web_Download;
 200 struct _Elm_Web_Download
 201 {
 202    const char *url;
 203 };
 204
 205 /**
 206  * Types of zoom available.
 207  */
 208 typedef enum
 209 {
 210    ELM_WEB_ZOOM_MODE_MANUAL = 0, /**< Zoom controlled normally by elm_web_zoom_set */
 211    ELM_WEB_ZOOM_MODE_AUTO_FIT, /**< Zoom until content fits in web object */
 212    ELM_WEB_ZOOM_MODE_AUTO_FILL, /**< Zoom until content fills web object */
 213    ELM_WEB_ZOOM_MODE_LAST /**< Sentinel value to indicate end */
 214 } Elm_Web_Zoom_Mode;
 215
 216 /**
 217  * Opaque handler containing the features (such as statusbar, menubar, etc)
 218  * that are to be set on a newly requested window.
 219  */
 220 typedef struct _Elm_Web_Window_Features Elm_Web_Window_Features;
 221
 222
 223 /**
 224  * Definitions of web window features.
 225  *
 226  */
 227 typedef enum
 228 {
 229    ELM_WEB_WINDOW_FEATURE_TOOLBAR,
 230    ELM_WEB_WINDOW_FEATURE_STATUSBAR,
 231    ELM_WEB_WINDOW_FEATURE_SCROLLBARS,
 232    ELM_WEB_WINDOW_FEATURE_MENUBAR,
 233    ELM_WEB_WINDOW_FEATURE_LOCATIONBAR,
 234    ELM_WEB_WINDOW_FEATURE_FULLSCREEN
 235 } Elm_Web_Window_Feature_Flag;
 236
 237 /**
 238  * Callback type for the create_window hook.
 239  *
 240  * @param data User data pointer set when setting the hook function.
 241  * @param obj The elm_web object requesting the new window.
 242  * @param js Set to @c EINA_TRUE if the request was originated from
 243  * JavaScript. @c EINA_FALSE otherwise.
 244  * @param window_features A pointer of #Elm_Web_Window_Features indicating
 245  * the features requested for the new window.
 246  *
 247  * @return The @c elm_web widget where the request will be loaded. That is,
 248  * if a new window or tab is created, the elm_web widget in it should be
 249  * returned, and @b NOT the window object. Returning @c NULL should cancel
 250  * the request.
 251  *
 252  * @see elm_web_window_create_hook_set()
 253  *
 254  * @ingroup Web
 255  */
 256 typedef Evas_Object *(*Elm_Web_Window_Open)(void *data, Evas_Object *obj, Eina_Bool js, const Elm_Web_Window_Features *window_features);
 257
 258 /**
 259  * Callback type for the JS alert hook.
 260  *
 261  * @param data User data pointer set when setting the hook function.
 262  * @param obj The elm_web object requesting the new window.
 263  * @param message The message to show in the alert dialog.
 264  *
 265  * @return The object representing the alert dialog.
 266  * Elm_Web will run a second main loop to handle the dialog and normal
 267  * flow of the application will be restored when the object is deleted, so
 268  * the user should handle the popup properly in order to delete the object
 269  * when the action is finished.
 270  * If the function returns @c NULL the popup will be ignored.
 271  *
 272  * @see elm_web_dialog_alert_hook_set()
 273  *
 274  * @ingroup Web
 275  */
 276 typedef Evas_Object *(*Elm_Web_Dialog_Alert)(void *data, Evas_Object *obj, const char *message);
 277
 278 /**
 279  * Callback type for the JS confirm hook.
 280  *
 281  * @param data User data pointer set when setting the hook function.
 282  * @param obj The elm_web object requesting the new window.
 283  * @param message The message to show in the confirm dialog.
 284  * @param ret Pointer to store the user selection. @c EINA_TRUE if
 285  * the user selected @c Ok, @c EINA_FALSE otherwise.
 286  *
 287  * @return The object representing the confirm dialog.
 288  * Elm_Web will run a second main loop to handle the dialog and normal
 289  * flow of the application will be restored when the object is deleted, so
 290  * the user should handle the popup properly in order to delete the object
 291  * when the action is finished.
 292  * If the function returns @c NULL the popup will be ignored.
 293  *
 294  * @see elm_web_dialog_confirm_hook_set()
 295  *
 296  * @ingroup Web
 297  */
 298 typedef Evas_Object *(*Elm_Web_Dialog_Confirm)(void *data, Evas_Object *obj, const char *message, Eina_Bool *ret);
 299
 300 /**
 301  * Callback type for the JS prompt hook.
 302  *
 303  * @param data User data pointer set when setting the hook function.
 304  * @param obj The elm_web object requesting the new window.
 305  * @param message The message to show in the prompt dialog.
 306  * @param def_value The default value to present the user in the entry
 307  * @param value Pointer to store the value given by the user. Must
 308  * be a malloc'ed string or @c NULL if the user canceled the popup.
 309  * @param ret Pointer to store the user selection. @c EINA_TRUE if
 310  * the user selected @c Ok, @c EINA_FALSE otherwise.
 311  *
 312  * @return The object representing the prompt dialog.
 313  * Elm_Web will run a second main loop to handle the dialog and normal
 314  * flow of the application will be restored when the object is deleted, so
 315  * the user should handle the popup properly in order to delete the object
 316  * when the action is finished.
 317  * If the function returns @c NULL the popup will be ignored.
 318  *
 319  * @see elm_web_dialog_prompt_hook_set()
 320  *
 321  * @ingroup Web
 322  */
 323 typedef Evas_Object *(*Elm_Web_Dialog_Prompt)(void *data, Evas_Object *obj, const char *message, const char *def_value, const char **value, Eina_Bool *ret);
 324
 325 /**
 326  * Callback type for the JS file selector hook.
 327  *
 328  * @param data User data pointer set when setting the hook function.
 329  * @param obj The elm_web object requesting the new window.
 330  * @param allows_multiple @c EINA_TRUE if multiple files can be selected.
 331  * @param accept_types Mime types accepted.
 332  * @param selected Pointer to store the list of malloc'ed strings
 333  * containing the path to each file selected. Must be @c NULL if the file
 334  * dialog is canceled.
 335  * @param ret Pointer to store the user selection. @c EINA_TRUE if
 336  * the user selected @c Ok, @c EINA_FALSE otherwise.
 337  *
 338  * @return The object representing the file selector dialog.
 339  * Elm_Web will run a second main loop to handle the dialog and normal
 340  * flow of the application will be restored when the object is deleted, so
 341  * the user should handle the popup properly in order to delete the object
 342  * when the action is finished.
 343  * If the function returns @c NULL the popup will be ignored.
 344  *
 345  * @see elm_web_dialog_file selector_hook_set()
 346  *
 347  * @ingroup Web
 348  */
 349 typedef Evas_Object *(*Elm_Web_Dialog_File_Selector)(void *data, Evas_Object *obj, Eina_Bool allows_multiple, Eina_List *accept_types, Eina_List **selected, Eina_Bool *ret);
 350
 351 /**
 352  * Callback type for the JS console message hook.
 353  *
 354  * When a console message is added from JavaScript, any set function to the
 355  * console message hook will be called for the user to handle. There is no
 356  * default implementation of this hook.
 357  *
 358  * @param data User data pointer set when setting the hook function.
 359  * @param obj The elm_web object that originated the message.
 360  * @param message The message sent.
 361  * @param line_number The line number.
 362  * @param source_id Source id.
 363  *
 364  * @see elm_web_console_message_hook_set()
 365  *
 366  * @ingroup Web
 367  */
 368 typedef void (*Elm_Web_Console_Message)(void *data, Evas_Object *obj, const char *message, unsigned int line_number, const char *source_id);
 369
 370 /**
 371  * Add a new web object to the parent.
 372  *
 373  * @param parent The parent object.
 374  * @return The new object or @c NULL if it cannot be created.
 375  *
 376  * @see elm_web_uri_set()
 377  * @see elm_web_webkit_view_get()
 378  *
 379  * @ingroup Web
 380  */
 381 EAPI Evas_Object      *elm_web_add(Evas_Object *parent);
 382
 383 /**
 384  * Change useragent of a elm_web object
 385  *
 386  * @param obj The object
 387  * @param user_agent String for useragent
 388  *
 389  * @ingroup Web
 390  */
 391 EAPI void elm_web_useragent_set(Evas_Object *obj, const char *user_agent);
 392
 393 /**
 394  * Return current useragent of elm_web object
 395  *
 396  * @param obj The object
 397  * @return Useragent string
 398  *
 399  * @ingroup Web
 400  */
 401 EAPI const char* elm_web_useragent_get(const Evas_Object *obj);
 402
 403 /**
 404  * Get internal ewk_view object from web object.
 405  *
 406  * Elementary may not provide some low level features of EWebKit,
 407  * instead of cluttering the API with proxy methods we opted to
 408  * return the internal reference. Be careful using it as it may
 409  * interfere with elm_web behavior.
 410  *
 411  * @param obj The web object.
 412  * @return The internal ewk_view object or @c NULL if it does not
 413  *         exist. (Failure to create or Elementary compiled without
 414  *         ewebkit)
 415  *
 416  * @see elm_web_add()
 417  *
 418  * @ingroup Web
 419  */
 420 EAPI Evas_Object      *elm_web_webkit_view_get(const Evas_Object *obj);
 421
 422 /**
 423  * Sets the function to call when a new window is requested
 424  *
 425  * This hook will be called when a request to create a new window is
 426  * issued from the web page loaded.
 427  * There is no default implementation for this feature, so leaving this
 428  * unset or passing @c NULL in @p func will prevent new windows from
 429  * opening.
 430  *
 431  * @param obj The web object where to set the hook function
 432  * @param func The hook function to be called when a window is requested
 433  * @param data User data
 434  *
 435  * @ingroup Web
 436  */
 437 EAPI void              elm_web_window_create_hook_set(Evas_Object *obj, Elm_Web_Window_Open func, void *data);
 438
 439 /**
 440  * Sets the function to call when an alert dialog
 441  *
 442  * This hook will be called when a JavaScript alert dialog is requested.
 443  * If no function is set or @c NULL is passed in @p func, the default
 444  * implementation will take place.
 445  *
 446  * @param obj The web object where to set the hook function
 447  * @param func The callback function to be used
 448  * @param data User data
 449  *
 450  * @see elm_web_inwin_mode_set()
 451  *
 452  * @ingroup Web
 453  */
 454 EAPI void              elm_web_dialog_alert_hook_set(Evas_Object *obj, Elm_Web_Dialog_Alert func, void *data);
 455
 456 /**
 457  * Sets the function to call when an confirm dialog
 458  *
 459  * This hook will be called when a JavaScript confirm dialog is requested.
 460  * If no function is set or @c NULL is passed in @p func, the default
 461  * implementation will take place.
 462  *
 463  * @param obj The web object where to set the hook function
 464  * @param func The callback function to be used
 465  * @param data User data
 466  *
 467  * @see elm_web_inwin_mode_set()
 468  *
 469  * @ingroup Web
 470  */
 471 EAPI void              elm_web_dialog_confirm_hook_set(Evas_Object *obj, Elm_Web_Dialog_Confirm func, void *data);
 472
 473 /**
 474  * Sets the function to call when an prompt dialog
 475  *
 476  * This hook will be called when a JavaScript prompt dialog is requested.
 477  * If no function is set or @c NULL is passed in @p func, the default
 478  * implementation will take place.
 479  *
 480  * @param obj The web object where to set the hook function
 481  * @param func The callback function to be used
 482  * @param data User data
 483  *
 484  * @see elm_web_inwin_mode_set()
 485  *
 486  * @ingroup Web
 487  */
 488 EAPI void              elm_web_dialog_prompt_hook_set(Evas_Object *obj, Elm_Web_Dialog_Prompt func, void *data);
 489
 490 /**
 491  * Sets the function to call when an file selector dialog
 492  *
 493  * This hook will be called when a JavaScript file selector dialog is
 494  * requested.
 495  * If no function is set or @c NULL is passed in @p func, the default
 496  * implementation will take place.
 497  *
 498  * @param obj The web object where to set the hook function
 499  * @param func The callback function to be used
 500  * @param data User data
 501  *
 502  * @see elm_web_inwin_mode_set()
 503  *
 504  * @ingroup Web
 505  */
 506 EAPI void              elm_web_dialog_file_selector_hook_set(Evas_Object *obj, Elm_Web_Dialog_File_Selector func, void *data);
 507
 508 /**
 509  * Sets the function to call when a console message is emitted from JS
 510  *
 511  * This hook will be called when a console message is emitted from
 512  * JavaScript. There is no default implementation for this feature.
 513  *
 514  * @param obj The web object where to set the hook function
 515  * @param func The callback function to be used
 516  * @param data User data
 517  *
 518  * @ingroup Web
 519  */
 520 EAPI void              elm_web_console_message_hook_set(Evas_Object *obj, Elm_Web_Console_Message func, void *data);
 521
 522 /**
 523  * Gets the status of the tab propagation
 524  *
 525  * @param obj The web object to query
 526  * @return @c EINA_TRUE if tab propagation is enabled, @c EINA_FALSE otherwise
 527  *
 528  * @see elm_web_tab_propagate_set()
 529  *
 530  * @ingroup Web
 531  */
 532 EAPI Eina_Bool         elm_web_tab_propagate_get(const Evas_Object *obj);
 533
 534 /**
 535  * Sets whether to use tab propagation
 536  *
 537  * If tab propagation is enabled, whenever the user presses the Tab key,
 538  * Elementary will handle it and switch focus to the next widget.
 539  * The default value is disabled, where WebKit will handle the Tab key to
 540  * cycle focus though its internal objects, jumping to the next widget
 541  * only when that cycle ends.
 542  *
 543  * @param obj The web object
 544  * @param propagate Whether to propagate Tab keys to Elementary or not
 545  *
 546  * @ingroup Web
 547  */
 548 EAPI void              elm_web_tab_propagate_set(Evas_Object *obj, Eina_Bool propagate);
 549
 550 /**
 551  * Sets the URI for the web object
 552  *
 553  * It must be a full URI, with resource included, in the form
 554  * http://www.enlightenment.org or file:///tmp/something.html
 555  *
 556  * @param obj The web object
 557  * @param uri The URI to set
 558  * @return @c EINA_TRUE if the URI could be set, @c EINA_FALSE if an error occurred.
 559  *
 560  * @ingroup Web
 561  */
 562 EAPI Eina_Bool         elm_web_uri_set(Evas_Object *obj, const char *uri);
 563
 564 /**
 565  * Gets the current URI for the object
 566  *
 567  * The returned string must not be freed and is guaranteed to be
 568  * stringshared.
 569  *
 570  * @param obj The web object
 571  * @return A stringshared internal string with the current URI, or @c NULL on
 572  * failure
 573  *
 574  * @ingroup Web
 575  */
 576 EAPI const char       *elm_web_uri_get(const Evas_Object *obj);
 577
 578 /**
 579  * Gets the current title
 580  *
 581  * The returned string must not be freed and is guaranteed to be
 582  * stringshared.
 583  *
 584  * @param obj The web object
 585  * @return A stringshared internal string with the current title, or @c NULL on
 586  * failure
 587  *
 588  * @ingroup Web
 589  */
 590 EAPI const char       *elm_web_title_get(const Evas_Object *obj);
 591
 592 /**
 593  * Sets the background color to be used by the web object
 594  *
 595  * This is the color that will be used by default when the loaded page
 596  * does not set it's own. Color values are pre-multiplied.
 597  *
 598  * @param obj The web object
 599  * @param r Red component
 600  * @param g Green component
 601  * @param b Blue component
 602  * @param a Alpha component
 603  *
 604  * @ingroup Web
 605  */
 606 EAPI void              elm_web_bg_color_set(Evas_Object *obj, int r, int g, int b, int a);
 607
 608 /**
 609  * Gets the background color to be used by the web object
 610  *
 611  * This is the color that will be used by default when the loaded page
 612  * does not set it's own. Color values are pre-multiplied.
 613  *
 614  * @param obj The web object
 615  * @param r Red component
 616  * @param g Green component
 617  * @param b Blue component
 618  * @param a Alpha component
 619  *
 620  * @ingroup Web
 621  */
 622 EAPI void              elm_web_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a);
 623
 624 /**
 625  * Gets a copy of the currently selected text
 626  *
 627  * The string returned must be freed by the user when it's done with it.
 628  *
 629  * @param obj The web object
 630  * @return A newly allocated string, or @c NULL if nothing is selected or an
 631  * error occurred
 632  *
 633  * @ingroup Web
 634  */
 635 EAPI const char       *elm_web_selection_get(const Evas_Object *obj);
 636
 637 /**
 638  * Tells the web object which index in the currently open popup was selected
 639  *
 640  * When the user handles the popup creation from the "popup,created" signal,
 641  * it needs to tell the web object which item was selected by calling this
 642  * function with the index corresponding to the item.
 643  *
 644  * @param obj The web object
 645  * @param index The index selected
 646  *
 647  * @see elm_web_popup_destroy()
 648  *
 649  * @ingroup Web
 650  */
 651 EAPI void              elm_web_popup_selected_set(Evas_Object *obj, int index);
 652
 653 /**
 654  * Dismisses an open dropdown popup
 655  *
 656  * When the popup from a dropdown widget is to be dismissed, either after
 657  * selecting an option or to cancel it, this function must be called, which
 658  * will later emit an "popup,willdelete" signal to notify the user that
 659  * any memory and objects related to this popup can be freed.
 660  *
 661  * @param obj The web object
 662  * @return @c EINA_TRUE if the menu was successfully destroyed, or @c EINA_FALSE
 663  * if there was no menu to destroy
 664  *
 665  * @ingroup Web
 666  */
 667 EAPI Eina_Bool         elm_web_popup_destroy(Evas_Object *obj);
 668
 669 /**
 670  * Searches the given string in a document.
 671  *
 672  * @param obj The web object where to search the text
 673  * @param string String to search
 674  * @param case_sensitive If search should be case sensitive or not
 675  * @param forward If search is from cursor and on or backwards
 676  * @param wrap If search should wrap at the end
 677  *
 678  * @return @c EINA_TRUE if the given string was found, @c EINA_FALSE if not
 679  * or failure
 680  *
 681  * @ingroup Web
 682  */
 683 EAPI Eina_Bool         elm_web_text_search(const Evas_Object *obj, const char *string, Eina_Bool case_sensitive, Eina_Bool forward, Eina_Bool wrap);
 684
 685 /**
 686  * Marks matches of the given string in a document.
 687  *
 688  * @param obj The web object where to search text
 689  * @param string String to match
 690  * @param case_sensitive If match should be case sensitive or not
 691  * @param highlight If matches should be highlighted
 692  * @param limit Maximum amount of matches, or zero to unlimited
 693  *
 694  * @return number of matched @a string
 695  *
 696  * @ingroup Web
 697  */
 698 EAPI unsigned int      elm_web_text_matches_mark(Evas_Object *obj, const char *string, Eina_Bool case_sensitive, Eina_Bool highlight, unsigned int limit);
 699
 700 /**
 701  * Clears all marked matches in the document
 702  *
 703  * @param obj The web object
 704  *
 705  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 706  *
 707  * @ingroup Web
 708  */
 709 EAPI Eina_Bool         elm_web_text_matches_unmark_all(Evas_Object *obj);
 710
 711 /**
 712  * Sets whether to highlight the matched marks
 713  *
 714  * If enabled, marks set with elm_web_text_matches_mark() will be
 715  * highlighted.
 716  *
 717  * @param obj The web object
 718  * @param highlight Whether to highlight the marks or not
 719  *
 720  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 721  *
 722  * @ingroup Web
 723  */
 724 EAPI Eina_Bool         elm_web_text_matches_highlight_set(Evas_Object *obj, Eina_Bool highlight);
 725
 726 /**
 727  * Gets whether highlighting marks is enabled
 728  *
 729  * @param obj The web object
 730  *
 731  * @return @c EINA_TRUE is marks are set to be highlighted, @c EINA_FALSE
 732  * otherwise
 733  *
 734  * @ingroup Web
 735  */
 736 EAPI Eina_Bool         elm_web_text_matches_highlight_get(const Evas_Object *obj);
 737
 738 /**
 739  * Gets the overall loading progress of the page
 740  *
 741  * Returns the estimated loading progress of the page, with a value between
 742  * 0.0 and 1.0. This is an estimated progress accounting for all the frames
 743  * included in the page.
 744  *
 745  * @param obj The web object
 746  *
 747  * @return A value between 0.0 and 1.0 indicating the progress, or -1.0 on
 748  * failure
 749  *
 750  * @ingroup Web
 751  */
 752 EAPI double            elm_web_load_progress_get(const Evas_Object *obj);
 753
 754 /**
 755  * Stops loading the current page
 756  *
 757  * Cancels the loading of the current page in the web object. This will
 758  * cause a "load,error" signal to be emitted, with the is_cancellation
 759  * flag set to @c EINA_TRUE.
 760  *
 761  * @param obj The web object
 762  *
 763  * @return @c EINA_TRUE if the cancel was successful, @c EINA_FALSE otherwise
 764  *
 765  * @ingroup Web
 766  */
 767 EAPI Eina_Bool         elm_web_stop(Evas_Object *obj);
 768
 769 /**
 770  * Requests a reload of the current document in the object
 771  *
 772  * @param obj The web object
 773  *
 774  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 775  *
 776  * @ingroup Web
 777  */
 778 EAPI Eina_Bool         elm_web_reload(Evas_Object *obj);
 779
 780 /**
 781  * Requests a reload of the current document, avoiding any existing caches
 782  *
 783  * @param obj The web object
 784  *
 785  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 786  *
 787  * @ingroup Web
 788  */
 789 EAPI Eina_Bool         elm_web_reload_full(Evas_Object *obj);
 790
 791 /**
 792  * Goes back one step in the browsing history
 793  *
 794  * This is equivalent to calling elm_web_object_navigate(obj, -1);
 795  *
 796  * @param obj The web object
 797  *
 798  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 799  *
 800  * @see elm_web_history_enabled_set()
 801  * @see elm_web_back_possible()
 802  * @see elm_web_forward()
 803  * @see elm_web_navigate()
 804  *
 805  * @ingroup Web
 806  */
 807 EAPI Eina_Bool         elm_web_back(Evas_Object *obj);
 808
 809 /**
 810  * Goes forward one step in the browsing history
 811  *
 812  * This is equivalent to calling elm_web_object_navigate(obj, 1);
 813  *
 814  * @param obj The web object
 815  *
 816  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 817  *
 818  * @see elm_web_history_enabled_set()
 819  * @see elm_web_forward_possible_get()
 820  * @see elm_web_back()
 821  * @see elm_web_navigate()
 822  *
 823  * @ingroup Web
 824  */
 825 EAPI Eina_Bool         elm_web_forward(Evas_Object *obj);
 826
 827 /**
 828  * Jumps the given number of steps in the browsing history
 829  *
 830  * The @p steps value can be a negative integer to back in history, or a
 831  * positive to move forward.
 832  *
 833  * @param obj The web object
 834  * @param steps The number of steps to jump
 835  *
 836  * @return @c EINA_TRUE on success, @c EINA_FALSE on error or if not enough
 837  * history exists to jump the given number of steps
 838  *
 839  * @see elm_web_history_enabled_set()
 840  * @see elm_web_back()
 841  * @see elm_web_forward()
 842  *
 843  * @ingroup Web
 844  */
 845 EAPI Eina_Bool         elm_web_navigate(Evas_Object *obj, int steps);
 846
 847 /**
 848  * Queries whether it's possible to go back in history
 849  *
 850  * @param obj The web object
 851  *
 852  * @return @c EINA_TRUE if it's possible to back in history, @c EINA_FALSE
 853  * otherwise
 854  *
 855  * @ingroup Web
 856  */
 857 EAPI Eina_Bool         elm_web_back_possible_get(Evas_Object *obj);
 858
 859 /**
 860  * Queries whether it's possible to go forward in history
 861  *
 862  * @param obj The web object
 863  *
 864  * @return @c EINA_TRUE if it's possible to forward in history, @c EINA_FALSE
 865  * otherwise
 866  *
 867  * @ingroup Web
 868  */
 869 EAPI Eina_Bool         elm_web_forward_possible_get(Evas_Object *obj);
 870
 871 /**
 872  * Queries whether it's possible to jump the given number of steps
 873  *
 874  * The @p steps value can be a negative integer to back in history, or a
 875  * positive to move forward.
 876  *
 877  * @param obj The web object
 878  * @param steps The number of steps to check for
 879  *
 880  * @return @c EINA_TRUE if enough history exists to perform the given jump,
 881  * @c EINA_FALSE otherwise
 882  *
 883  * @ingroup Web
 884  */
 885 EAPI Eina_Bool         elm_web_navigate_possible_get(Evas_Object *obj, int steps);
 886
 887 /**
 888  * Gets whether browsing history is enabled for the given object
 889  *
 890  * @param obj The web object
 891  *
 892  * @return @c EINA_TRUE if history is enabled, @c EINA_FALSE otherwise
 893  *
 894  * @ingroup Web
 895  */
 896 EAPI Eina_Bool         elm_web_history_enabled_get(const Evas_Object *obj);
 897
 898 /**
 899  * Enables or disables the browsing history
 900  *
 901  * @param obj The web object
 902  * @param enabled Whether to enable or disable the browsing history
 903  *
 904  * @ingroup Web
 905  */
 906 EAPI void              elm_web_history_enabled_set(Evas_Object *obj, Eina_Bool enabled);
 907
 908 /**
 909  * Sets the zoom level of the web object
 910  *
 911  * Zoom level matches the Webkit API, so 1.0 means normal zoom, with higher
 912  * values meaning zoom in and lower meaning zoom out. This function will
 913  * only affect the zoom level if the mode set with elm_web_zoom_mode_set()
 914  * is ::ELM_WEB_ZOOM_MODE_MANUAL.
 915  *
 916  * @param obj The web object
 917  * @param zoom The zoom level to set
 918  *
 919  * @ingroup Web
 920  */
 921 EAPI void              elm_web_zoom_set(Evas_Object *obj, double zoom);
 922
 923 /**
 924  * Gets the current zoom level set on the web object
 925  *
 926  * Note that this is the zoom level set on the web object and not that
 927  * of the underlying Webkit one. In the ::ELM_WEB_ZOOM_MODE_MANUAL mode,
 928  * the two zoom levels should match, but for the other two modes the
 929  * Webkit zoom is calculated internally to match the chosen mode without
 930  * changing the zoom level set for the web object.
 931  *
 932  * @param obj The web object
 933  *
 934  * @return The zoom level set on the object
 935  *
 936  * @ingroup Web
 937  */
 938 EAPI double            elm_web_zoom_get(const Evas_Object *obj);
 939
 940 /**
 941  * Sets the zoom mode to use
 942  *
 943  * The modes can be any of those defined in ::Elm_Web_Zoom_Mode, except
 944  * ::ELM_WEB_ZOOM_MODE_LAST. The default is ::ELM_WEB_ZOOM_MODE_MANUAL.
 945  *
 946  * ::ELM_WEB_ZOOM_MODE_MANUAL means the zoom level will be controlled
 947  * with the elm_web_zoom_set() function.
 948  * ::ELM_WEB_ZOOM_MODE_AUTO_FIT will calculate the needed zoom level to
 949  * make sure the entirety of the web object's contents are shown.
 950  * ::ELM_WEB_ZOOM_MODE_AUTO_FILL will calculate the needed zoom level to
 951  * fit the contents in the web object's size, without leaving any space
 952  * unused.
 953  *
 954  * @param obj The web object
 955  * @param mode The mode to set
 956  *
 957  * @ingroup Web
 958  */
 959 EAPI void              elm_web_zoom_mode_set(Evas_Object *obj, Elm_Web_Zoom_Mode mode);
 960
 961 /**
 962  * Gets the currently set zoom mode
 963  *
 964  * @param obj The web object
 965  *
 966  * @return The current zoom mode set for the object,
 967  * or ::ELM_WEB_ZOOM_MODE_LAST on error
 968  *
 969  * @ingroup Web
 970  */
 971 EAPI Elm_Web_Zoom_Mode elm_web_zoom_mode_get(const Evas_Object *obj);
 972
 973 /**
 974  * Shows the given region in the web object
 975  *
 976  * @param obj The web object
 977  * @param x The x coordinate of the region to show
 978  * @param y The y coordinate of the region to show
 979  * @param w The width of the region to show
 980  * @param h The height of the region to show
 981  *
 982  * @ingroup Web
 983  */
 984 EAPI void              elm_web_region_show(Evas_Object *obj, int x, int y, int w, int h);
 985
 986 /**
 987  * Brings in the region to the visible area
 988  *
 989  * Like elm_web_region_show(), but it animates the scrolling of the object
 990  * to show the area
 991  *
 992  * @param obj The web object
 993  * @param x The x coordinate of the region to show
 994  * @param y The y coordinate of the region to show
 995  * @param w The width of the region to show
 996  * @param h The height of the region to show
 997  *
 998  * @ingroup Web
 999  */
1000 EAPI void              elm_web_region_bring_in(Evas_Object *obj, int x, int y, int w, int h);
1001
1002 /**
1003  * Sets the default dialogs to use an Inwin instead of a normal window
1004  *
1005  * If set, then the default implementation for the JavaScript dialogs and
1006  * file selector will be opened in an Inwin. Otherwise they will use a
1007  * normal separated window.
1008  *
1009  * @param obj The web object
1010  * @param value @c EINA_TRUE to use Inwin, @c EINA_FALSE to use a normal window
1011  *
1012  * @ingroup Web
1013  */
1014 EAPI void              elm_web_inwin_mode_set(Evas_Object *obj, Eina_Bool value);
1015
1016 /**
1017  * Gets whether Inwin mode is set for the current object
1018  *
1019  * @param obj The web object
1020  *
1021  * @return @c EINA_TRUE if Inwin mode is set, @c EINA_FALSE otherwise
1022  *
1023  * @ingroup Web
1024  */
1025 EAPI Eina_Bool         elm_web_inwin_mode_get(const Evas_Object *obj);
1026
1027 EAPI void              elm_web_window_features_ref(Elm_Web_Window_Features *wf);
1028 EAPI void              elm_web_window_features_unref(Elm_Web_Window_Features *wf);
1029
1030 /**
1031  * Gets boolean properties from Elm_Web_Window_Features
1032  * (such as statusbar, menubar, etc) that are on a window.
1033  *
1034  * @param wf The web window features object
1035  * @param flag The web window feature flag whose value is required.
1036  *
1037  * @return @c EINA_TRUE if the flag is set, @c EINA_FALSE otherwise
1038  *
1039  * @ingroup Web
1040  */
1041 EAPI Eina_Bool              elm_web_window_features_property_get(const Elm_Web_Window_Features *wf, Elm_Web_Window_Feature_Flag flag);
1042
1043 /**
1044  *
1045  * TODO : Add documentation.
1046  *
1047  * @param wf The web window features object
1048  * @param x, y, w, h - the co-ordinates of the web view window.
1049  *
1050  * @ingroup Web
1051  */
1052 EAPI void              elm_web_window_features_region_get(const Elm_Web_Window_Features *wf, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h);
1053
1054 /**
1055  * @}
1056  */