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