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 Reloads the Web.
 174    */
 175   void Reload();
 176
 177   /**
 178    * @brief Stops loading web contents on the current page.
 179    */
 180   void StopLoading();
 181
 182   /**
 183    * @brief Suspends the operation associated with the view.
 184    */
 185   void Suspend();
 186
 187   /**
 188    * @brief Resumes the operation associated with the view object after calling Suspend().
 189    */
 190   void Resume();
 191
 192   /**
 193    * @brief Scrolls the webpage of view by deltaX and deltaY.
 194    */
 195   void ScrollBy(int deltaX, int deltaY);
 196
 197   /**
 198    * @brief Sets an absolute scroll of the given view.
 199    */
 200   void SetScrollPosition(int x, int y);
 201
 202   /**
 203    * @brief Gets the current scroll position of the given view.
 204    */
 205   Dali::Vector2 GetScrollPosition() const;
 206
 207   /**
 208    * @brief Gets the possible scroll size of the given view.
 209    */
 210   Dali::Vector2 GetScrollSize() const;
 211
 212   /**
 213    * @brief Gets the last known content's size.
 214    */
 215   Dali::Vector2 GetContentSize() const;
 216
 217   /**
 218    * @brief Returns whether forward is possible.
 219    *
 220    * @return True if forward is possible, false otherwise
 221    */
 222   bool CanGoForward();
 223
 224   /**
 225    * @brief Goes to forward.
 226    */
 227   void GoForward();
 228
 229   /**
 230    * @brief Returns whether backward is possible.
 231    *
 232    * @return True if backward is possible, false otherwise
 233    */
 234   bool CanGoBack();
 235
 236   /**
 237    * @brief Goes to back.
 238    */
 239   void GoBack();
 240
 241   /**
 242    * @brief Evaluates JavaScript code represented as a string.
 243    *
 244    * @param[in] script The JavaScript code
 245    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 246    */
 247   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
 248
 249   /**
 250    * @brief Add a message handler into JavaScript.
 251    *
 252    * @param[in] exposedObjectName The name of exposed object
 253    * @param[in] handler The callback function
 254    */
 255   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
 256
 257   /**
 258    * @brief Register a callback for JavaScript alert.
 259    *
 260    * @param[in] callback The callback function
 261    */
 262   void RegisterJavaScriptAlertCallback(Dali::WebEnginePlugin::JavaScriptAlertCallback callback);
 263
 264   /**
 265    * @brief Reply for JavaScript alert.
 266    */
 267   void JavaScriptAlertReply();
 268
 269   /**
 270    * @brief Register a callback for JavaScript confirm.
 271    *
 272    * @param[in] callback The callback function
 273    */
 274   void RegisterJavaScriptConfirmCallback(Dali::WebEnginePlugin::JavaScriptConfirmCallback callback);
 275
 276   /**
 277    * @brief Reply for JavaScript confirm.
 278    * @param[in] confirmed True if confirmed, false otherwise.
 279    */
 280   void JavaScriptConfirmReply(bool confirmed);
 281
 282   /**
 283    * @brief Register a callback for JavaScript prompt.
 284    *
 285    * @param[in] callback The callback function
 286    */
 287   void RegisterJavaScriptPromptCallback(Dali::WebEnginePlugin::JavaScriptPromptCallback callback);
 288
 289   /**
 290    * @brief Reply for JavaScript prompt.
 291    * @param[in] result The result returned from input-field in prompt popup.
 292    */
 293   void JavaScriptPromptReply(const std::string& result);
 294
 295   /**
 296    * @brief Clears the history of Web.
 297    */
 298   void ClearHistory();
 299
 300   /**
 301    * @brief Clears all tiles resources of Web.
 302    */
 303   void ClearAllTilesResources();
 304
 305   /**
 306    * @brief Get user agent string.
 307    *
 308    * @return The string value of user agent
 309    */
 310   const std::string& GetUserAgent() const;
 311
 312   /**
 313    * @brief Set user agent string.
 314    *
 315    * @param[in] userAgent The string value of user agent
 316    */
 317   void SetUserAgent(const std::string& userAgent);
 318
 319   /**
 320    * @brief Sets the size of Web Pages.
 321    */
 322   void SetSize(int width, int height);
 323
 324   /**
 325    * @brief Sets background color of web page.
 326    *
 327    * @param[in] color Background color
 328    */
 329   void SetDocumentBackgroundColor(Dali::Vector4 color);
 330
 331   /**
 332    * @brief Clears tiles when hidden.
 333    *
 334    * @param[in] cleared Whether tiles are cleared or not
 335    */
 336   void ClearTilesWhenHidden(bool cleared);
 337
 338   /**
 339    * @brief Sets multiplier of cover area of tile.
 340    *
 341    * @param[in] multiplier The multiplier of cover area
 342    */
 343   void SetTileCoverAreaMultiplier(float multiplier);
 344
 345   /**
 346    * @brief Enables cursor by client.
 347    *
 348    * @param[in] enabled Whether cursor is enabled or not
 349    */
 350   void EnableCursorByClient(bool enabled);
 351
 352   /**
 353    * @brief Gets the selected text.
 354    *
 355    * @return the selected text
 356    */
 357   std::string GetSelectedText() const;
 358
 359   /**
 360    * @brief Sends Touch Events.
 361    */
 362   bool SendTouchEvent(const TouchEvent& touch);
 363
 364   /**
 365    * @brief Sends key Events.
 366    */
 367   bool SendKeyEvent(const KeyEvent& event);
 368
 369   /**
 370    * @brief Set focus.
 371    * @param[in] focused True if web view is focused, false otherwise
 372    */
 373   void SetFocus(bool focused);
 374
 375   /**
 376    * @brief Enables/disables mouse events. The default is enabled.
 377    *
 378    * @param[in] enabled True if mouse events are enabled, false otherwise
 379    */
 380   void EnableMouseEvents( bool enabled );
 381
 382   /**
 383    * @brief Enables/disables key events. The default is enabled.
 384    *
 385    * @param[in] enabled True if key events are enabled, false otherwise
 386    */
 387   void EnableKeyEvents( bool enabled );
 388
 389   /**
 390    * @brief Update display area.
 391    * @param[in] displayArea The area to display web page.
 392    */
 393   void UpdateDisplayArea(Dali::Rect<int> displayArea);
 394
 395   /**
 396    * @brief Enable video hole.
 397    * @param[in] enabled True if video hole is enabled, false otherwise
 398    */
 399   void EnableVideoHole(bool enabled);
 400
 401   /**
 402    * @brief Sends hover events.
 403    * @param[in] event The hover event would be sent.
 404    */
 405   bool SendHoverEvent( const HoverEvent& event );
 406
 407   /**
 408    * @brief Sends wheel events.
 409    * @param[in] event The wheel event would be sent.
 410    */
 411   bool SendWheelEvent( const WheelEvent& event );
 412
 413   /**
 414    * @brief Connects to this signal to be notified when page loading is started.
 415    *
 416    * @return A signal object to connect with.
 417    */
 418   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadStartedSignal();
 419
 420   /**
 421    * @brief Connects to this signal to be notified when page loading is in progress.
 422    *
 423    * @return A signal object to connect with.
 424    */
 425   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadInProgressSignal();
 426
 427   /**
 428    * @brief Connects to this signal to be notified when page loading is finished.
 429    *
 430    * @return A signal object to connect with.
 431    */
 432   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadFinishedSignal();
 433
 434   /**
 435    * @brief Connects to this signal to be notified when an error occurs in page loading.
 436    *
 437    * @return A signal object to connect with.
 438    */
 439   Dali::WebEnginePlugin::WebEnginePageLoadErrorSignalType& PageLoadErrorSignal();
 440
 441   /**
 442    * @brief Connects to this signal to be notified when scroll edge is reached.
 443    *
 444    * @return A signal object to connect with.
 445    */
 446   Dali::WebEnginePlugin::WebEngineScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
 447
 448   /**
 449    * @brief Connects to this signal to be notified when url is changed.
 450    *
 451    * @return A signal object to connect with.
 452    */
 453   Dali::WebEnginePlugin::WebEngineUrlChangedSignalType& UrlChangedSignal();
 454
 455   /**
 456    * @brief Connects to this signal to be notified when form repost decision is requested.
 457    *
 458    * @return A signal object to connect with.
 459    */
 460   Dali::WebEnginePlugin::WebEngineFormRepostDecisionSignalType& FormRepostDecisionSignal();
 461
 462   /**
 463    * @brief Connects to this signal to be notified when frame is rendered.
 464    *
 465    * @return A signal object to connect with.
 466    */
 467   Dali::WebEnginePlugin::WebEngineFrameRenderedSignalType& FrameRenderedSignal();
 468
 469 private: // Not intended for application developers
 470   /**
 471    * @brief Internal constructor
 472    */
 473   explicit DALI_INTERNAL WebEngine(Internal::Adaptor::WebEngine* internal);
 474 };
 475
 476 } // namespace Dali
 477
 478 #endif // DALI_WEB_ENGINE_H