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 Get favicon of web page.
 231    *
 232    * @return Handle to a favicon
 233    */
 234   Dali::Toolkit::ImageView GetFavicon() const;
 235
 236   /**
 237    * @brief Loads a web page based on a given URL.
 238    *
 239    * @param [in] url The URL of the resource to load
 240    */
 241   void LoadUrl(const std::string& url);
 242
 243   /**
 244    * @brief Loads a given string as web contents.
 245    *
 246    * @param [in] htmlString The string to use as the contents of the web page
 247    */
 248   void LoadHtmlString(const std::string& htmlString);
 249
 250   /**
 251    * @brief Reloads the Web.
 252    */
 253   void Reload();
 254
 255   /**
 256    * @brief Stops loading web contents on the current page.
 257    */
 258   void StopLoading();
 259
 260   /**
 261    * @brief Suspends the operation associated with the view.
 262    */
 263   void Suspend();
 264
 265   /**
 266    * @brief Resumes the operation associated with the view object after calling Suspend().
 267    */
 268   void Resume();
 269
 270   /**
 271    * @brief Scrolls the webpage of view by deltaX and deltaY.
 272    * @param[in] deltaX The delta x of scroll
 273    * @param[in] deltaY The delta y of scroll
 274    */
 275   void ScrollBy( int deltaX, int deltaY );
 276
 277   /**
 278    * @brief Returns whether forward is possible.
 279    *
 280    * @return True if forward is possible, false otherwise
 281    */
 282   bool CanGoForward();
 283
 284   /**
 285    * @brief Goes forward in the navigation history.
 286    */
 287   void GoForward();
 288
 289   /**
 290    * @brief Returns whether backward is possible.
 291    *
 292    * @return True if backward is possible, false otherwise
 293    */
 294   bool CanGoBack();
 295
 296   /**
 297    * @brief Goes back in the navigation history.
 298    */
 299   void GoBack();
 300
 301   /**
 302    * @brief Evaluates JavaScript code represented as a string.
 303    *
 304    * @param[in] script The JavaScript code
 305    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 306    */
 307   void EvaluateJavaScript(const std::string& script, Dali::WebEnginePlugin::JavaScriptMessageHandlerCallback resultHandler);
 308
 309   /**
 310    * @brief Evaluates JavaScript code represented as a string.
 311    *
 312    * @param[in] script The JavaScript code
 313    */
 314   void EvaluateJavaScript(const std::string& script);
 315
 316   /**
 317    * @brief Inject a JavaScript object with a message handler into the WebView.
 318    *
 319    * @note The injected object will appear in the JavaScript context to be loaded next.
 320    *
 321    * Example:
 322    *
 323    * 1. Native
 324    *
 325    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
 326    *         printf( "Received a message from JS: %s", message.c_str() );
 327    *     });
 328    *
 329    *     // Start WebView by loading URL
 330    *     webview.LoadUrl( url );
 331    *
 332    * 2. JavaScript
 333    *
 334    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
 335    *
 336    *
 337    * @param[in] exposedObjectName The name of exposed object
 338    * @param[in] handler The callback function
 339    */
 340   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, Dali::WebEnginePlugin::JavaScriptMessageHandlerCallback handler);
 341
 342   /**
 343    * @brief Clears all tiles resources of Web.
 344    */
 345   void ClearAllTilesResources();
 346
 347   /**
 348    * @brief Clears the history of Web.
 349    */
 350   void ClearHistory();
 351
 352   /**
 353    * @brief Set or unset TTS focus of the webview.
 354    * @param[in] focused True if it is gained, false lost.
 355    * @note It only works when the webview does not have keyinput focus. If it has keyinput focus, the TTS focus is set automatically.
 356    */
 357   void SetTtsFocus(bool focused);
 358
 359   /**
 360    * @brief Callback to be called when page loading is started.
 361    *
 362    * @param[in] callback
 363    */
 364   void RegisterPageLoadStartedCallback(Dali::WebEnginePlugin::WebEnginePageLoadCallback callback);
 365
 366   /**
 367    * @brief Callback to be called when page loading is finished.
 368    *
 369    * @param[in] callback
 370    */
 371   void RegisterPageLoadFinishedCallback(Dali::WebEnginePlugin::WebEnginePageLoadCallback callback);
 372
 373   /**
 374    * @brief Callback to be called when an error occurs in page loading.
 375    *
 376    * @param[in] callback
 377    */
 378   void RegisterPageLoadErrorCallback(Dali::WebEnginePlugin::WebEnginePageLoadErrorCallback callback);
 379
 380   /**
 381    * @brief Callback to be called when scroll edge is reached.
 382    *
 383    * @param[in] callback
 384    */
 385   void RegisterScrollEdgeReachedCallback(Dali::WebEnginePlugin::WebEngineScrollEdgeReachedCallback callback);
 386
 387   /**
 388    * @brief Callback to be called when url is changed.
 389    *
 390    * @param[in] callback
 391    */
 392   void RegisterUrlChangedCallback(Dali::WebEnginePlugin::WebEngineUrlChangedCallback callback);
 393
 394   /**
 395    * @brief Callback to be called when navigation policy would be decided.
 396    *
 397    * @param[in] callback
 398    */
 399   void RegisterNavigationPolicyDecidedCallback(Dali::WebEnginePlugin::WebEngineNavigationPolicyDecidedCallback callback);
 400
 401   /**
 402    * @brief Get a plain text of current web page asynchronously.
 403    *
 404    * @param[in] callback The callback function called asynchronously.
 405    */
 406   void GetPlainTextAsynchronously(Dali::WebEnginePlugin::PlainTextReceivedCallback callback);
 407
 408 public: // Not intended for application developers
 409   /// @cond internal
 410   /**
 411    * @brief Creates a handle using the Toolkit::Internal implementation.
 412    *
 413    * @param[in] implementation The WebView implementation
 414    */
 415   DALI_INTERNAL WebView(Internal::WebView& implementation);
 416
 417   /**
 418    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
 419    *
 420    * @param[in] internal A pointer to the internal CustomActor
 421    */
 422   explicit DALI_INTERNAL WebView(Dali::Internal::CustomActor* internal);
 423   /// @endcond
 424 };
 425
 426 /**
 427  * @}
 428  */
 429
 430 } // namespace Toolkit
 431
 432 } // namespace Dali
 433
 434 #endif // DALI_TOOLKIT_WEB_VIEW_H