Add some APIs into web engine.
[platform/core/uifw/dali-adaptor.git] / dali / devel-api / adaptor-framework / web-engine-plugin.h
1 #ifndef DALI_WEB_ENGINE_PLUGIN_H
2 #define DALI_WEB_ENGINE_PLUGIN_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 <dali/devel-api/common/bitwise-enum.h>
23 #include <dali/public-api/images/native-image-interface.h>
24 #include <dali/public-api/math/rect.h>
25 #include <dali/public-api/signals/dali-signal.h>
26 #include <functional>
27 #include <memory>
28
29 namespace Dali
30 {
31 class KeyEvent;
32 class PixelData;
33 class TouchEvent;
34 class WebEngineBackForwardList;
35 class WebEngineContext;
36 class WebEngineCookieManager;
37 class WebEngineFormRepostDecision;
38 class WebEngineSettings;
39 class HoverEvent;
40 class WheelEvent;
41
42 /**
43  * @brief WebEnginePlugin is an abstract interface, used by dali-adaptor to access WebEngine plugin.
44  * A concrete implementation must be created for each platform and provided as dynamic library.
45  */
46 class WebEnginePlugin
47 {
48 public:
49   /**
50    * @brief WebEngine signal type related with page loading.
51    */
52   using WebEnginePageLoadSignalType = Signal<void(const std::string&)>;
53
54   /**
55    * @brief WebView signal type related with page loading error.
56    */
57   using WebEnginePageLoadErrorSignalType = Signal<void(const std::string&, int)>;
58
59   // forward declaration.
60   enum class ScrollEdge;
61
62   /**
63    * @brief WebView signal type related with scroll edge reached.
64    */
65   using WebEngineScrollEdgeReachedSignalType = Signal<void(const ScrollEdge)>;
66
67   /**
68    * @brief WebView signal type related with page url changed.
69    */
70   using WebEngineUrlChangedSignalType = Signal<void(const std::string&)>;
71
72   /**
73    * @brief WebView signal type related with screen captured.
74    */
75   using ScreenshotCapturedCallback = std::function<void(Dali::PixelData)>;
76
77   /**
78    * @brief WebView signal type related with geolocation permission.
79    *  Host and protocol of security origin will be provided when requesting
80    *  geolocation permission.
81    *  It returns true if a pop-up is created successfully, false otherwise.
82    */
83   using GeolocationPermissionCallback = std::function<bool(const std::string&, const std::string&)>;
84
85   /**
86    * @brief WebView signal type related with video playing.
87    */
88   using VideoPlayingCallback = std::function<void(bool)>;
89
90   /**
91    * @brief Alert callback when JavaScript alert is called with a message.
92    *  It returns true if a pop-up is created successfully, false otherwise.
93    */
94   using JavaScriptAlertCallback = std::function<bool(const std::string&)>;
95
96   /**
97    * @brief Confirm callback when JavaScript confirm is called with a message.
98    *  It returns true if a pop-up is created successfully, false otherwise.
99    */
100   using JavaScriptConfirmCallback = std::function<bool(const std::string&)>;
101
102   /**
103    * @brief Prompt callback when JavaScript prompt is called with a message
104    *  and an optional value that is the default value for the input field.
105    *  It returns true if a pop-up is created successfully, false otherwise.
106    */
107   using JavaScriptPromptCallback = std::function<bool(const std::string&, const std::string&)>;
108
109   /**
110    * @brief WebView signal type related with form repost decision.
111    */
112   using WebEngineFormRepostDecisionSignalType = Signal<void(std::shared_ptr<Dali::WebEngineFormRepostDecision>)>;
113
114   /**
115    * @brief WebView signal type related with frame rendered.
116    */
117   using WebEngineFrameRenderedSignalType = Signal<void(void)>;
118
119   /**
120    * @brief Enumeration for the scroll edge.
121    */
122   enum class ScrollEdge
123   {
124     LEFT,   ///< Left edge reached.
125     RIGHT,  ///< Right edge reached.
126     TOP,    ///< Top edge reached.
127     BOTTOM, ///< Bottom edge reached.
128   };
129
130   /**
131    * @brief Enumeration that provides the option to find text.
132    */
133   enum class FindOption
134   {
135     NONE                               = 0,      ///<  No search flags, this means a case sensitive, no wrap, forward only search
136     CASE_INSENSITIVE                   = 1 << 0, ///<  Case insensitive search
137     AT_WORD_STARTS                     = 1 << 1, ///<  Search text only at the beginning of the words
138     TREAT_MEDIAL_CAPITAL_AS_WORD_START = 1 << 2, ///<  Treat capital letters in the middle of words as word start
139     BACKWARDS                          = 1 << 3, ///<  Search backwards
140     WRAP_AROUND                        = 1 << 4, ///<  If not present the search stops at the end of the document
141     SHOW_OVERLAY                       = 1 << 5, ///<  Show overlay
142     SHOW_FIND_INDICATOR                = 1 << 6, ///<  Show indicator
143     SHOW_HIGHLIGHT                     = 1 << 7, ///<  Show highlight
144   };
145
146   /**
147    * @brief Constructor.
148    */
149   WebEnginePlugin() = default;
150
151   /**
152    * @brief Destructor.
153    */
154   virtual ~WebEnginePlugin() = default;
155
156   /**
157    * @brief Creates WebEngine instance.
158    *
159    * @param [in] width The width of Web
160    * @param [in] height The height of Web
161    * @param [in] locale The locale of Web
162    * @param [in] timezoneId The timezoneID of Web
163    */
164   virtual void Create(int width, int height, const std::string& locale, const std::string& timezoneId) = 0;
165
166   /**
167    * @brief Creates WebEngine instance.
168    *
169    * @param [in] width The width of Web
170    * @param [in] height The height of Web
171    * @param [in] argc The count of application arguments
172    * @param [in] argv The string array of application arguments
173    */
174   virtual void Create(int width, int height, int argc, char** argv) = 0;
175
176   /**
177    * @brief Destroys WebEngine instance.
178    */
179   virtual void Destroy() = 0;
180
181   /**
182    * @brief Get settings of WebEngine.
183    */
184   virtual WebEngineSettings& GetSettings() const = 0;
185
186   /**
187    * @brief Get context of WebEngine.
188    */
189   virtual WebEngineContext& GetContext() const = 0;
190
191   /**
192    * @brief Get cookie manager of WebEngine.
193    */
194   virtual WebEngineCookieManager& GetCookieManager() const = 0;
195
196   /**
197    * @brief Get back-forward list of WebEngine.
198    */
199   virtual WebEngineBackForwardList& GetBackForwardList() const = 0;
200
201   /**
202    * @brief Loads a web page based on a given URL.
203    *
204    * @param [in] url The URL of the resource to load
205    */
206   virtual void LoadUrl(const std::string& url) = 0;
207
208   /**
209    * @brief Returns the title of the Web.
210    *
211    * @return The title of web page
212    */
213   virtual std::string GetTitle() const = 0;
214
215   /**
216    * @brief Returns the Favicon of the Web.
217    *
218    * @return Favicon of Dali::PixelData& type
219    */
220   virtual Dali::PixelData GetFavicon() const = 0;
221
222   /**
223    * @brief Gets image to render.
224    */
225   virtual NativeImageInterfacePtr GetNativeImageSource() = 0;
226
227   /**
228    * @brief Returns the URL of the Web.
229    *
230    * @return Url of string type
231    */
232   virtual const std::string& GetUrl() = 0;
233
234   /**
235    * @brief Loads a given string as web contents.
236    *
237    * @param [in] htmlString The string to use as the contents of the web page
238    */
239   virtual void LoadHtmlString(const std::string& htmlString) = 0;
240
241   /**
242    * @brief Load the specified html string as the content of the view overriding current history entry
243    *
244    * @param[in] html HTML data to load
245    * @param[in] basicUri Base URL used for relative paths to external objects
246    * @param[in] unreachableUrl URL that could not be reached
247    *
248    * @return true if successfully loaded, false otherwise
249    */
250   virtual bool LoadHtmlStringOverrideCurrentEntry(const std::string& html, const std::string& basicUri, const std::string& unreachableUrl) = 0;
251
252   /**
253    * @brief Requests loading the given contents by MIME type into the view object
254    *
255    * @param[in] contents The content to load
256    * @param[in] contentSize The size of contents (in bytes)
257    * @param[in] mimeType The type of contents, if 0 is given "text/html" is assumed
258    * @param[in] encoding The encoding for contents, if 0 is given "UTF-8" is assumed
259    * @param[in] baseUri The base URI to use for relative resources
260    *
261    * @return true if successfully request, false otherwise
262    */
263   virtual bool LoadContents(const std::string& contents, uint32_t contentSize, const std::string& mimeType, const std::string& encoding, const std::string& baseUri) = 0;
264
265   /**
266    * @brief Reloads the Web.
267    */
268   virtual void Reload() = 0;
269
270   /**
271    * @brief Reloads the current page's document without cache
272    */
273   virtual bool ReloadWithoutCache() = 0;
274
275   /**
276    * @brief Stops loading web contents on the current page.
277    */
278   virtual void StopLoading() = 0;
279
280   /**
281    * @brief Suspends the operation associated with the view.
282    */
283   virtual void Suspend() = 0;
284
285   /**
286    * @brief Resumes the operation associated with the view object after calling Suspend().
287    */
288   virtual void Resume() = 0;
289
290   /**
291    * @brief To suspend all url loading
292    */
293   virtual void SuspendNetworkLoading() = 0;
294
295   /**
296    * @brief To resume new url network loading
297    */
298   virtual void ResumeNetworkLoading() = 0;
299
300   /**
301    * @brief Add custom header
302    *
303    * @param[in] name custom header name to add the custom header
304    * @param[in] value custom header value to add the custom header
305    *
306    * @return true if succeeded, false otherwise
307    */
308   virtual bool AddCustomHeader(const std::string& name, const std::string& value) = 0;
309
310   /**
311    * @brief Remove custom header
312    *
313    * @param[in] name custom header name to remove the custom header
314    *
315    * @return true if succeeded, false otherwise
316    */
317   virtual bool RemoveCustomHeader(const std::string& name) = 0;
318
319   /**
320    * @brief Start the inspector server
321    *
322    * @param[in] port port number
323    *
324    * @return the port number
325    */
326   virtual uint32_t StartInspectorServer(uint32_t port) = 0;
327
328   /**
329    * @brief Stop the inspector server
330    *
331    * @return true if succeeded, false otherwise
332    */
333   virtual bool StopInspectorServer() = 0;
334
335   /**
336    * @brief Scrolls web page of view by deltaX and deltaY.
337    *
338    * @param[in] deltaX horizontal offset to scroll
339    * @param[in] deltaY vertical offset to scroll
340    */
341   virtual void ScrollBy(int deltaX, int deltaY) = 0;
342
343   /**
344    * @brief Scrolls edge of view by deltaX and deltaY.
345    *
346    * @param[in] deltaX horizontal offset to scroll
347    * @param[in] deltaY vertical offset to scroll
348    *
349    * @return true if succeeded, false otherwise
350    */
351   virtual bool ScrollEdgeBy(int deltaX, int deltaY) = 0;
352
353   /**
354    * @brief Scroll to the specified position of the given view.
355    */
356   virtual void SetScrollPosition(int x, int y) = 0;
357
358   /**
359    * @brief Gets the current scroll position of the given view.
360    */
361   virtual Dali::Vector2 GetScrollPosition() const = 0;
362
363   /**
364    * @brief Gets the possible scroll size of the given view.
365    */
366   virtual Dali::Vector2 GetScrollSize() const = 0;
367
368   /**
369    * @brief Gets the last known content's size.
370    */
371   virtual Dali::Vector2 GetContentSize() const = 0;
372
373   /**
374    * @brief Returns whether forward is possible.
375    *
376    * @return True if forward is possible, false otherwise
377    */
378   virtual bool CanGoForward() = 0;
379
380   /**
381    * @brief Goes to forward.
382    */
383   virtual void GoForward() = 0;
384
385   /**
386    * @brief Returns whether backward is possible.
387    *
388    * @return True if backward is possible, false otherwise
389    */
390   virtual bool CanGoBack() = 0;
391
392   /**
393    * @brief Goes to back.
394    */
395   virtual void GoBack() = 0;
396
397   /**
398    * @brief Evaluates JavaScript code represented as a string.
399    *
400    * @param[in] script The JavaScript code
401    * @param[in] resultHandler The callback function to be called by the JavaScript runtime. This carries evaluation result.
402    */
403   virtual void EvaluateJavaScript(const std::string& script, std::function<void(const std::string&)> resultHandler) = 0;
404
405   /**
406    * @brief Add a message handler into JavaScript.
407    *
408    * @param[in] exposedObjectName The name of exposed object
409    * @param[in] handler The callback function
410    */
411   virtual void AddJavaScriptMessageHandler(const std::string& exposedObjectName, std::function<void(const std::string&)> handler) = 0;
412
413   /**
414    * @brief Register a callback for JavaScript alert.
415    *
416    * @param[in] callback The callback function
417    */
418   virtual void RegisterJavaScriptAlertCallback(JavaScriptAlertCallback callback) = 0;
419
420   /**
421    * @brief Reply for JavaScript alert.
422    */
423   virtual void JavaScriptAlertReply() = 0;
424
425   /**
426    * @brief Register a callback for JavaScript confirm.
427    *
428    * @param[in] callback The callback function
429    */
430   virtual void RegisterJavaScriptConfirmCallback(JavaScriptConfirmCallback callback) = 0;
431
432   /**
433    * @brief Reply for JavaScript confirm.
434    */
435   virtual void JavaScriptConfirmReply(bool confirmed) = 0;
436
437   /**
438    * @brief Register a callback for JavaScript prompt.
439    *
440    * @param[in] callback The callback function
441    */
442   virtual void RegisterJavaScriptPromptCallback(JavaScriptPromptCallback callback) = 0;
443
444   /**
445    * @brief Reply for JavaScript prompt.
446    */
447   virtual void JavaScriptPromptReply(const std::string& result) = 0;
448
449   /**
450    * @brief Clears the history of Web.
451    */
452   virtual void ClearHistory() = 0;
453
454   /**
455    * @brief Clears all tiles resources of Web.
456    */
457   virtual void ClearAllTilesResources() = 0;
458
459   /**
460    * @brief Get user agent string.
461    *
462    * @return The string value of user agent
463    */
464   virtual const std::string& GetUserAgent() const = 0;
465
466   /**
467    * @brief Set user agent string.
468    *
469    * @param[in] userAgent The string value of user agent
470    */
471   virtual void SetUserAgent(const std::string& userAgent) = 0;
472
473   /**
474    * @brief Sets size of Web Page.
475    */
476   virtual void SetSize(int width, int height) = 0;
477
478   /**
479    * @brief Sets background color of web page.
480    *
481    * @param[in] color Background color
482    */
483   virtual void SetDocumentBackgroundColor(Dali::Vector4 color) = 0;
484
485   /**
486    * @brief Clears tiles when hidden.
487    *
488    * @param[in] cleared Whether tiles are cleared or not
489    */
490   virtual void ClearTilesWhenHidden(bool cleared) = 0;
491
492   /**
493    * @brief Sets multiplier of cover area of tile.
494    *
495    * @param[in] multiplier The multiplier of cover area
496    */
497   virtual void SetTileCoverAreaMultiplier(float multiplier) = 0;
498
499   /**
500    * @brief Enables cursor by client.
501    *
502    * @param[in] enabled Whether cursor is enabled or not
503    */
504   virtual void EnableCursorByClient(bool enabled) = 0;
505
506   /**
507    * @brief Gets the selected text.
508    *
509    * @return the selected text
510    */
511   virtual std::string GetSelectedText() const = 0;
512
513   /**
514    * @brief Sends Touch Events.
515    */
516   virtual bool SendTouchEvent(const TouchEvent& touch) = 0;
517
518   /**
519    * @brief Sends Key Events.
520    */
521   virtual bool SendKeyEvent(const KeyEvent& event) = 0;
522
523   /**
524    * @brief Support mouse events or not.
525    * @param[in] enabled True if enabled, false othewise.
526    */
527   virtual void EnableMouseEvents( bool enabled ) = 0;
528
529   /**
530    * @brief Support key events or not.
531    * @param[in] enabled True if enabled, false othewise.
532    */
533   virtual void EnableKeyEvents( bool enabled ) = 0;
534
535   /**
536    * @brief Sets focus.
537    * @param[in] focused True if focus is gained, false lost.
538    */
539   virtual void SetFocus(bool focused) = 0;
540
541   /**
542    * @brief Sets zoom factor of the current page.
543    * @param[in] zoomFactor a new factor to be set.
544    */
545   virtual void SetPageZoomFactor(float zoomFactor) = 0;
546
547   /**
548    * @brief Queries the current zoom factor of the page。
549    * @return The current page zoom factor.
550    */
551   virtual float GetPageZoomFactor() const = 0;
552
553   /**
554    * @brief Sets the current text zoom level。.
555    * @param[in] zoomFactor a new factor to be set.
556    */
557   virtual void SetTextZoomFactor(float zoomFactor) = 0;
558
559   /**
560    * @brief Gets the current text zoom level.
561    * @return The current text zoom factor.
562    */
563   virtual float GetTextZoomFactor() const = 0;
564
565   /**
566    * @brief Gets the current load progress of the page.
567    * @return The load progress of the page.
568    */
569   virtual float GetLoadProgressPercentage() const = 0;
570
571   /**
572    * @brief Scales the current page, centered at the given point.
573    * @param[in] scaleFactor a new factor to be scaled.
574    * @param[in] point a center coordinate.
575    */
576   virtual void SetScaleFactor(float scaleFactor, Dali::Vector2 point) = 0;
577
578   /**
579    * @brief Gets the current scale factor of the page.
580    * @return The current scale factor.
581    */
582   virtual float GetScaleFactor() const = 0;
583
584   /**
585    * @brief Request to activate/deactivate the accessibility usage set by web app.
586    * @param[in] activated Activate accessibility or not.
587    */
588   virtual void ActivateAccessibility(bool activated) = 0;
589
590   /**
591    * @brief Request to set the current page's visibility.
592    * @param[in] visible Visible or not.
593    *
594    * @return true if succeeded, false otherwise
595    */
596   virtual bool SetVisibility(bool visible) = 0;
597
598   /**
599    * @brief Searches and highlights the given string in the document.
600    * @param[in] text The text to find
601    * @param[in] options The options to find
602    * @param[in] maxMatchCount The maximum match count to find
603    *
604    * @return true if found & highlighted, false otherwise
605    */
606   virtual bool HighlightText(const std::string& text, FindOption options, uint32_t maxMatchCount) = 0;
607
608   /**
609    * @brief Add dynamic certificate path.
610    * @param[in] host host that required client authentication
611    * @param[in] certPath the file path stored certificate
612    */
613   virtual void AddDynamicCertificatePath(const std::string& host, const std::string& certPath) = 0;
614
615   /**
616    * @brief Get snapshot of the specified viewArea of page.
617    *
618    * @param[in] viewArea The rectangle of screen shot
619    * @param[in] scaleFactor The scale factor
620    *
621    * @return pixel data of screen shot
622    */
623   virtual Dali::PixelData GetScreenshot(Dali::Rect<int> viewArea, float scaleFactor) = 0;
624
625   /**
626    * @brief Request to get snapshot of the specified viewArea of page asynchronously.
627    *
628    * @param[in] viewArea The rectangle of screen shot
629    * @param[in] scaleFactor The scale factor
630    * @param[in] callback The callback for screen shot
631    *
632    * @return true if requested successfully, false otherwise
633    */
634   virtual bool GetScreenshotAsynchronously(Dali::Rect<int> viewArea, float scaleFactor, ScreenshotCapturedCallback callback) = 0;
635
636   /**
637    * @brief Asynchronously request to check if there is a video playing in the given view.
638    *
639    * @param[in] callback The callback called after checking if video is playing or not
640    *
641    * @return true if requested successfully, false otherwise
642    */
643   virtual bool CheckVideoPlayingAsynchronously(VideoPlayingCallback callback) = 0;
644
645   /**
646    * @brief Sets callback which will be called upon geolocation permission request.
647    *
648    * @param[in] callback The callback for requesting geolocation permission
649    */
650   virtual void RegisterGeolocationPermissionCallback(GeolocationPermissionCallback callback) = 0;
651
652   /**
653    * @brief Update display area.
654    * @param[in] displayArea The display area need be updated.
655    */
656   virtual void UpdateDisplayArea(Dali::Rect<int> displayArea) = 0;
657
658   /**
659    * @brief Enable video hole.
660    * @param[in] enabled True if enabled, false othewise.
661    */
662   virtual void EnableVideoHole(bool enabled) = 0;
663
664   /**
665    * @brief Sends Hover Events.
666    * @param[in] event The hover event would be sent.
667    */
668   virtual bool SendHoverEvent( const HoverEvent& event ) = 0;
669
670   /**
671    * @brief Sends Wheel Events.
672    * @param[in] event The wheel event would be sent.
673    */
674   virtual bool SendWheelEvent( const WheelEvent& event ) = 0;
675
676   /**
677    * @brief Connects to this signal to be notified when page loading is started.
678    *
679    * @return A signal object to connect with.
680    */
681   virtual WebEnginePageLoadSignalType& PageLoadStartedSignal() = 0;
682
683   /**
684    * @brief Connects to this signal to be notified when page loading is in progress.
685    *
686    * @return A signal object to connect with.
687    */
688   virtual WebEnginePageLoadSignalType& PageLoadInProgressSignal() = 0;
689
690   /**
691    * @brief Connects to this signal to be notified when page loading is finished.
692    *
693    * @return A signal object to connect with.
694    */
695   virtual WebEnginePageLoadSignalType& PageLoadFinishedSignal() = 0;
696
697   /**
698    * @brief Connects to this signal to be notified when an error occurs in page loading.
699    *
700    * @return A signal object to connect with.
701    */
702   virtual WebEnginePageLoadErrorSignalType& PageLoadErrorSignal() = 0;
703
704   /**
705    * @brief Connects to this signal to be notified when scroll edge is reached.
706    *
707    * @return A signal object to connect with.
708    */
709   virtual WebEngineScrollEdgeReachedSignalType& ScrollEdgeReachedSignal() = 0;
710
711   /**
712    * @brief Connects to this signal to be notified when url is changed.
713    *
714    * @return A signal object to connect with.
715    */
716   virtual WebEngineUrlChangedSignalType& UrlChangedSignal() = 0;
717
718   /**
719    * @brief Connects to this signal to be notified when form repost decision is requested.
720    *
721    * @return A signal object to connect with.
722    */
723   virtual WebEngineFormRepostDecisionSignalType& FormRepostDecisionSignal() = 0;
724
725   /**
726    * @brief Connects to this signal to be notified when frame is rendered.
727    *
728    * @return A signal object to connect with.
729    */
730   virtual WebEngineFrameRenderedSignalType& FrameRenderedSignal() = 0;
731 };
732
733 // specialization has to be done in the same namespace
734 template<>
735 struct EnableBitMaskOperators<WebEnginePlugin::FindOption>
736 {
737   static const bool ENABLE = true;
738 };
739
740 } // namespace Dali
741
742 #endif