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