dali/devel-api/adaptor-framework/web-engine.h

   1 #ifndef DALI_WEB_ENGINE_H
   2 #define DALI_WEB_ENGINE_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 <dali/public-api/object/base-handle.h>
  23
  24 //INTERNAL INCLUDES
  25 #include <dali/devel-api/adaptor-framework/web-engine-plugin.h>
  26 #include <dali/public-api/dali-adaptor-common.h>
  27
  28 namespace Dali
  29 {
  30 namespace Internal
  31 {
  32 namespace Adaptor
  33 {
  34 class WebEngine;
  35 } // namespace Adaptor
  36
  37 } // namespace Internal
  38
  39 /**
  40  * @brief Proxy class to dynamically load, use and unload web engine plugin.
  41  *
  42  * The purpose of this class is to dynamically load the web engine plugin if and when its needed.
  43  * So we don't slow down every application startup if they never need web engine.
  44  */
  45 class DALI_ADAPTOR_API WebEngine : public BaseHandle
  46 {
  47 public:
  48   /**
  49    * @brief Constructor.
  50    */
  51   WebEngine();
  52
  53   /**
  54    * @brief Destructor.
  55    */
  56   ~WebEngine();
  57
  58   /**
  59    * @brief Creates a new instance of a WebEngine.
  60    */
  61   static WebEngine New();
  62
  63   /**
  64    * @brief Copy constructor.
  65    *
  66    * @param[in] WebEngine WebEngine to copy. The copied WebEngine will point at the same implementation
  67    */
  68   WebEngine(const WebEngine& WebEngine);
  69
  70   /**
  71    * @brief Assignment operator.
  72    *
  73    * @param[in] WebEngine The WebEngine to assign from.
  74    * @return The updated WebEngine.
  75    */
  76   WebEngine& operator=(const WebEngine& WebEngine);
  77
  78   /**
  79    * @brief Downcast a handle to WebEngine handle.
  80    *
  81    * If handle points to a WebEngine the downcast produces valid
  82    * handle. If not the returned handle is left uninitialized.
  83    *
  84    * @param[in] handle Handle to an object
  85    * @return Handle to a WebEngine or an uninitialized handle
  86    */
  87   static WebEngine DownCast(BaseHandle handle);
  88
  89   /**
  90    * @brief Creates WebEngine instance.
  91    *
  92    * @param [in] width The width of Web
  93    * @param [in] height The height of Web
  94    * @param [in] locale The locale of Web
  95    * @param [in] timezoneId The timezoneID of Web
  96    */
  97   void Create(int width, int height, const std::string& locale, const std::string& timezoneId);
  98
  99   /**
 100    * @brief Destroys WebEngine instance.
 101    */
 102   void Destroy();
 103
 104   /**
 105    * @brief Gets native image source to render.
 106    */
 107   NativeImageInterfacePtr GetNativeImageSource();
 108
 109   /**
 110    * @brief Loads a web page based on a given URL.
 111    *
 112    * @param [in] url The URL of the resource to load
 113    */
 114   void LoadUrl(const std::string& url);
 115
 116   /**
 117    * @brief Gets the url.
 118    */
 119   const std::string& GetUrl();
 120
 121   /**
 122    * @brief Loads a given string as web contents.
 123    *
 124    * @param [in] htmlString The string to use as the contents of the web page
 125    */
 126   void LoadHTMLString(const std::string& htmlString);
 127
 128   /**
 129    * @brief Reloads the Web.
 130    */
 131   void Reload();
 132
 133   /**
 134    * @brief Stops loading web contents on the current page.
 135    */
 136   void StopLoading();
 137
 138   /**
 139    * @brief Suspends the operation associated with the view.
 140    */
 141   void Suspend();
 142
 143   /**
 144    * @brief Resumes the operation associated with the view object after calling Suspend().
 145    */
 146   void Resume();
 147
 148   /**
 149    * @brief Scrolls the webpage of view by deltaX and deltaY.
 150    */
 151   void ScrollBy( int deltaX, int deltaY );
 152
 153   /**
 154    * @brief Sets an absolute scroll of the given view.
 155    */
 156   void SetScrollPosition( int x, int y );
 157
 158   /**
 159    * @brief Gets the current scroll position of the given view.
 160    */
 161   void GetScrollPosition( int& x, int& y ) const;
 162
 163   /**
 164    * @brief Gets the possible scroll size of the given view.
 165    */
 166   void GetScrollSize( int& width, int& height ) const;
 167
 168   /**
 169    * @brief Gets the last known content's size.
 170    */
 171   void GetContentSize( int& width, int& height ) const;
 172
 173   /**
 174    * @brief Returns whether forward is possible.
 175    *
 176    * @return True if forward is possible, false otherwise
 177    */
 178   bool CanGoForward();
 179
 180   /**
 181    * @brief Goes to forward.
 182    */
 183   void GoForward();
 184
 185   /**
 186    * @brief Returns whether backward is possible.
 187    *
 188    * @return True if backward is possible, false otherwise
 189    */
 190   bool CanGoBack();
 191
 192   /**
 193    * @brief Goes to back.
 194    */
 195   void GoBack();
 196
 197   /**
 198    * @brief Evaluates JavaScript code represented as a string.
 199    *
 200    * @param[in] script The JavaScript code
 201    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
 202    */
 203   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
 204
 205   /**
 206    * @brief Add a message handler into JavaScript.
 207    *
 208    * @param[in] exposedObjectName The name of exposed object
 209    * @param[in] handler The callback function
 210    */
 211   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
 212
 213   /**
 214    * @brief Clears the history of Web.
 215    */
 216   void ClearHistory();
 217
 218   /**
 219    * @brief Clears the cache of Web.
 220    */
 221   void ClearCache();
 222
 223   /**
 224    * @brief Clears all the cookies of Web.
 225    */
 226   void ClearCookies();
 227
 228   /**
 229    * @brief Get cache model option. The default is DOCUMENT_VIEWER.
 230    *
 231    * @return The cache model option
 232    */
 233   Dali::WebEnginePlugin::CacheModel GetCacheModel() const;
 234
 235   /**
 236    * @brief Set cache model option. The default is DOCUMENT_VIEWER.
 237    *
 238    * @param[in] cacheModel The cache model option
 239    */
 240   void SetCacheModel(Dali::WebEnginePlugin::CacheModel cacheModel);
 241
 242   /**
 243    * @brief Gets the cookie acceptance policy. The default is NO_THIRD_PARTY.
 244    *
 245    * @return The cookie acceptance policy
 246    */
 247   Dali::WebEnginePlugin::CookieAcceptPolicy GetCookieAcceptPolicy() const;
 248
 249   /**
 250    * @brief Sets the cookie acceptance policy. The default is NO_THIRD_PARTY.
 251    *
 252    * @param[in] policy The cookie acceptance policy
 253    */
 254   void SetCookieAcceptPolicy(Dali::WebEnginePlugin::CookieAcceptPolicy policy);
 255
 256   /**
 257    * @brief Get user agent string.
 258    *
 259    * @return The string value of user agent
 260    */
 261   const std::string& GetUserAgent() const;
 262
 263   /**
 264    * @brief Set user agent string.
 265    *
 266    * @param[in] userAgent The string value of user agent
 267    */
 268   void SetUserAgent(const std::string& userAgent);
 269
 270   /**
 271    * @brief Returns whether JavaScript can be executable. The default is true.
 272    *
 273    * @return true if JavaScript executing is enabled, false otherwise
 274    */
 275   bool IsJavaScriptEnabled() const;
 276
 277   /**
 278    * @brief Enables/disables JavaScript executing. The default is enabled.
 279    *
 280    * @param[in] enabled True if JavaScript executing is enabled, false otherwise
 281    */
 282   void EnableJavaScript(bool enabled);
 283
 284   /**
 285    * @brief Returns whether JavaScript can be executable. The default is true.
 286    *
 287    * @return true if images are loaded automatically, false otherwise
 288    */
 289   bool AreImagesAutomaticallyLoaded() const;
 290
 291   /**
 292    * @brief Enables/disables auto loading of images. The default is enabled.
 293    *
 294    * @param[in] automatic True if images are loaded automatically, false otherwise
 295    */
 296   void LoadImagesAutomatically(bool automatic);
 297
 298   /**
 299    * @brief Gets the default text encoding name.
 300    *
 301    * @return The default text encoding name
 302    */
 303   const std::string& GetDefaultTextEncodingName() const;
 304
 305   /**
 306    * @brief Sets the default text encoding name.
 307    *
 308    * @param[in] defaultTextEncodingName The default text encoding name
 309    */
 310   void SetDefaultTextEncodingName(const std::string& defaultTextEncodingName);
 311
 312   /**
 313    * @brief Returns the default font size in pixel. The default value is 16.
 314    *
 315    * @return The default font size
 316    */
 317   int GetDefaultFontSize() const;
 318
 319   /**
 320    * @brief Sets the default font size in pixel. The default value is 16.
 321    *
 322    * @param[in] defaultFontSize A new default font size to set
 323    */
 324   void SetDefaultFontSize(int defaultFontSize);
 325
 326   /**
 327    * @brief Sets the size of Web Pages.
 328    */
 329   void SetSize(int width, int height);
 330
 331   /**
 332    * @brief Sends Touch Events.
 333    */
 334   bool SendTouchEvent(const TouchEvent& touch);
 335
 336   /**
 337    * @brief Sends key Events.
 338    */
 339   bool SendKeyEvent(const KeyEvent& event);
 340
 341   /**
 342    * @brief Set focus.
 343    */
 344   void SetFocus( bool focused );
 345
 346   /**
 347    * @brief Connects to this signal to be notified when page loading is started.
 348    *
 349    * @return A signal object to connect with.
 350    */
 351   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadStartedSignal();
 352
 353   /**
 354    * @brief Connects to this signal to be notified when page loading is finished.
 355    *
 356    * @return A signal object to connect with.
 357    */
 358   Dali::WebEnginePlugin::WebEnginePageLoadSignalType& PageLoadFinishedSignal();
 359
 360   /**
 361    * @brief Connects to this signal to be notified when an error occurs in page loading.
 362    *
 363    * @return A signal object to connect with.
 364    */
 365   Dali::WebEnginePlugin::WebEnginePageLoadErrorSignalType& PageLoadErrorSignal();
 366
 367   /**
 368    * @brief Connects to this signal to be notified when scroll edge is reached.
 369    *
 370    * @return A signal object to connect with.
 371    */
 372   Dali::WebEnginePlugin::WebEngineScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
 373
 374 private: // Not intended for application developers
 375   /**
 376    * @brief Internal constructor
 377    */
 378   explicit DALI_INTERNAL WebEngine(Internal::Adaptor::WebEngine* internal);
 379 };
 380
 381 } // namespace Dali
 382
 383 #endif // DALI_WEB_ENGINE_H