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