dali/devel-api/adaptor-framework/web-engine.h

   1 #ifndef DALI_WEB_ENGINE_H
   2 #define DALI_WEB_ENGINE_H
   3
   4 /*
   5  * Copyright (c) 2021 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23
  24 //INTERNAL INCLUDES
  25 #include <dali/devel-api/adaptor-framework/web-engine-plugin.h>
  26 #include <dali/public-api/dali-adaptor-common.h>
  27
  28 namespace Dali
  29 {
  30 namespace Internal
  31 {
  32 namespace Adaptor
  33 {
  34 class WebEngine;
  35 } // namespace Adaptor
  36
  37 } // namespace Internal
  38
  39 /**
  40  * @brief Proxy class to dynamically load, use and unload web engine plugin.
  41  *
  42  * The purpose of this class is to dynamically load the web engine plugin if and when its needed.
  43  * So we don't slow down every application startup if they never need web engine.
  44  */
  45 class DALI_ADAPTOR_API WebEngine : public BaseHandle
  46 {
  47 public:
  48   /**
  49    * @brief Constructor.
  50    */
  51   WebEngine();
  52
  53   /**
  54    * @brief Destructor.
  55    */
  56   ~WebEngine();
  57
  58   /**
  59    * @brief Creates a new instance of a WebEngine.
  60    */
  61   static WebEngine New();
  62
  63   /**
  64    * @brief Copy constructor.
  65    *
  66    * @param[in] WebEngine WebEngine to copy. The copied WebEngine will point at the same implementation
  67    */
  68   WebEngine(const WebEngine& WebEngine);
  69
  70   /**
  71    * @brief Assignment operator.
  72    *
  73    * @param[in] WebEngine The WebEngine to assign from.
  74    * @return The updated WebEngine.
  75    */
  76   WebEngine& operator=(const WebEngine& WebEngine);
  77
  78   /**
  79    * @brief Downcast a handle to WebEngine handle.
  80    *
  81    * If handle points to a WebEngine the downcast produces valid
  82    * handle. If not the returned handle is left uninitialized.
  83    *
  84    * @param[in] handle Handle to an object
  85    * @return Handle to a WebEngine or an uninitialized handle
  86    */
  87   static WebEngine DownCast(BaseHandle handle);
  88
  89   /**
  90    * @brief Creates WebEngine instance.
  91    *
  92    * @param [in] width The width of Web
  93    * @param [in] height The height of Web
  94    * @param [in] locale The locale of Web
  95    * @param [in] timezoneId The timezoneID of Web
  96    */
  97   void Create(int width, int height, const std::string& locale, const std::string& timezoneId);
  98
  99   /**
 100    * @brief Creates WebEngine instance.
 101    *
 102    * @param [in] width The width of Web
 103    * @param [in] height The height of Web
 104    * @param [in] argc The count of application arguments
 105    * @param [in] argv The string array of application arguments
 106    */
 107   void Create(int width, int height, int argc, char** argv);
 108
 109   /**
 110    * @brief Destroys WebEngine instance.
 111    */
 112   void Destroy();
 113
 114   /**
 115    * @brief Gets native image source to render.
 116    */
 117   NativeImageInterfacePtr GetNativeImageSource();
 118
 119   /**
 120    * @brief Get settings of WebEngine.
 121    */
 122   Dali::WebEngineSettings& GetSettings() const;
 123
 124   /**
 125    * @brief Get context of WebEngine.
 126    */
 127   Dali::WebEngineContext& GetContext() const;
 128
 129   /**
 130    * @brief Get cookie manager of WebEngine.
 131    */
 132   Dali::WebEngineCookieManager& GetCookieManager() const;
 133
 134   /**
 135    * @brief Get back-forward list of WebEngine.
 136    */
 137   Dali::WebEngineBackForwardList& GetBackForwardList() const;
 138
 139   /**
 140    * @brief Loads a web page based on a given URL.
 141    *
 142    * @param [in] url The URL of the resource to load
 143    */
 144   void LoadUrl(const std::string& url);
 145
 146   /**
 147    * @brief Returns the title of the Web.
 148    *
 149    * @return The title of web page
 150    */
 151   std::string GetTitle() const;
 152
 153   /**
 154    * @brief Returns the Favicon of the Web.
 155    *
 156    * @return FavIcon of Dali::PixelData& type
 157    */
 158   Dali::PixelData GetFavicon() const;
 159
 160   /**
 161    * @brief Gets the url.
 162    */
 163   const std::string& GetUrl();
 164
 165   /**
 166    * @brief Loads a given string as web contents.
 167    *
 168    * @param [in] htmlString The string to use as the contents of the web page
 169    */
 170   void LoadHtmlString(const std::string& htmlString);
 171
 172   /**
 173    * @brief Load the specified html string as the content of the view overriding current history entry
 174    *
 175    * @param[in] html HTML data to load
 176    * @param[in] basicUri Base URL used for relative paths to external objects
 177    * @param[in] unreachableUrl URL that could not be reached
 178    *
 179    * @return true if successfully loaded, false otherwise
 180    */
 181   bool LoadHtmlStringOverrideCurrentEntry(const std::string& html, const std::string& basicUri, const std::string& unreachableUrl);
 182
 183   /**
 184    * @brief Requests loading the given contents by MIME type into the view object
 185    *
 186    * @param[in] contents The content to load
 187    * @param[in] contentSize The size of contents (in bytes)
 188    * @param[in] mimeType The type of contents, if 0 is given "text/html" is assumed
 189    * @param[in] encoding The encoding for contents, if 0 is given "UTF-8" is assumed
 190    * @param[in] baseUri The base URI to use for relative resources
 191    *
 192    * @return true if successfully request, false otherwise
 193    */
 194   bool LoadContents(const std::string& contents, uint32_t contentSize, const std::string& mimeType, const std::string& encoding, const std::string& baseUri);
 195
 196   /**
 197    * @brief Reloads the Web.
 198    */
 199   void Reload();
 200
 201   /**
 202    * @brief Reloads the current page's document without cache
 203    */
 204   bool ReloadWithoutCache();
 205
 206   /**
 207    * @brief Stops loading web contents on the current page.
 208    */
 209   void StopLoading();
 210
 211   /**
 212    * @brief Suspends the operation associated with the view.
 213    */
 214   void Suspend();
 215
 216   /**
 217    * @brief Resumes the operation associated with the view object after calling Suspend().
 218    */
 219   void Resume();
 220
 221   /**
 222    * @brief To suspend all url loading
 223    */
 224   void SuspendNetworkLoading();
 225
 226   /**
 227    * @brief To resume new url network loading
 228    */
 229   void ResumeNetworkLoading();
 230
 231   /**
 232    * @brief Add custom header
 233    *
 234    * @param[in] name custom header name to add the custom header
 235    * @param[in] value custom header value to add the custom header
 236    *
 237    * @return true if succeeded, false otherwise
 238    */
 239   bool AddCustomHeader(const std::string& name, const std::string& value);
 240
 241   /**
 242    * @brief Remove custom header
 243    *
 244    * @param[in] name custom header name to remove the custom header
 245    *
 246    * @return true if succeeded, false otherwise
 247    */
 248   bool RemoveCustomHeader(const std::string& name);
 249
 250   /**
 251    * @brief Start the inspector server
 252    *
 253    * @param[in] port port number
 254    *
 255    * @return the port number
 256    */
 257   uint32_t StartInspectorServer(uint32_t port);
 258
 259   /**
 260    * @brief Stop the inspector server
 261    *
 262    * @return true if succeeded, false otherwise
 263    */
 264   bool StopInspectorServer();
 265
 266   /**
 267    * @brief Scrolls web page of view by deltaX and deltaY.
 268    *
 269    * @param[in] deltaX horizontal offset to scroll
 270    * @param[in] deltaY vertical offset to scroll
 271    */
 272   void ScrollBy(int deltaX, int deltaY);
 273
 274   /**
 275    * @brief Scrolls edge of view by deltaX and deltaY.
 276    *
 277    * @param[in] deltaX horizontal offset to scroll
 278    * @param[in] deltaY vertical offset to scroll
 279    *
 280    * @return true if succeeded, false otherwise
 281    */
 282   bool ScrollEdgeBy(int deltaX, int deltaY);
 283
 284   /**
 285    * @brief Sets an absolute scroll of the given view.
 286    */
 287   void SetScrollPosition(int x, int y);
 288
 289   /**
 290    * @brief Gets the current scroll position of the given view.
 291    */
 292   Dali::Vector2 GetScrollPosition() const;
 293
 294   /**
 295    * @brief Gets the possible scroll size of the given view.
 296    */
 297   Dali::Vector2 GetScrollSize() const;
 298
 299   /**
 300    * @brief Gets the last known content's size.
 301    */
 302   Dali::Vector2 GetContentSize() const;
 303
 304   /**
 305    * @brief Returns whether forward is possible.
 306    *
 307    * @return True if forward is possible, false otherwise
 308    */
 309   bool CanGoForward();
 310
 311   /**
 312    * @brief Goes to forward.
 313    */
 314   void GoForward();
 315
 316   /**
 317    * @brief Returns whether backward is possible.
 318    *
 319    * @return True if backward is possible, false otherwise
 320    */
 321   bool CanGoBack();
 322
 323   /**
 324    * @brief Goes to back.
 325    */
 326   void GoBack();
 327
 328   /**
 329    * @brief Evaluates JavaScript code represented as a string.
 330    *
 331    * @param[in] script The JavaScript code
 332    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 333    */
 334   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
 335
 336   /**
 337    * @brief Add a message handler into JavaScript.
 338    *
 339    * @param[in] exposedObjectName The name of exposed object
 340    * @param[in] handler The callback function
 341    */
 342   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
 343
 344   /**
 345    * @brief Register a callback for JavaScript alert.
 346    *
 347    * @param[in] callback The callback function
 348    */
 349   void RegisterJavaScriptAlertCallback(Dali::WebEnginePlugin::JavaScriptAlertCallback callback);
 350
 351   /**
 352    * @brief Reply for JavaScript alert.
 353    */
 354   void JavaScriptAlertReply();
 355
 356   /**
 357    * @brief Register a callback for JavaScript confirm.
 358    *
 359    * @param[in] callback The callback function
 360    */
 361   void RegisterJavaScriptConfirmCallback(Dali::WebEnginePlugin::JavaScriptConfirmCallback callback);
 362
 363   /**
 364    * @brief Reply for JavaScript confirm.
 365    * @param[in] confirmed True if confirmed, false otherwise.
 366    */
 367   void JavaScriptConfirmReply(bool confirmed);
 368
 369   /**
 370    * @brief Register a callback for JavaScript prompt.
 371    *
 372    * @param[in] callback The callback function
 373    */
 374   void RegisterJavaScriptPromptCallback(Dali::WebEnginePlugin::JavaScriptPromptCallback callback);
 375
 376   /**
 377    * @brief Reply for JavaScript prompt.
 378    * @param[in] result The result returned from input-field in prompt popup.
 379    */
 380   void JavaScriptPromptReply(const std::string& result);
 381
 382   /**
 383    * @brief Clears the history of Web.
 384    */
 385   void ClearHistory();
 386
 387   /**
 388    * @brief Clears all tiles resources of Web.
 389    */
 390   void ClearAllTilesResources();
 391
 392   /**
 393    * @brief Get user agent string.
 394    *
 395    * @return The string value of user agent
 396    */
 397   const std::string& GetUserAgent() const;
 398
 399   /**
 400    * @brief Set user agent string.
 401    *
 402    * @param[in] userAgent The string value of user agent
 403    */
 404   void SetUserAgent(const std::string& userAgent);
 405
 406   /**
 407    * @brief Sets the size of Web Pages.
 408    */
 409   void SetSize(int width, int height);
 410
 411   /**
 412    * @brief Sets background color of web page.
 413    *
 414    * @param[in] color Background color
 415    */
 416   void SetDocumentBackgroundColor(Dali::Vector4 color);
 417
 418   /**
 419    * @brief Clears tiles when hidden.
 420    *
 421    * @param[in] cleared Whether tiles are cleared or not
 422    */
 423   void ClearTilesWhenHidden(bool cleared);
 424
 425   /**
 426    * @brief Sets multiplier of cover area of tile.
 427    *
 428    * @param[in] multiplier The multiplier of cover area
 429    */
 430   void SetTileCoverAreaMultiplier(float multiplier);
 431
 432   /**
 433    * @brief Enables cursor by client.
 434    *
 435    * @param[in] enabled Whether cursor is enabled or not
 436    */
 437   void EnableCursorByClient(bool enabled);
 438
 439   /**
 440    * @brief Gets the selected text.
 441    *
 442    * @return the selected text
 443    */
 444   std::string GetSelectedText() const;
 445
 446   /**
 447    * @brief Sends Touch Events.
 448    */
 449   bool SendTouchEvent(const TouchEvent& touch);
 450
 451   /**
 452    * @brief Sends key Events.
 453    */
 454   bool SendKeyEvent(const KeyEvent& event);
 455
 456   /**
 457    * @brief Set focus.
 458    * @param[in] focused True if web view is focused, false otherwise
 459    */
 460   void SetFocus(bool focused);
 461
 462   /**
 463    * @brief Enables/disables mouse events. The default is enabled.
 464    *
 465    * @param[in] enabled True if mouse events are enabled, false otherwise
 466    */
 467   void EnableMouseEvents( bool enabled );
 468
 469   /**
 470    * @brief Enables/disables key events. The default is enabled.
 471    *
 472    * @param[in] enabled True if key events are enabled, false otherwise
 473    */
 474   void EnableKeyEvents( bool enabled );
 475
 476   /**
 477    * @brief Sets zoom factor of the current page.
 478    * @param[in] zoomFactor a new factor to be set.
 479    */
 480   void SetPageZoomFactor(float zoomFactor);
 481
 482   /**
 483    * @brief Queries the current zoom factor of the page。
 484    * @return The current page zoom factor.
 485    */
 486   float GetPageZoomFactor() const;
 487
 488   /**
 489    * @brief Sets the current text zoom level。.
 490    * @param[in] zoomFactor a new factor to be set.
 491    */
 492   void SetTextZoomFactor(float zoomFactor);
 493
 494   /**
 495    * @brief Gets the current text zoom level.
 496    * @return The current text zoom factor.
 497    */
 498   float GetTextZoomFactor() const;
 499
 500   /**
 501    * @brief Gets the current load progress of the page.
 502    * @return The load progress of the page.
 503    */
 504   float GetLoadProgressPercentage() const;
 505
 506   /**
 507    * @brief Scales the current page, centered at the given point.
 508    * @param[in] scaleFactor a new factor to be scaled.
 509    * @param[in] point a center coordinate.
 510    */
 511   void SetScaleFactor(float scaleFactor, Dali::Vector2 point);
 512
 513   /**
 514    * @brief Gets the current scale factor of the page.
 515    * @return The current scale factor.
 516    */
 517   float GetScaleFactor() const;
 518
 519   /**
 520    * @brief Request to activate/deactivate the accessibility usage set by web app.
 521    * @param[in] activated Activate accessibility or not.
 522    */
 523   void ActivateAccessibility(bool activated);
 524
 525   /**
 526    * @brief Request to set the current page's visibility.
 527    * @param[in] visible Visible or not.
 528    *
 529    * @return true if changed successfully, false otherwise
 530    */
 531   bool SetVisibility(bool visible);
 532
 533   /**
 534    * @brief Searches and highlights the given string in the document.
 535    * @param[in] text The text to find
 536    * @param[in] options The options to find
 537    * @param[in] maxMatchCount The maximum match count to find
 538    *
 539    * @return true if found & highlighted, false otherwise
 540    */
 541   bool HighlightText(const std::string& text, Dali::WebEnginePlugin::FindOption options, uint32_t maxMatchCount);
 542
 543   /**
 544    * @brief Add dynamic certificate path.
 545    * @param[in] host host that required client authentication
 546    * @param[in] certPath the file path stored certificate
 547    */
 548   void AddDynamicCertificatePath(const std::string& host, const std::string& certPath);
 549
 550   /**
 551    * @brief Get snapshot of the specified viewArea of page.
 552    *
 553    * @param[in] viewArea The rectangle of screen shot
 554    * @param[in] scaleFactor The scale factor
 555    *
 556    * @return pixel data of screen shot
 557    */
 558   Dali::PixelData GetScreenshot(Dali::Rect<int> viewArea, float scaleFactor);
 559
 560   /**
 561    * @brief Request to get snapshot of the specified viewArea of page asynchronously.
 562    *
 563    * @param[in] viewArea The rectangle of screen shot
 564    * @param[in] scaleFactor The scale factor
 565    * @param[in] callback The callback for screen shot
 566    *
 567    * @return true if requested successfully, false otherwise
 568    */
 569   bool GetScreenshotAsynchronously(Dali::Rect<int> viewArea, float scaleFactor, Dali::WebEnginePlugin::ScreenshotCapturedCallback callback);
 570
 571   /**
 572    * @brief Asynchronous request to check if there is a video playing in the given view.
 573    *
 574    * @param[in] callback The callback called after checking if video is playing or not
 575    *
 576    * @return true if requested successfully, false otherwise
 577    */
 578   bool CheckVideoPlayingAsynchronously(Dali::WebEnginePlugin::VideoPlayingCallback callback);
 579
 580   /**
 581    * @brief Sets callback which alled upon geolocation permission request.
 582    *
 583    * @param[in] callback The callback for requesting geolocation permission
 584    */
 585   void RegisterGeolocationPermissionCallback(Dali::WebEnginePlugin::GeolocationPermissionCallback callback);
 586
 587   /**
 588    * @brief Update display area.
 589    * @param[in] displayArea The area to display web page
 590    */
 591   void UpdateDisplayArea(Dali::Rect<int> displayArea);
 592
 593   /**
 594    * @brief Enable video hole.
 595    * @param[in] enabled True if video hole is enabled, false otherwise
 596    */
 597   void EnableVideoHole(bool enabled);
 598
 599   /**
 600    * @brief Sends hover events.
 601    * @param[in] event The hover event would be sent.
 602    */
 603   bool SendHoverEvent( const HoverEvent& event );
 604
 605   /**
 606    * @brief Sends wheel events.
 607    * @param[in] event The wheel event would be sent.
 608    */
 609   bool SendWheelEvent( const WheelEvent& event );
 610
 611   /**
 612    * @brief Connects to this signal to be notified when page loading is started.
 613    *
 614    * @return A signal object to connect with
 615    */
 616   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadStartedSignal();
 617
 618   /**
 619    * @brief Connects to this signal to be notified when page loading is in progress.
 620    *
 621    * @return A signal object to connect with
 622    */
 623   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadInProgressSignal();
 624
 625   /**
 626    * @brief Connects to this signal to be notified when page loading is finished.
 627    *
 628    * @return A signal object to connect with
 629    */
 630   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadFinishedSignal();
 631
 632   /**
 633    * @brief Connects to this signal to be notified when an error occurs in page loading.
 634    *
 635    * @return A signal object to connect with
 636    */
 637   Dali::WebEnginePlugin::WebEnginePageLoadErrorSignalType& PageLoadErrorSignal();
 638
 639   /**
 640    * @brief Connects to this signal to be notified when scroll edge is reached.
 641    *
 642    * @return A signal object to connect with
 643    */
 644   Dali::WebEnginePlugin::WebEngineScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
 645
 646   /**
 647    * @brief Connects to this signal to be notified when url is changed.
 648    *
 649    * @return A signal object to connect with
 650    */
 651   Dali::WebEnginePlugin::WebEngineUrlChangedSignalType& UrlChangedSignal();
 652
 653   /**
 654    * @brief Connects to this signal to be notified when form repost decision is requested.
 655    *
 656    * @return A signal object to connect with.
 657    */
 658   Dali::WebEnginePlugin::WebEngineFormRepostDecisionSignalType& FormRepostDecisionSignal();
 659
 660   /**
 661    * @brief Connects to this signal to be notified when frame is rendered.
 662    *
 663    * @return A signal object to connect with.
 664    */
 665   Dali::WebEnginePlugin::WebEngineFrameRenderedSignalType& FrameRenderedSignal();
 666
 667   /**
 668    * @brief Connects to this signal to be notified when http request need be intercepted.
 669    *
 670    * @return A signal object to connect with.
 671    */
 672   Dali::WebEnginePlugin::WebEngineRequestInterceptorSignalType& RequestInterceptorSignal();
 673
 674 private: // Not intended for application developers
 675   /**
 676    * @brief Internal constructor
 677    */
 678   explicit DALI_INTERNAL WebEngine(Internal::Adaptor::WebEngine* internal);
 679 };
 680
 681 } // namespace Dali
 682
 683 #endif // DALI_WEB_ENGINE_H