df73d0ed6ab03f9ff7f058064e9908a4e4438a25
[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) 2021 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 #include <memory>
24
25 // INTERNAL INCLUDES
26 #include <dali-toolkit/public-api/controls/control.h>
27 #include <dali/devel-api/adaptor-framework/web-engine-plugin.h>
28
29 namespace Dali
30 {
31 namespace Toolkit
32 {
33 class ImageView;
34 class WebBackForwardList;
35 class WebContext;
36 class WebCookieManager;
37 class WebFormRepostDecision;
38 class WebSettings;
39
40 namespace Internal DALI_INTERNAL
41 {
42 class WebView;
43 } // namespace DALI_INTERNAL
44
45 /**
46  * @addtogroup dali_toolkit_controls_web_view
47  * @{
48  */
49
50 /**
51  * @brief WebView is a control for displaying web content.
52  *
53  * This enables embedding web pages in the application.
54  *
55  * For working WebView, a web engine plugin for a platform should be provided.
56  *
57  */
58 class DALI_TOOLKIT_API WebView : public Control
59 {
60 public:
61   /**
62    * @brief Enumeration for the start and end property ranges for this control.
63    */
64   enum PropertyRange
65   {
66     PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
67     PROPERTY_END_INDEX   = PROPERTY_START_INDEX + 1000,
68   };
69
70   /**
71    * @brief Enumeration for the instance of properties belonging to the WebView class.
72    */
73   struct Property
74   {
75     enum
76     {
77       /**
78        * @brief The url to load.
79        * @details name "url", type Property::STRING.
80        */
81       URL = PROPERTY_START_INDEX,
82
83       /**
84        * @brief The user agent string.
85        * @details name "userAgent", type Property::STRING.
86        */
87       USER_AGENT,
88
89       /**
90        * @brief The current position of scroll.
91        * @details name "scrollPosition", type Property::VECTOR2.
92        */
93       SCROLL_POSITION,
94
95       /**
96        * @brief The current size of scroll.
97        * @details name "scrollSize", type Property::VECTOR2.
98        * @note The value is read-only.
99        */
100       SCROLL_SIZE,
101
102       /**
103        * @brief The current size of content.
104        * @details name "contentSize", type Property::VECTOR2.
105        * @note The value is read-only.
106        */
107       CONTENT_SIZE,
108
109       /**
110        * @brief The title of web page.
111        * @details name "title", type Property::STRING.
112        * @note The value is read-only.
113        */
114       TITLE,
115
116       /**
117        * @brief Whether video hole is enabled or not.
118        * @details name "videoHoleEnabled", type Property::BOOLEAN.
119        * @note The value is read-only.
120        */
121       VIDEO_HOLE_ENABLED,
122
123       /**
124        * @brief Whether mouse event is enabled.
125        * @details name "mouseEventsEnabled", type Property::BOOLEAN.
126        * @note Default is true.
127        */
128       MOUSE_EVENTS_ENABLED,
129
130       /**
131        * @brief Whether key event is enabled.
132        * @details name "keyEventsEnabled", type Property::BOOLEAN.
133        * @note Default is true.
134        */
135       KEY_EVENTS_ENABLED,
136
137       /**
138        * @brief The background color of web page.
139        * @details name "documentBackgroundColor", type Property::VECTOR4.
140        */
141       DOCUMENT_BACKGROUND_COLOR,
142
143       /**
144        * @brief Whether tiles can be cleared or not when hidden.
145        * @details name "tilesClearedWhenHidden", type BOOLEAN.
146        */
147       TILES_CLEARED_WHEN_HIDDEN,
148
149       /**
150        * @brief The multiplier of cover area of tile when rendering web page.
151        * @details name "tileCoverAreaMultiplier", type FLOAT.
152        */
153       TILE_COVER_AREA_MULTIPLIER,
154
155       /**
156        * @brief Whether cursor is enabled or not by client.
157        * @details name "cursorEnabledByClient", type BOOLEAN.
158        */
159       CURSOR_ENABLED_BY_CLIENT,
160
161       /**
162        * @brief The selected text of web page.
163        * @details name "selectedText", type Property::STRING.
164        * @note The value is read-only.
165        */
166       SELECTED_TEXT,
167
168       /**
169        * @brief Zoom factor of web page.
170        * @details name "pageZoomFactor", type Property::FLOAT.
171        */
172       PAGE_ZOOM_FACTOR,
173
174       /**
175        * @brief Zoom factor of text.
176        * @details name "textZoomFactor", type Property::FLOAT.
177        */
178       TEXT_ZOOM_FACTOR,
179
180       /**
181        * @brief progress percentage of loading a web page.
182        * @details name "loadProgressPercentage", type Property::FLOAT.
183        * @note The value is read-only.
184        */
185       LOAD_PROGRESS_PERCENTAGE,
186     };
187   };
188
189   /**
190    * @brief WebView callback related with screen-shot captured.
191    */
192   using WebViewScreenshotCapturedCallback = std::function<void(Dali::Toolkit::ImageView)>;
193
194   /**
195    * @brief WebView signal type related with page loading.
196    */
197   using WebViewPageLoadSignalType = Signal<void(WebView, const std::string&)>;
198
199   /**
200    * @brief WebView signal type related with page loading error.
201    */
202   using WebViewPageLoadErrorSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEngineLoadError>)>;
203
204   /**
205    * @brief WebView signal type related with scroll edge reached.
206    */
207   using WebViewScrollEdgeReachedSignalType = Signal<void(WebView, Dali::WebEnginePlugin::ScrollEdge)>;
208
209   /**
210    * @brief WebView signal type related with url changed.
211    */
212   using WebViewUrlChangedSignalType = Signal<void(WebView, const std::string&)>;
213
214   /**
215    * @brief WebView signal type related with form repost decision.
216    */
217   using WebViewFormRepostDecisionSignalType = Signal<void(WebView, std::shared_ptr<Dali::Toolkit::WebFormRepostDecision>)>;
218
219   /**
220    * @brief WebView signal type related with frame rendered.
221    */
222   using WebViewFrameRenderedSignalType = Signal<void(WebView)>;
223
224   /**
225    * @brief WebView signal type related with http request interceptor.
226    */
227   using WebViewRequestInterceptorSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEngineRequestInterceptor>)>;
228
229   /**
230    * @brief WebView signal type related with console message.
231    */
232   using WebViewConsoleMessageSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEngineConsoleMessage>)>;
233
234   /**
235    * @brief WebView signal type related with policy decision.
236    */
237   using WebViewPolicyDecisionSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEnginePolicyDecision>)>;
238
239   /**
240    * @brief WebView signal type related with certificate changed.
241    */
242   using WebViewCertificateSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEngineCertificate>)>;
243
244   /**
245    * @brief WebView signal type related with http authentication.
246    */
247   using WebViewHttpAuthHandlerSignalType = Signal<void(WebView, std::shared_ptr<Dali::WebEngineHttpAuthHandler>)>;
248
249 public:
250   /**
251    * @brief Creates an initialized WebView.
252    * @return A handle to a newly allocated Dali WebView
253    *
254    * @note WebView will not display anything
255    */
256   static WebView New();
257
258   /**
259    * @brief Creates an initialized WebView.
260    *
261    * @param [in] locale The locale of Web
262    * @param [in] timezoneId The timezoneId of Web
263    */
264   static WebView New(const std::string& locale, const std::string& timezoneId);
265
266   /**
267    * @brief Creates an initialized WebView.
268    *
269    * @param [in] argc The count of arguments of Applications
270    * @param [in] argv The string array of arguments of Applications
271    */
272   static WebView New(int argc, char** argv);
273
274   /**
275    * @brief Creates an uninitialized WebView.
276    */
277   WebView();
278
279   /**
280    * @brief Destructor.
281    *
282    * This is non-virtual since derived Handel types must not contain data or virtual methods.
283    */
284   ~WebView();
285
286   /*
287    * @brief Copy constructor.
288    *
289    * @param[in] WebView WebView to copy. The copied WebView will point at the same implementation
290    */
291   WebView(const WebView& WebView);
292
293   /**
294    * @brief Assignment operator.
295    *
296    * @param[in] WebView The WebView to assign from
297    * @return The updated WebView
298    */
299   WebView& operator=(const WebView& WebView);
300
301   /**
302    * @brief Downcasts a handle to WebView handle.
303    *
304    * If handle points to a WebView, the downcast produces valid handle.
305    * If not, the returned handle is left uninitialized.
306    *
307    * @param[in] handle Handle to an object
308    * @return Handle to a WebView or an uninitialized handle
309    */
310   static WebView DownCast(BaseHandle handle);
311
312   /**
313    * @brief Get WebSettings of WebEngine.
314    */
315   Dali::Toolkit::WebSettings* GetSettings() const;
316
317   /**
318    * @brief Get WebContext of WebEngine.
319    */
320   Dali::Toolkit::WebContext* GetContext() const;
321
322   /**
323    * @brief Get CookieManager of WebEngine.
324    */
325   Dali::Toolkit::WebCookieManager* GetCookieManager() const;
326
327   /**
328    * @brief Get WebBackForwardList of WebEngine.
329    */
330   Dali::Toolkit::WebBackForwardList* GetBackForwardList() const;
331
332   /**
333    * @brief Get Favicon of web page.
334    *
335    * @return Handle to a fav icon
336    */
337   Dali::Toolkit::ImageView& GetFavicon();
338
339   /**
340    * @brief Loads a web page based on a given URL.
341    *
342    * @param [in] url The URL of the resource to load
343    */
344   void LoadUrl(const std::string& url);
345
346   /**
347    * @brief Loads a given string as web contents.
348    *
349    * @param [in] htmlString The string to use as the contents of the web page
350    */
351   void LoadHtmlString(const std::string& htmlString);
352
353   /**
354    * @brief Load the specified html string as the content of the view overriding current history entry
355    *
356    * @param[in] html HTML data to load
357    * @param[in] basicUri Base URL used for relative paths to external objects
358    * @param[in] unreachableUrl URL that could not be reached
359    *
360    * @return true if successfully loaded, false otherwise
361    */
362   bool LoadHtmlStringOverrideCurrentEntry(const std::string& html, const std::string& basicUri, const std::string& unreachableUrl);
363
364   /**
365    * @brief Requests loading the given contents by MIME type into the view object
366    *
367    * @param[in] contents The content to load
368    * @param[in] contentSize The size of contents (in bytes)
369    * @param[in] mimeType The type of contents, if 0 is given "text/html" is assumed
370    * @param[in] encoding The encoding for contents, if 0 is given "UTF-8" is assumed
371    * @param[in] baseUri The base URI to use for relative resources
372    *
373    * @return true if successfully request, false otherwise
374    */
375   bool LoadContents(const std::string& contents, uint32_t contentSize, const std::string& mimeType, const std::string& encoding, const std::string& baseUri);
376
377   /**
378    * @brief Reloads the Web.
379    */
380   void Reload();
381
382   /**
383    * @brief Reloads the current page's document without cache
384    */
385   bool ReloadWithoutCache();
386
387   /**
388    * @brief Stops loading web contents on the current page.
389    */
390   void StopLoading();
391
392   /**
393    * @brief Suspends the operation associated with the view.
394    */
395   void Suspend();
396
397   /**
398    * @brief Resumes the operation associated with the view object after calling Suspend().
399    */
400   void Resume();
401
402   /**
403    * @brief To suspend all url loading
404    */
405   void SuspendNetworkLoading();
406
407   /**
408    * @brief To resume new url network loading
409    */
410   void ResumeNetworkLoading();
411
412   /**
413    * @brief Add custom header
414    *
415    * @param[in] name custom header name to add the custom header
416    * @param[in] value custom header value to add the custom header
417    *
418    * @return true if succeeded, false otherwise
419    */
420   bool AddCustomHeader(const std::string& name, const std::string& value);
421
422   /**
423    * @brief Remove custom header
424    *
425    * @param[in] name custom header name to remove the custom header
426    *
427    * @return true if succeeded, false otherwise
428    */
429   bool RemoveCustomHeader(const std::string& name);
430
431   /**
432    * @brief Start the inspector server
433    *
434    * @param[in] port port number
435    *
436    * @return the port number
437    */
438   uint32_t StartInspectorServer(uint32_t port);
439
440   /**
441    * @brief Stop the inspector server
442    *
443    * @return true if succeeded, false otherwise
444    */
445   bool StopInspectorServer();
446
447   /**
448    * @brief Scrolls web page of view by deltaX and deltaY.
449    * @param[in] deltaX The delta x of scroll
450    * @param[in] deltaY The delta y of scroll
451    */
452   void ScrollBy(int deltaX, int deltaY);
453
454   /**
455    * @brief Scrolls edge of view by deltaX and deltaY.
456    *
457    * @param[in] deltaX horizontal offset to scroll
458    * @param[in] deltaY vertical offset to scroll
459    *
460    * @return true if succeeded, false otherwise
461    */
462   bool ScrollEdgeBy(int deltaX, int deltaY);
463
464   /**
465    * @brief Returns whether forward is possible.
466    *
467    * @return True if forward is possible, false otherwise
468    */
469   bool CanGoForward();
470
471   /**
472    * @brief Goes forward in the navigation history.
473    */
474   void GoForward();
475
476   /**
477    * @brief Returns whether backward is possible.
478    *
479    * @return True if backward is possible, false otherwise
480    */
481   bool CanGoBack();
482
483   /**
484    * @brief Goes back in the navigation history.
485    */
486   void GoBack();
487
488   /**
489    * @brief Evaluates JavaScript code represented as a string.
490    *
491    * @param[in] script The JavaScript code
492    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result
493    */
494   void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler);
495
496   /**
497    * @brief Evaluates JavaScript code represented as a string.
498    *
499    * @param[in] script The JavaScript code
500    */
501   void EvaluateJavaScript(const std::string& script);
502
503   /**
504    * @brief Inject a JavaScript object with a message handler into the WebView.
505    *
506    * @note The injected object will appear in the JavaScript context to be loaded next.
507    *
508    * Example:
509    *
510    * 1. Native
511    *
512    *     webview.AddJavaScriptMessageHandler( "myObject", []( const std::string& message ) {
513    *         printf( "Received a message from JS: %s", message.c_str() );
514    *     });
515    *
516    *     // Start WebView by loading URL
517    *     webview.LoadUrl( url );
518    *
519    * 2. JavaScript
520    *
521    *     myObject.postMessage( "Hello World!" ); // "Received a message from JS: Hello World!"
522    *
523    *
524    * @param[in] exposedObjectName The name of exposed object
525    * @param[in] handler The callback function
526    */
527   void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler);
528
529   /**
530    * @brief Register alert callback for javascript.
531    *
532    * @param[in] callback The callback function to be called by the JavaScript runtime.
533    */
534   void RegisterJavaScriptAlertCallback(Dali::WebEnginePlugin::JavaScriptAlertCallback callback);
535
536   /**
537    * @brief Reply for JavaScript alert.
538    */
539   void JavaScriptAlertReply();
540
541   /**
542    * @brief Register confirm callback for javascript.
543    *
544    * @param[in] callback The callback function to be called by the JavaScript runtime.
545    */
546   void RegisterJavaScriptConfirmCallback(Dali::WebEnginePlugin::JavaScriptConfirmCallback callback);
547
548   /**
549    * @brief Reply for JavaScript confirm.
550    * @param[in] confirmed True if confirmed, false otherwise
551    */
552   void JavaScriptConfirmReply(bool confirmed);
553
554   /**
555    * @brief Register prompt callback for javascript.
556    *
557    * @param[in] callback The callback function to be called by the JavaScript runtime.
558    */
559   void RegisterJavaScriptPromptCallback(Dali::WebEnginePlugin::JavaScriptPromptCallback callback);
560
561   /**
562    * @brief Reply for JavaScript prompt.
563    * @param[in] result The result from input-field of prompt popup.
564    */
565   void JavaScriptPromptReply(const std::string& result);
566
567   /**
568    * @brief Clears the history of Web.
569    */
570   void ClearHistory();
571
572   /**
573    * @brief Clears all tiles resources of Web.
574    */
575   void ClearAllTilesResources();
576
577   /**
578    * @brief Scales the current page, centered at the given point.
579    * @param[in] scaleFactor a new factor to be scaled.
580    * @param[in] point a center coordinate.
581    */
582   void SetScaleFactor(float scaleFactor, Dali::Vector2 point);
583
584   /**
585    * @brief Gets the current scale factor of the page.
586    * @return The current scale factor.
587    */
588   float GetScaleFactor() const;
589
590   /**
591    * @brief Request to activate/deactivate the accessibility usage set by web app.
592    * @param[in] activated Activate accessibility or not.
593    */
594   void ActivateAccessibility(bool activated);
595
596   /**
597    * @brief Searches and highlights the given string in the document.
598    * @param[in] text The text to find
599    * @param[in] options The options to find
600    * @param[in] maxMatchCount The maximum match count to find
601    *
602    * @return true if found & highlighted, false otherwise
603    */
604   bool HighlightText(const std::string& text, Dali::WebEnginePlugin::FindOption options, uint32_t maxMatchCount);
605
606   /**
607    * @brief Add dynamic certificate path.
608    * @param[in] host host that required client authentication
609    * @param[in] certPath the file path stored certificate
610    */
611   void AddDynamicCertificatePath(const std::string& host, const std::string& certPath);
612
613   /**
614    * @brief Get snapshot of the specified viewArea of page.
615    *
616    * @param[in] viewArea The rectangle of screen shot
617    * @param[in] scaleFactor The scale factor
618    *
619    * @return image view of screen shot
620    */
621   Dali::Toolkit::ImageView GetScreenshot(Dali::Rect<int> viewArea, float scaleFactor);
622
623   /**
624    * @brief Request to get snapshot of the specified viewArea of page asynchronously.
625    *
626    * @param[in] viewArea The rectangle of screen shot
627    * @param[in] scaleFactor The scale factor
628    * @param[in] callback The callback for screen shot
629    *
630    * @return true if requested successfully, false otherwise
631    */
632   bool GetScreenshotAsynchronously(Dali::Rect<int> viewArea, float scaleFactor, WebViewScreenshotCapturedCallback callback);
633
634   /**
635    * @brief Asynchronous request to check if there is a video playing in the given view.
636    *
637    * @param[in] callback The callback called after checking if video is playing or not
638    *
639    * @return true if requested successfully, false otherwise
640    */
641   bool CheckVideoPlayingAsynchronously(Dali::WebEnginePlugin::VideoPlayingCallback callback);
642
643   /**
644    * @brief Sets callback which will be called upon geolocation permission request.
645    *
646    * @param[in] callback The callback for requesting geolocation permission
647    */
648   void RegisterGeolocationPermissionCallback(Dali::WebEnginePlugin::GeolocationPermissionCallback callback);
649
650   /**
651    * @brief Connects to this signal to be notified when page loading is started.
652    *
653    * @return A signal object to connect with
654    */
655   WebViewPageLoadSignalType& PageLoadStartedSignal();
656
657   /**
658    * @brief Connects to this signal to be notified when page loading is in progress.
659    *
660    * @return A signal object to connect with
661    */
662   WebViewPageLoadSignalType& PageLoadInProgressSignal();
663
664   /**
665    * @brief Connects to this signal to be notified when page loading is finished.
666    *
667    * @return A signal object to connect with
668    */
669   WebViewPageLoadSignalType& PageLoadFinishedSignal();
670
671   /**
672    * @brief Connects to this signal to be notified when an error occurs in page loading.
673    *
674    * @return A signal object to connect with
675    */
676   WebViewPageLoadErrorSignalType& PageLoadErrorSignal();
677
678   /**
679    * @brief Connects to this signal to be notified when scroll edge is reached.
680    *
681    * @return A signal object to connect with
682    */
683   WebViewScrollEdgeReachedSignalType& ScrollEdgeReachedSignal();
684
685   /**
686    * @brief Connects to this signal to be notified when url is changed.
687    *
688    * @return A signal object to connect with
689    */
690   WebViewUrlChangedSignalType& UrlChangedSignal();
691
692   /**
693    * @brief Connects to this signal to be notified when form repost decision is requested.
694    *
695    * @return A signal object to connect with.
696    */
697   WebViewFormRepostDecisionSignalType& FormRepostDecisionSignal();
698
699   /**
700    * @brief Connects to this signal to be notified when frame is rendered.
701    *
702    * @return A signal object to connect with.
703    */
704   WebViewFrameRenderedSignalType& FrameRenderedSignal();
705
706   /**
707    * @brief Connects to this signal to be notified when http request need be intercepted.
708    *
709    * @return A signal object to connect with.
710    */
711   WebViewRequestInterceptorSignalType& RequestInterceptorSignal();
712
713   /**
714    * @brief Connects to this signal to be notified when console message will be logged.
715    *
716    * @return A signal object to connect with.
717    */
718   WebViewConsoleMessageSignalType& ConsoleMessageSignal();
719
720   /**
721    * @brief Connects to this signal to be notified when new policy would be decided.
722    *
723    * @return A signal object to connect with.
724    */
725   WebViewPolicyDecisionSignalType& PolicyDecisionSignal();
726
727   /**
728    * @brief Connects to this signal to be notified when certificate need be confirmed.
729    *
730    * @return A signal object to connect with.
731    */
732   WebViewCertificateSignalType& CertificateConfirmSignal();
733
734   /**
735    * @brief Connects to this signal to be notified when ssl certificate is changed.
736    *
737    * @return A signal object to connect with.
738    */
739   WebViewCertificateSignalType& SslCertificateChangedSignal();
740
741   /**
742    * @brief Connects to this signal to be notified when http authentication need be confirmed.
743    *
744    * @return A signal object to connect with.
745    */
746   WebViewHttpAuthHandlerSignalType& HttpAuthHandlerSignal();
747
748 public: // Not intended for application developers
749   /// @cond internal
750   /**
751    * @brief Creates a handle using the Toolkit::Internal implementation.
752    *
753    * @param[in] implementation The WebView implementation
754    */
755   DALI_INTERNAL WebView(Internal::WebView& implementation);
756
757   /**
758    * @brief Allows the creation of this WebView from an Internal::CustomActor pointer.
759    *
760    * @param[in] internal A pointer to the internal CustomActor
761    */
762   explicit DALI_INTERNAL WebView(Dali::Internal::CustomActor* internal);
763   /// @endcond
764 };
765
766 /**
767  * @}
768  */
769
770 } // namespace Toolkit
771
772 } // namespace Dali
773
774 #endif // DALI_TOOLKIT_WEB_VIEW_H