src/lib/elm_web.h

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