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 size of scroll.
  96        * @details name "scrollSize", type Property::VECTOR2.
  97        * @note The value is read-only.
  98        */
  99       SCROLL_SIZE,
 100
 101       /**
 102        * @brief The current size of content.
 103        * @details name "contentSize", type Property::VECTOR2.
 104        * @note The value is read-only.
 105        */
 106       CONTENT_SIZE,
 107
 108       /**
 109        * @brief The title of web page.
 110        * @details name "title", type Property::STRING.
 111        * @note The value is read-only.
 112        */
 113       TITLE,
 114
 115       /**
 116        * @brief Whether video hole is enabled or not.
 117        * @details name "videoHoleEnabled", type Property::BOOLEAN.
 118        * @note The value is read-only.
 119        */
 120       VIDEO_HOLE_ENABLED,
 121     };
 122   };
 123
 124   /**
 125    * @brief Enumeration for indicating error code of page loading.
 126    */
 127   enum class LoadErrorCode
 128   {
 129     UNKNOWN = 0,            ///< Unknown.
 130     CANCELED,               ///< User canceled.
 131     CANT_SUPPORT_MIMETYPE,  ///< Can't show the page for this MIME type.
 132     FAILED_FILE_IO,         ///< File IO error.
 133     CANT_CONNECT,           ///< Cannot connect to the network.
 134     CANT_LOOKUP_HOST,       ///< Fail to look up host from the DNS.
 135     FAILED_TLS_HANDSHAKE,   ///< Fail to SSL/TLS handshake.
 136     INVALID_CERTIFICATE,    ///< Received certificate is invalid.
 137     REQUEST_TIMEOUT,        ///< Connection timeout.
 138     TOO_MANY_REDIRECTS,     ///< Too many redirects.
 139     TOO_MANY_REQUESTS,      ///< Too many requests during this load.
 140     BAD_URL,                ///< Malformed URL.
 141     UNSUPPORTED_SCHEME,     ///< Unsupported scheme.
 142     AUTHENTICATION,         ///< User authentication failed on the server.
 143     INTERNAL_SERVER         ///< Web server has an internal server error.
 144   };
 145
 146 public:
 147   /**
 148    * @brief Creates an initialized WebView.
 149    * @return A handle to a newly allocated Dali WebView
 150    *
 151    * @note WebView will not display anything
 152    */
 153   static WebView New();
 154
 155   /**
 156    * @brief Creates an initialized WebView.
 157    *
 158    * @param [in] locale The locale of Web
 159    * @param [in] timezoneId The timezoneId of Web
 160    */
 161   static WebView New(const std::string& locale, const std::string& timezoneId);
 162
 163   /**
 164    * @brief Creates an initialized WebView.
 165    *
 166    * @param [in] argc The count of arguments of Applications
 167    * @param [in] argv The string array of arguments of Applications
 168    */
 169   static WebView New( int argc, char** argv );
 170
 171   /**
 172    * @brief Creates an uninitialized WebView.
 173    */
 174   WebView();
 175
 176   /**
 177    * @brief Destructor.
 178    *
 179    * This is non-virtual since derived Handel types must not contain data or virtual methods.
 180    */
 181   ~WebView();
 182
 183   /*
 184    * @brief Copy constructor.
 185    *
 186    * @param[in] WebView WebView to copy. The copied WebView will point at the same implementation
 187    */
 188   WebView(const WebView& WebView);
 189
 190   /**
 191    * @brief Assignment operator.
 192    *
 193    * @param[in] WebView The WebView to assign from
 194    * @return The updated WebView
 195    */
 196   WebView& operator=(const WebView& WebView);
 197
 198   /**
 199    * @brief Downcasts a handle to WebView handle.
 200    *
 201    * If handle points to a WebView, the downcast produces valid handle.
 202    * If not, the returned handle is left uninitialized.
 203    *
 204    * @param[in] handle Handle to an object
 205    * @return Handle to a WebView or an uninitialized handle
 206    */
 207   static WebView DownCast(BaseHandle handle);
 208
 209   /**
 210    * @brief Get WebSettings of WebEngine.
 211    */
 212   Dali::Toolkit::WebSettings* GetSettings() const;
 213
 214   /**
 215    * @brief Get WebContext of WebEngine.
 216    */
 217   Dali::Toolkit::WebContext* GetContext() const;
 218
 219   /**
 220    * @brief Get CookieManager of WebEngine.
 221    */
 222   Dali::Toolkit::WebCookieManager* GetCookieManager() const;
 223
 224   /**
 225    * @brief Get WebBackForwardList of WebEngine.
 226    */
 227   Dali::Toolkit::WebBackForwardList* GetBackForwardList() const;
 228
 229   /**
 230    * @brief Gets web engine plugin.
 231    */
 232   Dali::WebEnginePlugin* GetPlugin() const;
 233
 234   /**
 235    * @brief Get favicon of web page.
 236    *
 237    * @return Handle to a favicon
 238    */
 239   Dali::Toolkit::ImageView GetFavicon() const;
 240
 241   /**
 242    * @brief Loads a web page based on a given URL.
 243    *
 244    * @param [in] url The URL of the resource to load
 245    */
 246   void LoadUrl(const std::string& url);
 247
 248   /**
 249    * @brief Loads a given string as web contents.
 250    *
 251    * @param [in] htmlString The string to use as the contents of the web page
 252    */
 253   void LoadHtmlString(const std::string& htmlString);
 254
 255   /**
 256    * @brief Reloads the Web.
 257    */
 258   void Reload();
 259
 260   /**
 261    * @brief Stops loading web contents on the current page.
 262    */
 263   void StopLoading();
 264
 265   /**
 266    * @brief Suspends the operation associated with the view.
 267    */
 268   void Suspend();
 269
 270   /**
 271    * @brief Resumes the operation associated with the view object after calling Suspend().
 272    */
 273   void Resume();
 274
 275   /**
 276    * @brief Scrolls the webpage of view by deltaX and deltaY.
 277    * @param[in] deltaX The delta x of scroll
 278    * @param[in] deltaY The delta y of scroll
 279    */
 280   void ScrollBy( int deltaX, int deltaY );
 281
 282   /**
 283    * @brief Returns whether forward is possible.
 284    *
 285    * @return True if forward is possible, false otherwise
 286    */
 287   bool CanGoForward();
 288
 289   /**
 290    * @brief Goes forward in the navigation history.
 291    */
 292   void GoForward();
 293
 294   /**
 295    * @brief Returns whether backward is possible.
 296    *
 297    * @return True if backward is possible, false otherwise
 298    */
 299   bool CanGoBack();
 300
 301   /**
 302    * @brief Goes back in the navigation history.
 303    */
 304   void GoBack();
 305
 306   /**
 307    * @brief Evaluates JavaScript code represented as a string.
 308    *
 309    * @param[in] script The JavaScript code
 310    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 311    */
 312   void EvaluateJavaScript(const std::string& script, Dali::WebEnginePlugin::JavaScriptMessageHandlerCallback resultHandler);
 313
 314   /**
 315    * @brief Evaluates JavaScript code represented as a string.
 316    *
 317    * @param[in] script The JavaScript code
 318    */
 319   void EvaluateJavaScript(const std::string& script);
 320
 321   /**
 322    * @brief Inject a JavaScript object with a message handler into the WebView.
 323    *
 324    * @note The injected object will appear in the JavaScript context to be loaded next.
 325    *
 326    * Example:
 327    *
 328    * 1. Native
 329    *
 330    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
 331    *         printf( "Received a message from JS: %s", message.c_str() );
 332    *     });
 333    *
 334    *     // Start WebView by loading URL
 335    *     webview.LoadUrl( url );
 336    *
 337    * 2. JavaScript
 338    *
 339    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
 340    *
 341    *
 342    * @param[in] exposedObjectName The name of exposed object
 343    * @param[in] handler The callback function
 344    */
 345   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, Dali::WebEnginePlugin::JavaScriptMessageHandlerCallback handler);
 346
 347   /**
 348    * @brief Clears all tiles resources of Web.
 349    */
 350   void ClearAllTilesResources();
 351
 352   /**
 353    * @brief Clears the history of Web.
 354    */
 355   void ClearHistory();
 356
 357   /**
 358    * @brief Set or unset TTS focus of the webview.
 359    * @param[in] focused True if it is gained, false lost.
 360    * @note It only works when the webview does not have keyinput focus. If it has keyinput focus, the TTS focus is set automatically.
 361    */
 362   void SetTtsFocus(bool focused);
 363
 364   /**
 365    * @brief Callback to be called when page loading is started.
 366    *
 367    * @param[in] callback
 368    */
 369   void RegisterPageLoadStartedCallback(Dali::WebEnginePlugin::WebEnginePageLoadCallback callback);
 370
 371   /**
 372    * @brief Callback to be called when page loading is finished.
 373    *
 374    * @param[in] callback
 375    */
 376   void RegisterPageLoadFinishedCallback(Dali::WebEnginePlugin::WebEnginePageLoadCallback callback);
 377
 378   /**
 379    * @brief Callback to be called when an error occurs in page loading.
 380    *
 381    * @param[in] callback
 382    */
 383   void RegisterPageLoadErrorCallback(Dali::WebEnginePlugin::WebEnginePageLoadErrorCallback callback);
 384
 385   /**
 386    * @brief Callback to be called when scroll edge is reached.
 387    *
 388    * @param[in] callback
 389    */
 390   void RegisterScrollEdgeReachedCallback(Dali::WebEnginePlugin::WebEngineScrollEdgeReachedCallback callback);
 391
 392   /**
 393    * @brief Callback to be called when url is changed.
 394    *
 395    * @param[in] callback
 396    */
 397   void RegisterUrlChangedCallback(Dali::WebEnginePlugin::WebEngineUrlChangedCallback callback);
 398
 399   /**
 400    * @brief Callback to be called when navigation policy would be decided.
 401    *
 402    * @param[in] callback
 403    */
 404   void RegisterNavigationPolicyDecidedCallback(Dali::WebEnginePlugin::WebEngineNavigationPolicyDecidedCallback callback);
 405
 406   /**
 407    * @brief Callback to be called when a new window would be created.
 408    *
 409    * @param[in] callback
 410    */
 411   void RegisterNewWindowCreatedCallback(Dali::WebEnginePlugin::WebEngineNewWindowCreatedCallback callback);
 412
 413   /**
 414    * @brief Get a plain text of current web page asynchronously.
 415    *
 416    * @param[in] callback The callback function called asynchronously.
 417    */
 418   void GetPlainTextAsynchronously(Dali::WebEnginePlugin::PlainTextReceivedCallback callback);
 419
 420 public: // Not intended for application developers
 421   /// @cond internal
 422   /**
 423    * @brief Creates a handle using the Toolkit::Internal implementation.
 424    *
 425    * @param[in] implementation The WebView implementation
 426    */
 427   DALI_INTERNAL WebView(Internal::WebView& implementation);
 428
 429   /**
 430    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
 431    *
 432    * @param[in] internal A pointer to the internal CustomActor
 433    */
 434   explicit DALI_INTERNAL WebView(Dali::Internal::CustomActor* internal);
 435   /// @endcond
 436 };
 437
 438 /**
 439  * @}
 440  */
 441
 442 } // namespace Toolkit
 443
 444 } // namespace Dali
 445
 446 #endif // DALI_TOOLKIT_WEB_VIEW_H