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

   1 #ifndef DALI_WEB_ENGINE_PLUGIN_H
   2 #define DALI_WEB_ENGINE_PLUGIN_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/images/native-image-interface.h>
  23 #include <dali/public-api/math/rect.h>
  24 #include <dali/public-api/signals/dali-signal.h>
  25 #include <functional>
  26 #include <memory>
  27
  28 namespace Dali
  29 {
  30 class KeyEvent;
  31 class PixelData;
  32 class TouchEvent;
  33 class WebEngineBackForwardList;
  34 class WebEngineContext;
  35 class WebEngineCookieManager;
  36 class WebEngineFormRepostDecision;
  37 class WebEngineSettings;
  38 class HoverEvent;
  39 class WheelEvent;
  40
  41 /**
  42  * @brief WebEnginePlugin is an abstract interface, used by dali-adaptor to access WebEngine plugin.
  43  * A concrete implementation must be created for each platform and provided as dynamic library.
  44  */
  45 class WebEnginePlugin
  46 {
  47 public:
  48   /**
  49    * @brief WebEngine signal type related with page loading.
  50    */
  51   using WebEnginePageLoadSignalType = Signal<void(const std::string&)>;
  52
  53   /**
  54    * @brief WebView signal type related with page loading error.
  55    */
  56   using WebEnginePageLoadErrorSignalType = Signal<void(const std::string&, int)>;
  57
  58   // forward declaration.
  59   enum class ScrollEdge;
  60
  61   /**
  62    * @brief WebView signal type related with scroll edge reached.
  63    */
  64   using WebEngineScrollEdgeReachedSignalType = Signal<void(const ScrollEdge)>;
  65
  66   /**
  67    * @brief WebView signal type related with page url changed.
  68    */
  69   using WebEngineUrlChangedSignalType = Signal<void(const std::string&)>;
  70
  71   /**
  72    * @brief Alert callback when JavaScript alert is called with a message.
  73    *  It returns true if a pop-up is created successfully, false otherwise.
  74    */
  75   using JavaScriptAlertCallback = std::function<bool(const std::string&)>;
  76
  77   /**
  78    * @brief Confirm callback when JavaScript confirm is called with a message.
  79    *  It returns true if a pop-up is created successfully, false otherwise.
  80    */
  81   using JavaScriptConfirmCallback = std::function<bool(const std::string&)>;
  82
  83   /**
  84    * @brief Prompt callback when JavaScript prompt is called with a message
  85    *  and an optional value that is the default value for the input field.
  86    *  It returns true if a pop-up is created successfully, false otherwise.
  87    */
  88   using JavaScriptPromptCallback = std::function<bool(const std::string&, const std::string&)>;
  89
  90   /**
  91    * @brief WebView signal type related with form repost decision.
  92    */
  93   using WebEngineFormRepostDecisionSignalType = Signal<void(std::shared_ptr<Dali::WebEngineFormRepostDecision>)>;
  94
  95   /**
  96    * @brief WebView signal type related with frame rendered.
  97    */
  98   using WebEngineFrameRenderedSignalType = Signal<void(void)>;
  99
 100   /**
 101    * @brief Enumeration for the scroll edge.
 102    */
 103   enum class ScrollEdge
 104   {
 105     LEFT,   ///< Left edge reached.
 106     RIGHT,  ///< Right edge reached.
 107     TOP,    ///< Top edge reached.
 108     BOTTOM, ///< Bottom edge reached.
 109   };
 110
 111   /**
 112    * @brief Constructor.
 113    */
 114   WebEnginePlugin() = default;
 115
 116   /**
 117    * @brief Destructor.
 118    */
 119   virtual ~WebEnginePlugin() = default;
 120
 121   /**
 122    * @brief Creates WebEngine instance.
 123    *
 124    * @param [in] width The width of Web
 125    * @param [in] height The height of Web
 126    * @param [in] locale The locale of Web
 127    * @param [in] timezoneId The timezoneID of Web
 128    */
 129   virtual void Create(int width, int height, const std::string& locale, const std::string& timezoneId) = 0;
 130
 131   /**
 132    * @brief Creates WebEngine instance.
 133    *
 134    * @param [in] width The width of Web
 135    * @param [in] height The height of Web
 136    * @param [in] argc The count of application arguments
 137    * @param [in] argv The string array of application arguments
 138    */
 139   virtual void Create(int width, int height, int argc, char** argv) = 0;
 140
 141   /**
 142    * @brief Destroys WebEngine instance.
 143    */
 144   virtual void Destroy() = 0;
 145
 146   /**
 147    * @brief Get settings of WebEngine.
 148    */
 149   virtual WebEngineSettings& GetSettings() const = 0;
 150
 151   /**
 152    * @brief Get context of WebEngine.
 153    */
 154   virtual WebEngineContext& GetContext() const = 0;
 155
 156   /**
 157    * @brief Get cookie manager of WebEngine.
 158    */
 159   virtual WebEngineCookieManager& GetCookieManager() const = 0;
 160
 161   /**
 162    * @brief Get back-forward list of WebEngine.
 163    */
 164   virtual WebEngineBackForwardList& GetBackForwardList() const = 0;
 165
 166   /**
 167    * @brief Loads a web page based on a given URL.
 168    *
 169    * @param [in] url The URL of the resource to load
 170    */
 171   virtual void LoadUrl(const std::string& url) = 0;
 172
 173   /**
 174    * @brief Returns the title of the Web.
 175    *
 176    * @return The title of web page
 177    */
 178   virtual std::string GetTitle() const = 0;
 179
 180   /**
 181    * @brief Returns the Favicon of the Web.
 182    *
 183    * @return Favicon of Dali::PixelData& type
 184    */
 185   virtual Dali::PixelData GetFavicon() const = 0;
 186
 187   /**
 188    * @brief Gets image to render.
 189    */
 190   virtual NativeImageInterfacePtr GetNativeImageSource() = 0;
 191
 192   /**
 193    * @brief Returns the URL of the Web.
 194    *
 195    * @return Url of string type
 196    */
 197   virtual const std::string& GetUrl() = 0;
 198
 199   /**
 200    * @brief Loads a given string as web contents.
 201    *
 202    * @param [in] htmlString The string to use as the contents of the web page
 203    */
 204   virtual void LoadHtmlString(const std::string& htmlString) = 0;
 205
 206   /**
 207    * @brief Reloads the Web.
 208    */
 209   virtual void Reload() = 0;
 210
 211   /**
 212    * @brief Stops loading web contents on the current page.
 213    */
 214   virtual void StopLoading() = 0;
 215
 216   /**
 217    * @brief Suspends the operation associated with the view.
 218    */
 219   virtual void Suspend() = 0;
 220
 221   /**
 222    * @brief Resumes the operation associated with the view object after calling Suspend().
 223    */
 224   virtual void Resume() = 0;
 225
 226   /**
 227    * @brief Scrolls the webpage of view by deltaX and deltaY.
 228    */
 229   virtual void ScrollBy(int deltaX, int deltaY) = 0;
 230
 231   /**
 232    * @brief Scroll to the specified position of the given view.
 233    */
 234   virtual void SetScrollPosition(int x, int y) = 0;
 235
 236   /**
 237    * @brief Gets the current scroll position of the given view.
 238    */
 239   virtual Dali::Vector2 GetScrollPosition() const = 0;
 240
 241   /**
 242    * @brief Gets the possible scroll size of the given view.
 243    */
 244   virtual Dali::Vector2 GetScrollSize() const = 0;
 245
 246   /**
 247    * @brief Gets the last known content's size.
 248    */
 249   virtual Dali::Vector2 GetContentSize() const = 0;
 250
 251   /**
 252    * @brief Returns whether forward is possible.
 253    *
 254    * @return True if forward is possible, false otherwise
 255    */
 256   virtual bool CanGoForward() = 0;
 257
 258   /**
 259    * @brief Goes to forward.
 260    */
 261   virtual void GoForward() = 0;
 262
 263   /**
 264    * @brief Returns whether backward is possible.
 265    *
 266    * @return True if backward is possible, false otherwise
 267    */
 268   virtual bool CanGoBack() = 0;
 269
 270   /**
 271    * @brief Goes to back.
 272    */
 273   virtual void GoBack() = 0;
 274
 275   /**
 276    * @brief Evaluates JavaScript code represented as a string.
 277    *
 278    * @param[in] script The JavaScript code
 279    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 280    */
 281   virtual void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler) = 0;
 282
 283   /**
 284    * @brief Add a message handler into JavaScript.
 285    *
 286    * @param[in] exposedObjectName The name of exposed object
 287    * @param[in] handler The callback function
 288    */
 289   virtual void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler) = 0;
 290
 291   /**
 292    * @brief Register a callback for JavaScript alert.
 293    *
 294    * @param[in] callback The callback function
 295    */
 296   virtual void RegisterJavaScriptAlertCallback(JavaScriptAlertCallback callback) = 0;
 297
 298   /**
 299    * @brief Reply for JavaScript alert.
 300    */
 301   virtual void JavaScriptAlertReply() = 0;
 302
 303   /**
 304    * @brief Register a callback for JavaScript confirm.
 305    *
 306    * @param[in] callback The callback function
 307    */
 308   virtual void RegisterJavaScriptConfirmCallback(JavaScriptConfirmCallback callback) = 0;
 309
 310   /**
 311    * @brief Reply for JavaScript confirm.
 312    */
 313   virtual void JavaScriptConfirmReply(bool confirmed) = 0;
 314
 315   /**
 316    * @brief Register a callback for JavaScript prompt.
 317    *
 318    * @param[in] callback The callback function
 319    */
 320   virtual void RegisterJavaScriptPromptCallback(JavaScriptPromptCallback callback) = 0;
 321
 322   /**
 323    * @brief Reply for JavaScript prompt.
 324    */
 325   virtual void JavaScriptPromptReply(const std::string& result) = 0;
 326
 327   /**
 328    * @brief Clears the history of Web.
 329    */
 330   virtual void ClearHistory() = 0;
 331
 332   /**
 333    * @brief Clears all tiles resources of Web.
 334    */
 335   virtual void ClearAllTilesResources() = 0;
 336
 337   /**
 338    * @brief Get user agent string.
 339    *
 340    * @return The string value of user agent
 341    */
 342   virtual const std::string& GetUserAgent() const = 0;
 343
 344   /**
 345    * @brief Set user agent string.
 346    *
 347    * @param[in] userAgent The string value of user agent
 348    */
 349   virtual void SetUserAgent(const std::string& userAgent) = 0;
 350
 351   /**
 352    * @brief Sets size of Web Page.
 353    */
 354   virtual void SetSize(int width, int height) = 0;
 355
 356   /**
 357    * @brief Sets background color of web page.
 358    *
 359    * @param[in] color Background color
 360    */
 361   virtual void SetDocumentBackgroundColor(Dali::Vector4 color) = 0;
 362
 363   /**
 364    * @brief Clears tiles when hidden.
 365    *
 366    * @param[in] cleared Whether tiles are cleared or not
 367    */
 368   virtual void ClearTilesWhenHidden(bool cleared) = 0;
 369
 370   /**
 371    * @brief Sets multiplier of cover area of tile.
 372    *
 373    * @param[in] multiplier The multiplier of cover area
 374    */
 375   virtual void SetTileCoverAreaMultiplier(float multiplier) = 0;
 376
 377   /**
 378    * @brief Enables cursor by client.
 379    *
 380    * @param[in] enabled Whether cursor is enabled or not
 381    */
 382   virtual void EnableCursorByClient(bool enabled) = 0;
 383
 384   /**
 385    * @brief Gets the selected text.
 386    *
 387    * @return the selected text
 388    */
 389   virtual std::string GetSelectedText() const = 0;
 390
 391   /**
 392    * @brief Sends Touch Events.
 393    */
 394   virtual bool SendTouchEvent(const TouchEvent& touch) = 0;
 395
 396   /**
 397    * @brief Sends Key Events.
 398    */
 399   virtual bool SendKeyEvent(const KeyEvent& event) = 0;
 400
 401   /**
 402    * @brief Support mouse events or not.
 403    * @param[in] enabled True if enabled, false othewise.
 404    */
 405   virtual void EnableMouseEvents( bool enabled ) = 0;
 406
 407   /**
 408    * @brief Support key events or not.
 409    * @param[in] enabled True if enabled, false othewise.
 410    */
 411   virtual void EnableKeyEvents( bool enabled ) = 0;
 412
 413   /**
 414    * @brief Sets focus.
 415    * @param[in] focused True if focus is gained, false lost.
 416    */
 417   virtual void SetFocus(bool focused) = 0;
 418
 419   /**
 420    * @brief Update display area.
 421    * @param[in] displayArea The display area need be updated.
 422    */
 423   virtual void UpdateDisplayArea(Dali::Rect<int> displayArea) = 0;
 424
 425   /**
 426    * @brief Enable video hole.
 427    * @param[in] enabled True if enabled, false othewise.
 428    */
 429   virtual void EnableVideoHole(bool enabled) = 0;
 430
 431   /**
 432    * @brief Sends Hover Events.
 433    * @param[in] event The hover event would be sent.
 434    */
 435   virtual bool SendHoverEvent( const HoverEvent& event ) = 0;
 436
 437   /**
 438    * @brief Sends Wheel Events.
 439    * @param[in] event The wheel event would be sent.
 440    */
 441   virtual bool SendWheelEvent( const WheelEvent& event ) = 0;
 442
 443   /**
 444    * @brief Connects to this signal to be notified when page loading is started.
 445    *
 446    * @return A signal object to connect with.
 447    */
 448   virtual WebEnginePageLoadSignalType& PageLoadStartedSignal() = 0;
 449
 450   /**
 451    * @brief Connects to this signal to be notified when page loading is in progress.
 452    *
 453    * @return A signal object to connect with.
 454    */
 455   virtual WebEnginePageLoadSignalType& PageLoadInProgressSignal() = 0;
 456
 457   /**
 458    * @brief Connects to this signal to be notified when page loading is finished.
 459    *
 460    * @return A signal object to connect with.
 461    */
 462   virtual WebEnginePageLoadSignalType& PageLoadFinishedSignal() = 0;
 463
 464   /**
 465    * @brief Connects to this signal to be notified when an error occurs in page loading.
 466    *
 467    * @return A signal object to connect with.
 468    */
 469   virtual WebEnginePageLoadErrorSignalType& PageLoadErrorSignal() = 0;
 470
 471   /**
 472    * @brief Connects to this signal to be notified when scroll edge is reached.
 473    *
 474    * @return A signal object to connect with.
 475    */
 476   virtual WebEngineScrollEdgeReachedSignalType& ScrollEdgeReachedSignal() = 0;
 477
 478   /**
 479    * @brief Connects to this signal to be notified when url is changed.
 480    *
 481    * @return A signal object to connect with.
 482    */
 483   virtual WebEngineUrlChangedSignalType& UrlChangedSignal() = 0;
 484
 485   /**
 486    * @brief Connects to this signal to be notified when form repost decision is requested.
 487    *
 488    * @return A signal object to connect with.
 489    */
 490   virtual WebEngineFormRepostDecisionSignalType& FormRepostDecisionSignal() = 0;
 491
 492   /**
 493    * @brief Connects to this signal to be notified when frame is rendered.
 494    *
 495    * @return A signal object to connect with.
 496    */
 497   virtual WebEngineFrameRenderedSignalType& FrameRenderedSignal() = 0;
 498 };
 499
 500 } // namespace Dali
 501
 502 #endif