8d33f3a9ea8389ba02977d7d639743d2c99dd88b
[platform/core/uifw/dali-toolkit.git] / 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