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) 2018 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-toolkit/public-api/controls/control.h>
  26
  27 namespace Dali
  28 {
  29
  30 namespace Toolkit
  31 {
  32
  33 namespace Internal DALI_INTERNAL
  34 {
  35   class WebView;
  36 } // namespace Internal
  37
  38 /**
  39  * @addtogroup dali_toolkit_controls_web_view
  40  * @{
  41  */
  42
  43 /**
  44  * @brief WebView is a control for displaying web content.
  45  *
  46  * This enables embedding web pages in the application.
  47  *
  48  * For working WebView, a web engine plugin for a platform should be provided.
  49  *
  50  */
  51 class DALI_TOOLKIT_API WebView : public Control
  52 {
  53 public:
  54
  55   /**
  56    * @brief Enumeration for the start and end property ranges for this control.
  57    */
  58   enum PropertyRange
  59   {
  60     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
  61     PROPERTY_END_INDEX = PROPERTY_START_INDEX + 1000,
  62   };
  63
  64   /**
  65    * @brief Enumeration for the instance of properties belonging to the WebView class.
  66    */
  67   struct Property
  68   {
  69     enum
  70     {
  71       /**
  72        * @brief name "url", type string
  73        *
  74        * @details Sets the url to load
  75        */
  76       URL = PROPERTY_START_INDEX
  77     };
  78   };
  79
  80   typedef Signal< void ( WebView, const std::string& ) > WebViewSignalType;
  81
  82 public:
  83
  84   /**
  85    * @brief Creates an initialized WebView.
  86    * @return A handle to a newly allocated Dali WebView
  87    *
  88    * @note WebView will not display anything
  89    */
  90   static WebView New();
  91
  92   /**
  93    * @brief Creates an initialized WebView.
  94    *
  95    * @param [in] locale The locale of Web
  96    * @param [in] timezoneId The timezoneId of Web
  97    */
  98   static WebView New( const std::string& locale, const std::string& timezoneId );
  99
 100   /**
 101    * @brief Creates an uninitialized WebView.
 102    */
 103   WebView();
 104
 105   /**
 106    * @brief Destructor.
 107    *
 108    * This is non-virtual since derived Handel types must not contain data or virtual methods.
 109    */
 110   ~WebView();
 111
 112   /*
 113    * @brief Copy constructor.
 114    *
 115    * @param[in] WebView WebView to copy. The copied WebView will point at the same implementation
 116    */
 117   WebView( const WebView& WebView );
 118
 119   /**
 120    * @brief Assignment operator.
 121    *
 122    * @param[in] WebView The WebView to assign from
 123    * @return The updated WebView
 124    */
 125   WebView& operator=( const WebView& WebView );
 126
 127   /**
 128    * @brief Downcasts a handle to WebView handle.
 129    *
 130    * If handle points to a WebView, the downcast produces valid handle.
 131    * If not, the returned handle is left uninitialized.
 132    *
 133    * @param[in] handle Handle to an object
 134    * @return Handle to a WebView or an uninitialized handle
 135    */
 136   static WebView DownCast( BaseHandle handle );
 137
 138   /**
 139    * @brief Loads a web page based on a given URL.
 140    *
 141    * @param [in] url The URL of the resource to load
 142    */
 143   void LoadUrl( const std::string& url );
 144
 145   /**
 146    * @brief Returns the URL of the Web.
 147    *
 148    * @return Url of string type
 149    */
 150   const std::string& GetUrl();
 151
 152   /**
 153    * @brief Loads a given string as web contents.
 154    *
 155    * @param [in] htmlString The string to use as the contents of the web page
 156    */
 157   void LoadHTMLString( const std::string& htmlString );
 158
 159   /**
 160    * @brief Reloads the Web.
 161    */
 162   void Reload();
 163
 164   /**
 165    * @brief Stops loading web contents on the current page.
 166    */
 167   void StopLoading();
 168
 169   /**
 170    * @brief Returns whether forward is possible.
 171    *
 172    * @return True if forward is possible, false otherwise
 173    */
 174   bool CanGoForward();
 175
 176   /**
 177    * @brief Goes forward in the navigation history.
 178    */
 179   void GoForward();
 180
 181   /**
 182    * @brief Returns whether backward is possible.
 183    *
 184    * @return True if backward is possible, false otherwise
 185    */
 186   bool CanGoBack();
 187
 188   /**
 189    * @brief Goes back in the navigation history.
 190    */
 191   void GoBack();
 192
 193   /**
 194    * @brief Evaluates JavaScript code represented as a string.
 195    *
 196    * @param[in] script The JavaScript code
 197    */
 198   void EvaluateJavaScript( const std::string& script );
 199
 200   /**
 201    * @brief Inject a JavaScript object with a message handler into the WebView.
 202    *
 203    * @note The injected object will appear in the JavaScript context to be loaded next.
 204    *
 205    * Example:
 206    *
 207    * 1. Native
 208    *
 209    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
 210    *         printf( "Received a message from JS: %s", message.c_str() );
 211    *     });
 212    *
 213    *     // Start WebView by loading URL
 214    *     webview.LoadUrl( url );
 215    *
 216    * 2. JavaScript
 217    *
 218    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
 219    *
 220    *
 221    * @param[in] exposedObjectName The name of exposed object
 222    * @param[in] handler The callback function
 223    */
 224   void AddJavaScriptMessageHandler( const std::string& exposedObjectName, std::function< void( const std::string& ) > handler );
 225
 226   /**
 227    * @brief Clears the history of Web.
 228    */
 229   void ClearHistory();
 230
 231   /**
 232    * @brief Clears the cache of Web.
 233    */
 234   void ClearCache();
 235
 236   /**
 237    * @brief Connects to this signal to be notified when page loading is started.
 238    *
 239    * @return A signal object to connect with
 240    */
 241   WebViewSignalType& PageLoadStartedSignal();
 242
 243   /**
 244    * @brief Connects to this signal to be notified when page loading is finished.
 245    *
 246    * @return A signal object to connect with
 247    */
 248   WebViewSignalType& PageLoadFinishedSignal();
 249
 250 public: // Not intended for application developers
 251
 252   /// @cond internal
 253   /**
 254    * @brief Creates a handle using the Toolkit::Internal implementation.
 255    *
 256    * @param[in] implementation The WebView implementation
 257    */
 258   DALI_INTERNAL WebView( Internal::WebView& implementation );
 259
 260   /**
 261    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
 262    *
 263    * @param[in] internal A pointer to the internal CustomActor
 264    */
 265   explicit DALI_INTERNAL WebView( Dali::Internal::CustomActor* internal );
 266   /// @endcond
 267
 268 };
 269
 270 /**
 271  * @}
 272  */
 273
 274 } // namespace Toolkit
 275
 276 } // namespace Dali
 277
 278 #endif // DALI_TOOLKIT_WEB_VIEW_H