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   /**
 147    * @brief WebView signal type related with page loading.
 148    */
 149   using WebViewPageLoadSignalType = Signal< void( WebView, const std::string& ) >;
 150
 151   /**
 152    * @brief WebView signal type related with page loading error.
 153    */
 154   using WebViewPageLoadErrorSignalType = Signal< void( WebView, const std::string&, LoadErrorCode ) >;
 155
 156   /**
 157    * @brief WebView signal type related with scroll edge reached.
 158    */
 159   using WebViewScrollEdgeReachedSignalType = Signal< void( WebView, Dali::WebEnginePlugin::ScrollEdge ) >;
 160
 161 public:
 162   /**
 163    * @brief Creates an initialized WebView.
 164    * @return A handle to a newly allocated Dali WebView
 165    *
 166    * @note WebView will not display anything
 167    */
 168   static WebView New();
 169
 170   /**
 171    * @brief Creates an initialized WebView.
 172    *
 173    * @param [in] locale The locale of Web
 174    * @param [in] timezoneId The timezoneId of Web
 175    */
 176   static WebView New(const std::string& locale, const std::string& timezoneId);
 177
 178   /**
 179    * @brief Creates an initialized WebView.
 180    *
 181    * @param [in] argc The count of arguments of Applications
 182    * @param [in] argv The string array of arguments of Applications
 183    */
 184   static WebView New( int argc, char** argv );
 185
 186   /**
 187    * @brief Creates an uninitialized WebView.
 188    */
 189   WebView();
 190
 191   /**
 192    * @brief Destructor.
 193    *
 194    * This is non-virtual since derived Handel types must not contain data or virtual methods.
 195    */
 196   ~WebView();
 197
 198   /*
 199    * @brief Copy constructor.
 200    *
 201    * @param[in] WebView WebView to copy. The copied WebView will point at the same implementation
 202    */
 203   WebView(const WebView& WebView);
 204
 205   /**
 206    * @brief Assignment operator.
 207    *
 208    * @param[in] WebView The WebView to assign from
 209    * @return The updated WebView
 210    */
 211   WebView& operator=(const WebView& WebView);
 212
 213   /**
 214    * @brief Downcasts a handle to WebView handle.
 215    *
 216    * If handle points to a WebView, the downcast produces valid handle.
 217    * If not, the returned handle is left uninitialized.
 218    *
 219    * @param[in] handle Handle to an object
 220    * @return Handle to a WebView or an uninitialized handle
 221    */
 222   static WebView DownCast(BaseHandle handle);
 223
 224   /**
 225    * @brief Get WebSettings of WebEngine.
 226    */
 227   Dali::Toolkit::WebSettings* GetSettings() const;
 228
 229   /**
 230    * @brief Get WebContext of WebEngine.
 231    */
 232   Dali::Toolkit::WebContext* GetContext() const;
 233
 234   /**
 235    * @brief Get CookieManager of WebEngine.
 236    */
 237   Dali::Toolkit::WebCookieManager* GetCookieManager() const;
 238
 239   /**
 240    * @brief Get WebBackForwardList of WebEngine.
 241    */
 242   Dali::Toolkit::WebBackForwardList* GetBackForwardList() const;
 243
 244   /**
 245    * @brief Get Favicon of web page.
 246    *
 247    * @return Handle to a fav icon
 248    */
 249   Dali::Toolkit::ImageView& GetFavicon();
 250
 251   /**
 252    * @brief Loads a web page based on a given URL.
 253    *
 254    * @param [in] url The URL of the resource to load
 255    */
 256   void LoadUrl(const std::string& url);
 257
 258   /**
 259    * @brief Loads a given string as web contents.
 260    *
 261    * @param [in] htmlString The string to use as the contents of the web page
 262    */
 263   void LoadHtmlString(const std::string& htmlString);
 264
 265   /**
 266    * @brief Reloads the Web.
 267    */
 268   void Reload();
 269
 270   /**
 271    * @brief Stops loading web contents on the current page.
 272    */
 273   void StopLoading();
 274
 275   /**
 276    * @brief Suspends the operation associated with the view.
 277    */
 278   void Suspend();
 279
 280   /**
 281    * @brief Resumes the operation associated with the view object after calling Suspend().
 282    */
 283   void Resume();
 284
 285   /**
 286    * @brief Scrolls the webpage of view by deltaX and deltaY.
 287    * @param[in] deltaX The delta x of scroll
 288    * @param[in] deltaY The delta y of scroll
 289    */
 290   void ScrollBy( int deltaX, int deltaY );
 291
 292   /**
 293    * @brief Returns whether forward is possible.
 294    *
 295    * @return True if forward is possible, false otherwise
 296    */
 297   bool CanGoForward();
 298
 299   /**
 300    * @brief Goes forward in the navigation history.
 301    */
 302   void GoForward();
 303
 304   /**
 305    * @brief Returns whether backward is possible.
 306    *
 307    * @return True if backward is possible, false otherwise
 308    */
 309   bool CanGoBack();
 310
 311   /**
 312    * @brief Goes back in the navigation history.
 313    */
 314   void GoBack();
 315
 316   /**
 317    * @brief Evaluates JavaScript code represented as a string.
 318    *
 319    * @param[in] script The JavaScript code
 320    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 321    */
 322   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
 323
 324   /**
 325    * @brief Evaluates JavaScript code represented as a string.
 326    *
 327    * @param[in] script The JavaScript code
 328    */
 329   void EvaluateJavaScript(const std::string& script);
 330
 331   /**
 332    * @brief Inject a JavaScript object with a message handler into the WebView.
 333    *
 334    * @note The injected object will appear in the JavaScript context to be loaded next.
 335    *
 336    * Example:
 337    *
 338    * 1. Native
 339    *
 340    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
 341    *         printf( "Received a message from JS: %s", message.c_str() );
 342    *     });
 343    *
 344    *     // Start WebView by loading URL
 345    *     webview.LoadUrl( url );
 346    *
 347    * 2. JavaScript
 348    *
 349    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
 350    *
 351    *
 352    * @param[in] exposedObjectName The name of exposed object
 353    * @param[in] handler The callback function
 354    */
 355   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
 356
 357   /**
 358    * @brief Clears all tiles resources of Web.
 359    */
 360   void ClearAllTilesResources();
 361
 362   /**
 363    * @brief Clears the history of Web.
 364    */
 365   void ClearHistory();
 366
 367   /**
 368    * @brief Connects to this signal to be notified when page loading is started.
 369    *
 370    * @return A signal object to connect with
 371    */
 372   WebViewPageLoadSignalType& PageLoadStartedSignal();
 373
 374   /**
 375    * @brief Connects to this signal to be notified when page loading is finished.
 376    *
 377    * @return A signal object to connect with
 378    */
 379   WebViewPageLoadSignalType& PageLoadFinishedSignal();
 380
 381   /**
 382    * @brief Connects to this signal to be notified when an error occurs in page loading.
 383    *
 384    * @return A signal object to connect with.
 385    */
 386   WebViewPageLoadErrorSignalType& PageLoadErrorSignal();
 387
 388   /**
 389    * @brief Connects to this signal to be notified when scroll edge is reached.
 390    *
 391    * @return A signal object to connect with.
 392    */
 393   WebViewScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
 394
 395 public: // Not intended for application developers
 396   /// @cond internal
 397   /**
 398    * @brief Creates a handle using the Toolkit::Internal implementation.
 399    *
 400    * @param[in] implementation The WebView implementation
 401    */
 402   DALI_INTERNAL WebView(Internal::WebView& implementation);
 403
 404   /**
 405    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
 406    *
 407    * @param[in] internal A pointer to the internal CustomActor
 408    */
 409   explicit DALI_INTERNAL WebView(Dali::Internal::CustomActor* internal);
 410   /// @endcond
 411 };
 412
 413 /**
 414  * @}
 415  */
 416
 417 } // namespace Toolkit
 418
 419 } // namespace Dali
 420
 421 #endif // DALI_TOOLKIT_WEB_VIEW_H