dali-toolkit/devel-api/controls/web-view/web-view.h

   1 #ifndef DALI_TOOLKIT_WEB_VIEW_H
   2 #define DALI_TOOLKIT_WEB_VIEW_H
   3
   4 /*
   5  * Copyright (c) 2020 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 <functional>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/devel-api/adaptor-framework/web-engine-plugin.h>
  26 #include <dali-toolkit/public-api/controls/control.h>
  27
  28 namespace Dali
  29 {
  30 namespace Toolkit
  31 {
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class WebView;
  35 } // namespace DALI_INTERNAL
  36
  37 /**
  38  * @addtogroup dali_toolkit_controls_web_view
  39  * @{
  40  */
  41
  42 /**
  43  * @brief WebView is a control for displaying web content.
  44  *
  45  * This enables embedding web pages in the application.
  46  *
  47  * For working WebView, a web engine plugin for a platform should be provided.
  48  *
  49  */
  50 class DALI_TOOLKIT_API WebView : public Control
  51 {
  52 public:
  53   /**
  54    * @brief A structure used to contain the cache model enumeration.
  55    */
  56   struct CacheModel
  57   {
  58     /**
  59      * @brief Enumeration for cache model options.
  60      */
  61     enum Type
  62     {
  63       /**
  64        * @brief Use the smallest cache capacity.
  65        */
  66       DOCUMENT_VIEWER,
  67
  68       /**
  69        * @brief Use the bigger cache capacity than DocumentBrowser.
  70        */
  71       DOCUMENT_BROWSER,
  72
  73       /**
  74        * @brief Use the biggest cache capacity.
  75        */
  76       PRIMARY_WEB_BROWSER
  77     };
  78   };
  79
  80   /**
  81    * @brief A structure used to contain the cookie acceptance policy enumeration.
  82    */
  83   struct CookieAcceptPolicy
  84   {
  85     /**
  86      * @brief Enumeration for the cookies accept policies.
  87      */
  88     enum Type
  89     {
  90       /**
  91        * @brief Accepts every cookie sent from any page.
  92        */
  93       ALWAYS,
  94
  95       /**
  96        * @brief Rejects all the cookies.
  97        */
  98       NEVER,
  99
 100       /**
 101        * @brief Accepts only cookies set by the main document that is loaded.
 102        */
 103       NO_THIRD_PARTY
 104     };
 105   };
 106
 107   /**
 108    * @brief Enumeration for the start and end property ranges for this control.
 109    */
 110   enum PropertyRange
 111   {
 112     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
 113     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,
 114   };
 115
 116   /**
 117    * @brief Enumeration for the instance of properties belonging to the WebView class.
 118    */
 119   struct Property
 120   {
 121     enum
 122     {
 123       /**
 124        * @brief The url to load.
 125        * @details name "url", type Property::STRING.
 126        */
 127       URL = PROPERTY_START_INDEX,
 128
 129       /**
 130        * @brief The cache model.
 131        * @details Name "cacheModel", type WebView::CacheModel::Type (Property::INTEGER) or Property::STRING.
 132        * @note Default is WebView::CacheModel::DOCUMENT_VIEWER.
 133        * @see WebView::CacheModel::Type
 134        */
 135       CACHE_MODEL,
 136
 137       /**
 138        * @brief The cookie acceptance policy.
 139        * @details Name "cookieAcceptPolicy", type WebView::CookieAcceptPolicy::Type (Property::INTEGER) or Property::STRING.
 140        * @note Default is WebView::CookieAcceptPolicy::NO_THIRD_PARTY.
 141        * @see WebView::CookieAcceptPolicy::Type
 142        */
 143       COOKIE_ACCEPT_POLICY,
 144
 145       /**
 146        * @brief The user agent string.
 147        * @details Name "userAgent", type Property::STRING.
 148        */
 149       USER_AGENT,
 150
 151       /**
 152        * @brief Whether JavaScript is enabled.
 153        * @details Name "enableJavaScript", type Property::BOOLEAN.
 154        * @note Default is true.
 155        */
 156       ENABLE_JAVASCRIPT,
 157
 158       /**
 159        * @brief Whether images can be loaded automatically.
 160        * @details Name "loadImagesAutomatically", type Property::BOOLEAN.
 161        * @note Default is true.
 162        */
 163       LOAD_IMAGES_AUTOMATICALLY,
 164
 165       /**
 166        * @brief The default text encoding name.
 167        * @details Name "defaultTextEncodingName", type Property::STRING.
 168        * @note If the value is not set, the web engine detects web page's text encoding.
 169        */
 170       DEFAULT_TEXT_ENCODING_NAME,
 171
 172       /**
 173        * @brief The default font size in pixel.
 174        * @details Name "defaultFontSize", type Property::INT.
 175        * @note Default is 16.
 176        */
 177       DEFAULT_FONT_SIZE,
 178
 179       /**
 180        * @brief The current position of scroll.
 181        * @details Name "scrollPosition", type Property::VECTOR2.
 182        */
 183       SCROLL_POSITION,
 184
 185       /**
 186        * @brief The current position of scroll.
 187        * @details Name "scrollSize", type Property::VECTOR2. Read-only.
 188        */
 189       SCROLL_SIZE,
 190
 191       /**
 192        * @brief The current position of scroll.
 193        * @details Name "contentSize", type Property::VECTOR2. Read-only.
 194        */
 195       CONTENT_SIZE,
 196     };
 197   };
 198
 199   /**
 200    * @brief Enumeration for indicating error code of page loading.
 201    */
 202   enum class LoadErrorCode
 203   {
 204     /**
 205      * @brief Unknown.
 206      */
 207     UNKNOWN = 0,
 208
 209     /**
 210      * @brief User canceled.
 211      */
 212     CANCELED,
 213
 214     /**
 215      * @brief Can't show the page for this MIME type.
 216      */
 217     CANT_SUPPORT_MIMETYPE,
 218
 219     /**
 220      * @brief File IO error.
 221      */
 222     FAILED_FILE_IO,
 223
 224     /**
 225      * @brief Cannot connect to the network.
 226      */
 227     CANT_CONNECT,
 228
 229     /**
 230      * @brief Fail to look up host from the DNS.
 231      */
 232     CANT_LOOKUP_HOST,
 233
 234     /**
 235      * @brief Fail to SSL/TLS handshake.
 236      */
 237     FAILED_TLS_HANDSHAKE,
 238
 239     /**
 240      * @brief Received certificate is invalid.
 241      */
 242     INVALID_CERTIFICATE,
 243
 244     /**
 245      * @brief Connection timeout.
 246      */
 247     REQUEST_TIMEOUT,
 248
 249     /**
 250      * @brief Too many redirects.
 251      */
 252     TOO_MANY_REDIRECTS,
 253
 254     /**
 255      * @brief Too many requests during this load.
 256      */
 257     TOO_MANY_REQUESTS,
 258
 259     /**
 260      * @brief Malformed URL.
 261      */
 262     BAD_URL,
 263
 264     /**
 265      * @brief Unsupported scheme.
 266      */
 267     UNSUPPORTED_SCHEME,
 268
 269     /**
 270      * @brief User authentication failed on the server.
 271      */
 272     AUTHENTICATION,
 273
 274     /**
 275      * @brief Web server has an internal server error.
 276      */
 277     INTERNAL_SERVER
 278   };
 279
 280   /**
 281    * @brief WebView signal type related with page loading.
 282    */
 283   typedef Signal<void(WebView, const std::string&)> WebViewPageLoadSignalType;
 284
 285   /**
 286    * @brief WebView signal type related with page loading error.
 287    */
 288   typedef Signal<void(WebView, const std::string&, LoadErrorCode)> WebViewPageLoadErrorSignalType;
 289
 290   /**
 291    * @brief WebView signal type related with scroll edge reached.
 292    */
 293   typedef Signal<void(WebView, Dali::WebEnginePlugin::ScrollEdge)> WebViewScrollEdgeReachedSignalType;
 294
 295 public:
 296   /**
 297    * @brief Creates an initialized WebView.
 298    * @return A handle to a newly allocated Dali WebView
 299    *
 300    * @note WebView will not display anything
 301    */
 302   static WebView New();
 303
 304   /**
 305    * @brief Creates an initialized WebView.
 306    *
 307    * @param [in] locale The locale of Web
 308    * @param [in] timezoneId The timezoneId of Web
 309    */
 310   static WebView New(const std::string& locale, const std::string& timezoneId);
 311
 312   /**
 313    * @brief Creates an uninitialized WebView.
 314    */
 315   WebView();
 316
 317   /**
 318    * @brief Destructor.
 319    *
 320    * This is non-virtual since derived Handel types must not contain data or virtual methods.
 321    */
 322   ~WebView();
 323
 324   /*
 325    * @brief Copy constructor.
 326    *
 327    * @param[in] WebView WebView to copy. The copied WebView will point at the same implementation
 328    */
 329   WebView(const WebView& WebView);
 330
 331   /**
 332    * @brief Assignment operator.
 333    *
 334    * @param[in] WebView The WebView to assign from
 335    * @return The updated WebView
 336    */
 337   WebView& operator=(const WebView& WebView);
 338
 339   /**
 340    * @brief Downcasts a handle to WebView handle.
 341    *
 342    * If handle points to a WebView, the downcast produces valid handle.
 343    * If not, the returned handle is left uninitialized.
 344    *
 345    * @param[in] handle Handle to an object
 346    * @return Handle to a WebView or an uninitialized handle
 347    */
 348   static WebView DownCast(BaseHandle handle);
 349
 350   /**
 351    * @brief Loads a web page based on a given URL.
 352    *
 353    * @param [in] url The URL of the resource to load
 354    */
 355   void LoadUrl(const std::string& url);
 356
 357   /**
 358    * @brief Loads a given string as web contents.
 359    *
 360    * @param [in] htmlString The string to use as the contents of the web page
 361    */
 362   void LoadHTMLString(const std::string& htmlString);
 363
 364   /**
 365    * @brief Reloads the Web.
 366    */
 367   void Reload();
 368
 369   /**
 370    * @brief Stops loading web contents on the current page.
 371    */
 372   void StopLoading();
 373
 374   /**
 375    * @brief Suspends the operation associated with the view.
 376    */
 377   void Suspend();
 378
 379   /**
 380    * @brief Resumes the operation associated with the view object after calling Suspend().
 381    */
 382   void Resume();
 383
 384   /**
 385    * @brief Scrolls the webpage of view by deltaX and deltaY.
 386    * @param[in] deltaX The delta x of scroll
 387    * @param[in] deltaY The delta y of scroll
 388    */
 389   void ScrollBy( int deltaX, int deltaY );
 390
 391   /**
 392    * @brief Returns whether forward is possible.
 393    *
 394    * @return True if forward is possible, false otherwise
 395    */
 396   bool CanGoForward();
 397
 398   /**
 399    * @brief Goes forward in the navigation history.
 400    */
 401   void GoForward();
 402
 403   /**
 404    * @brief Returns whether backward is possible.
 405    *
 406    * @return True if backward is possible, false otherwise
 407    */
 408   bool CanGoBack();
 409
 410   /**
 411    * @brief Goes back in the navigation history.
 412    */
 413   void GoBack();
 414
 415   /**
 416    * @brief Evaluates JavaScript code represented as a string.
 417    *
 418    * @param[in] script The JavaScript code
 419    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 420    */
 421   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
 422
 423   /**
 424    * @brief Evaluates JavaScript code represented as a string.
 425    *
 426    * @param[in] script The JavaScript code
 427    */
 428   void EvaluateJavaScript(const std::string& script);
 429
 430   /**
 431    * @brief Inject a JavaScript object with a message handler into the WebView.
 432    *
 433    * @note The injected object will appear in the JavaScript context to be loaded next.
 434    *
 435    * Example:
 436    *
 437    * 1. Native
 438    *
 439    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
 440    *         printf( "Received a message from JS: %s", message.c_str() );
 441    *     });
 442    *
 443    *     // Start WebView by loading URL
 444    *     webview.LoadUrl( url );
 445    *
 446    * 2. JavaScript
 447    *
 448    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
 449    *
 450    *
 451    * @param[in] exposedObjectName The name of exposed object
 452    * @param[in] handler The callback function
 453    */
 454   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
 455
 456   /**
 457    * @brief Clears the history of Web.
 458    */
 459   void ClearHistory();
 460
 461   /**
 462    * @brief Clears the cache of Web.
 463    */
 464   void ClearCache();
 465
 466   /**
 467    * @brief Clears all the cookies of Web.
 468    */
 469   void ClearCookies();
 470
 471   /**
 472    * @brief Connects to this signal to be notified when page loading is started.
 473    *
 474    * @return A signal object to connect with
 475    */
 476   WebViewPageLoadSignalType& PageLoadStartedSignal();
 477
 478   /**
 479    * @brief Connects to this signal to be notified when page loading is finished.
 480    *
 481    * @return A signal object to connect with
 482    */
 483   WebViewPageLoadSignalType& PageLoadFinishedSignal();
 484
 485   /**
 486    * @brief Connects to this signal to be notified when an error occurs in page loading.
 487    *
 488    * @return A signal object to connect with.
 489    */
 490   WebViewPageLoadErrorSignalType& PageLoadErrorSignal();
 491
 492   /**
 493    * @brief Connects to this signal to be notified when scroll edge is reached.
 494    *
 495    * @return A signal object to connect with.
 496    */
 497   WebViewScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
 498
 499 public: // Not intended for application developers
 500   /// @cond internal
 501   /**
 502    * @brief Creates a handle using the Toolkit::Internal implementation.
 503    *
 504    * @param[in] implementation The WebView implementation
 505    */
 506   DALI_INTERNAL WebView(Internal::WebView& implementation);
 507
 508   /**
 509    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
 510    *
 511    * @param[in] internal A pointer to the internal CustomActor
 512    */
 513   explicit DALI_INTERNAL WebView(Dali::Internal::CustomActor* internal);
 514   /// @endcond
 515 };
 516
 517 /**
 518  * @}
 519  */
 520
 521 } // namespace Toolkit
 522
 523 } // namespace Dali
 524
 525 #endif // DALI_TOOLKIT_WEB_VIEW_H