src/lib/elm_web.h

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