2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
20 * @brief This is the header file for the %Web class.
22 * This header file contains the declarations of the %Web class.
24 #ifndef _FWEB_CTRL_WEB_H_
25 #define _FWEB_CTRL_WEB_H_
27 #include <FBaseBuffer.h>
28 #include <FBaseResult.h>
29 #include <FBaseString.h>
30 #include <FUiContainer.h>
32 namespace Tizen { namespace Graphics
39 namespace Tizen { namespace Net { namespace Http
42 }}} // Tizen::Net::Http
44 namespace Tizen { namespace Web { namespace Controls
46 class IJavaScriptBridge;
47 class ILoadingListener;
48 class ITextSearchListener;
49 class IWebDownloadListener;
50 class IWebKeypadEventListener;
51 class IWebUiEventListener;
53 class HitElementResult;
54 class PageNavigationList;
57 }}} // Tizen::Web::Controls
59 namespace Tizen { namespace Web { namespace Controls
64 * @brief This class provides methods for embedding a browser in an application.
68 * The %Web class provides methods for embedding a browser in an application to load and render various types of %Web content. Similar to adding UI controls, the %Web content can be added to the application by adding a %Web control.
70 * For more information on the class features and %Web browser feature limitations, see <a href="../org.tizen.native.appprogramming/html/guide/web/controls_namespace.htm">Web Controls Guide</a> and <a href="../org.tizen.native.appprogramming/html/guide/web/supported_web_features.htm">Supported Features in the Web Control</a>.
72 * The following example demonstrates how to use the %Web class.
74 // Sample code for WebSample.h
79 public Tizen::Ui::Controls::Form
83 virtual ~WebSample(void) {};
89 Tizen::Web::Controls::Web *__pWeb;
92 virtual result OnInitializing(void);
95 // Sample code for WebSample.cpp
96 #include "WebSample.h"
98 using namespace Tizen::Ui;
99 using namespace Tizen::Ui::Controls;
100 using namespace Tizen::Web::Controls;
103 WebSample::OnInitializing(void)
105 result r = E_SUCCESS;
108 __pWeb->Construct(GetClientAreaBounds());
115 // Calls LoadUrl() with the URL of the Web content to display it on the Web control
117 WebSample::LoadUrl(void)
119 Tizen::Base::String url(L"http://www.tizen.org");
121 __pWeb->LoadUrl(url);
126 class _OSP_EXPORT_ Web
127 : public Tizen::Ui::Container
131 * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
138 * This destructor overrides Tizen::Base::Object::~Object().
145 * Initializes this instance of the %Web control with the specified parameters.
149 * @privilege %http://tizen.org/privilege/web.service
151 * @return An error code
152 * @param[in] rect The rectangle size of the control
153 * @exception E_SUCCESS The method is successful.
154 * @exception E_SYSTEM The method has failed.
155 * @exception E_INVALID_OPERATION The control has not been constructed as yet.
156 * @exception E_INVALID_ARG The specified @c rect is invalid.
157 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
159 result Construct(const Tizen::Graphics::Rectangle& rect);
162 * Loads the resource specified by the URL.
166 * @privilege %http://tizen.org/privilege/web.service
168 * @param[in] url The resource to load
169 * @exception E_SUCCESS The method is successful.
170 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
171 * @remarks The specific error code can be accessed using the GetLastResult() method.
173 void LoadUrl(const Tizen::Base::String& url);
176 * Loads the resource specified by the URL with the given header of HTTP request.
180 * @privilege %http://tizen.org/privilege/web.service
182 * @return An error code
183 * @param[in] url The resource to load
184 * @param[in] header The header of the HTTP request
185 * @exception E_SUCCESS The method is successful.
186 * @exception E_INVALID_ARG The url or the header is invalid.
187 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
189 result LoadUrl(const Tizen::Base::String& url, const Tizen::Net::Http::HttpHeader& header);
192 * Load the resource specified by the URL with the given header and body of HTTP request.
193 * The header must include content-type entity-header field that is needed to check mime-type of the message body.
197 * @privilege %http://tizen.org/privilege/web.service
199 * @return An error code
200 * @param[in] url The resource to load
201 * @param[in] header The header of the HTTP request
202 * @param[in] body The message body of the HTTP request
203 * @exception E_SUCCESS The method is successful.
204 * @exception E_INVALID_ARG The header is invalid.
205 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
207 result LoadUrlWithPostRequest(const Tizen::Base::String& url, const Tizen::Net::Http::HttpHeader& header, const Tizen::Base::ByteBuffer& body);
210 * Loads the content of the specified buffer.
214 * @privilege %http://tizen.org/privilege/web.service
216 * @param[in] baseUrl The uniform resource locator (URL) of the content
217 * @param[in] content The content
218 * @param[in] mime The MIME type of the content
219 * @param[in] encoding The <a href= "../org.tizen.native.appprogramming/html/guide/web/supported_web_features.htm">text encoding</a> of the content
220 * @exception E_SUCCESS The method is successful.
221 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
222 * @remarks The specific error code can be accessed using the GetLastResult() method.
224 void LoadData(const Tizen::Base::String& baseUrl, const Tizen::Base::ByteBuffer& content, const Tizen::Base::String& mime, const Tizen::Base::String& encoding = "UTF-8");
227 * Stops the current loading operation.
231 * @privilege %http://tizen.org/privilege/web.service
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
235 * @remarks The specific error code can be accessed using the GetLastResult() method.
237 void StopLoading(void);
240 * Reloads the current page.
244 * @privilege %http://tizen.org/privilege/web.service
246 * @exception E_SUCCESS The method is successful.
247 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
248 * @remarks The specific error code can be accessed using the GetLastResult() method.
253 * Checks whether the page is loading.
257 * @return @c true if a page is loading, @n
260 bool IsLoading(void) const;
263 * Checks whether the current %Web control has a back history item.
267 * @return @c true if a back history item exists, @n
270 bool CanGoBack(void) const;
273 * Checks whether the current %Web control has a forward history item.
277 * @return @c true if a forward history item exists, @n
280 bool CanGoForward(void) const;
283 * Goes to the back history of the current %Web control.
287 * @privilege %http://tizen.org/privilege/web.service
289 * @exception E_SUCCESS The method is successful.
290 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
291 * @remarks The specific error code can be accessed using the GetLastResult() method.
296 * Goes to the forward history of the current %Web control.
300 * @privilege %http://tizen.org/privilege/web.service
302 * @exception E_SUCCESS The method is successful.
303 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
304 * @remarks The specific error code can be accessed using the GetLastResult() method.
306 void GoForward(void);
309 * Gets the backward and forward navigation list of the %Web control.
313 * @return A pointer to PageNavigationList containing the history items of the %Web control
314 * @exception E_SUCCESS The method is successful.
315 * @exception E_DATA_NOT_FOUND There is no history data.
316 * @remarks The specific error code can be accessed using the GetLastResult() method.
318 Tizen::Web::Controls::PageNavigationList* GetBackForwardListN(void) const;
321 * Searches for a word on the current page. @n
322 * When called again, it searches for the next instance of the word on the page. Set @c searchForward to @c false to search for the word in the backward
327 * @return @c true if the specified @c word is found, @n
329 * @param[in] word The string to search for
330 * @param[in] searchForward Set to @c true to search for the word in the forward direction from the current position, @n
331 * else @c false to search for the word in the backward direction from the current position
333 bool SearchText(const Tizen::Base::String& word, bool searchForward = true);
336 * Sets the new values for the default setting. @n
337 * It fails to change the setting during data load.
341 * @privilege %http://tizen.org/privilege/web.service
343 * @return An error code
344 * @param[in] setting The setting to update
345 * @exception E_SUCCESS The method is successful.
346 * @exception E_FAILURE The method has failed.
347 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
349 result SetSetting(const Tizen::Web::Controls::WebSetting& setting);
352 * Gets the setting of the %Web control.
356 * @return An instance of WebSetting
358 Tizen::Web::Controls::WebSetting GetSetting(void) const;
362 * Gets the information of the element pointed by the specified coordinates.
366 * @return A HitElementResult of the pointed element
367 * @param[in] point The x and y coordinates
368 * @exception E_SUCCESS The method is successful.
369 * @exception E_INVALID_ARG The specified @c point is invalid.
370 * @exception E_OBJ_NOT_FOUND The specified element is not found.
371 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
372 * @remarks The specific error code can be accessed using the GetLastResult() method.
374 Tizen::Web::Controls::HitElementResult* GetElementByPointN(const Tizen::Graphics::Point& point) const;
377 * Evaluates the JavaScript string and returns the result.
381 * @privilege %http://tizen.org/privilege/web.service
383 * @return The result of the evaluated JavaScript, @n
384 * else an empty string if an error occurs
385 * @param[in] scriptCode The JavaScript code as string
386 * @exception E_SUCCESS The method is successful.
387 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
388 * @remarks The specific error code can be accessed using the GetLastResult() method.
390 Tizen::Base::String* EvaluateJavascriptN(const Tizen::Base::String& scriptCode);
393 * Sets the zoom-out level as a ratio.
397 * @return An error code
398 * @param[in] level The zoom-out level @n
399 * The value ranges between @c 0.3 and @c 2.0. When the page view is at its original size, the level is @c 1.0. @n If the
400 * specified level is less than @c 1.0, the page view is reduced. @n If the specified level is greater than @c 1.0, the page view is
402 * @exception E_SUCCESS The method is successful.
403 * @exception E_OUT_OF_RANGE The specified @c level is less than @c 0.3 or greater than @c 2.0.
405 result SetZoomLevel(float level);
408 * Gets the zoom level of a page as a percentage.
412 * @return The value ranges between @c 0.3 and @c 2.0
414 float GetZoomLevel(void) const;
417 * Gets the title of the current page.
421 * @return The title of the current page
423 Tizen::Base::String GetTitle(void) const;
426 * Gets the URL of the current page.
430 * @return The URL of the current page
432 Tizen::Base::String GetUrl(void) const;
435 * Checks whether the specified multipurpose internet mail extensions (MIME) type is supported by Tizen.
439 * @return @c true if the specified MIME type is supported, @n
441 * @param[in] mime The MIME type
443 bool IsMimeSupported(const Tizen::Base::String& mime) const;
446 * Sets a load event listener.
450 * @privilege %http://tizen.org/privilege/web.service
452 * @param[in] pLoadingListener The listener receives the events that occurs while loading the data
453 * @exception E_SUCCESS The method is successful.
454 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
455 * @remarks The specific error code can be accessed using the GetLastResult() method.
457 void SetLoadingListener(Tizen::Web::Controls::ILoadingListener* pLoadingListener);
460 * Sets a download event listener.
464 * @privilege %http://tizen.org/privilege/web.service
466 * @param[in] pDownLoadListener The listener to receive the data from a network incrementally
467 * @exception E_SUCCESS The method is successful.
468 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
469 * @remarks The specific error code can be accessed using the GetLastResult() method.
471 void SetDownloadListener(Tizen::Web::Controls::IWebDownloadListener* pDownLoadListener);
474 * Sets the starting point for the text selection block. @n
475 * It sets the selection block around the nearest word bound.
479 * @return An error code
480 * @param[in] startPoint The starting point for the text selection block
481 * @exception E_SUCCESS The method is successful.
482 * @exception E_INVALID_ARG There is nothing to select from the starting point specified.
484 result SetBlockSelectionPosition(const Tizen::Graphics::Point& startPoint);
487 * Releases the currently selected block.
491 * @return An error code
492 * @exception E_SUCCESS The method is successful.
495 result ReleaseBlock(void);
498 * Gets the starting point and the ending point of the selected text block. @n
499 * When this method is called without the selection block, the startPoint and endPoint have (0,0) values for the x and y coordinates.
503 * @return An error code
504 * @param[out] startPoint The starting point of the selected text block
505 * @param[out] endPoint The ending point of the selected text block
506 * @exception E_SUCCESS The method is successful.
508 result GetBlockRange(Tizen::Graphics::Point& startPoint, Tizen::Graphics::Point& endPoint) const;
511 * Gets the text of the selected text block.
515 * @return The selected text, @n
516 * else an empty string if there is no selection block
518 Tizen::Base::String GetTextFromBlock(void) const;
521 * Enables or disables the vertical and horizontal scrolls.
525 * @param[in] enable Set to @c true to enable the scrolling of the web page, @n
527 * @exception E_SUCCESS The method is successful.
529 result SetScrollEnabled(bool enable);
533 * Checks whether the web page scroll is enabled.
537 * @return @c true if the web page scroll is enabled, @n
540 bool IsScrollEnabled(void) const;
543 * Registers a user interface (UI) event listener.
547 * @param[in] pUiEventListener The listener to receive the user interface (UI) related events
549 void SetWebUiEventListener(Tizen::Web::Controls::IWebUiEventListener* pUiEventListener);
552 * Checks whether the %Web control uses private browsing.
556 * @return @c true if private browsing is enabled, @n
559 bool IsPrivateBrowsingEnabled(void) const;
562 * Sets the private browsing and returns the result.
566 * @return The result of setting the private browsing
567 * @param[in] enable Set to @c true to enable private browsing, @n
569 * @exception E_SUCCESS The method is successful.
570 * @exception E_SYSTEM The method has failed.
572 result SetPrivateBrowsingEnabled(bool enable);
575 * Clears the application's cache.
579 * @privilege %http://tizen.org/privilege/web.service
581 * @return An error code
582 * @exception E_SUCCESS The method is successful.
583 * @exception E_SYSTEM The method has failed.
584 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
586 result ClearCache(void);
589 * Clears the application's cookie.
593 * @privilege %http://tizen.org/privilege/web.service
595 * @return An error code
596 * @exception E_SUCCESS The method is successful.
597 * @exception E_SYSTEM The method has failed.
598 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
600 result ClearCookie(void);
603 * Checks whether the %Web control allows cookie. @n
604 * Returns @c true if cookie is enabled.
608 * @return @c true if cookie is allowed, @n
611 bool IsCookieEnabled(void) const;
614 * Enables or disables a cookie.
618 * @privilege %http://tizen.org/privilege/web.service
620 * @return The result of enabling or disabling cookie
621 * @param[in] enable Set to @c true if the web control allows a cookie, @n
623 * @exception E_SUCCESS The method is successful.
624 * @exception E_SYSTEM The method has failed.
625 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
627 result SetCookieEnabled(bool enable);
630 * Saves the current web page as a pdf file. The size parameter is used to set size of the pdf file using millimeter.
634 * @return An error code
635 * @param[in] filePath The path of the pdf file that is created
636 * @param[in] pSize The width and height of the pdf file in millimeter. The width and height must be greater than 0. @n
637 * If the parameter contains @c null, the method uses the default size of the web page that is shown on the screen.
638 * @exception E_SUCCESS The method is successful.
639 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
640 * - The specified path is invalid.
641 * - The specified size is invalid.
642 * @exception E_INACCESSIBLE_PATH The file path is not allowed for the application to write.
644 result SavePageAsPdf(const Tizen::Base::String& filePath, const Tizen::Graphics::Dimension* pSize = null);
647 * Adds a JavaScript bridge instance.
651 * @return An error code
652 * @param[in] jsBridge The JavaScript bridge to add
653 * @exception E_SUCCESS The method is successful.
654 * @exception E_OBJ_ALREADY_EXIST A JavaScript bridge with the same name already exists.
656 result AddJavaScriptBridge(const IJavaScriptBridge& jsBridge);
659 * Removes a JavaScript bridge instance.
663 * @return An error code
664 * @param[in] jsBridge The JavaScript bridge to remove
665 * @exception E_SUCCESS The method is successful.
667 result RemoveJavaScriptBridge(const IJavaScriptBridge& jsBridge);
670 * Registers a keypad event listener. @n
671 * The registered listener is notified when the keypad associated with @c <input> tag or with @c <textarea> tag is opened or closed.
675 * @param[in] pKeypadEventListener The event listener to set
676 * @remarks The interfaces of IWebKeypadEventListener are called only when the input style of the keypad is @c INPUT_STYLE_OVERLAY.
677 * @see WebSetting::SetInputStyle()
679 void SetWebKeypadEventListener(IWebKeypadEventListener* pKeypadEventListener);
682 * Searches for all instances of the text on the current page and then highlights them. @n
683 * The current matched block will indicate the first match.
687 * @return An error code
689 * @param[in] text The string to search for
690 * @param[in] caseSensitive Set to @c true to search for the text with case-sensitive mode, @n
691 * else @c false to search for the text in the backward direction from the current position
692 * @exception E_SUCCESS The method is successful.
693 * @exception E_INVALID_ARG The specified @c text is invalid.
694 * @remarks This method operates asynchronously.
695 * @see Tizen::Web::Controls::ITextSearchListener::OnTextFound()
697 result SearchTextAllAsync(const Tizen::Base::String& text, bool caseSensitive);
700 * Scrolls the current matched block to the next text matched by SearchTextAllAsync()
704 * @return An error code
706 * @param[in] searchForward Set to @c true to search for the text in the forward direction from the current position, @n
707 * @exception E_SUCCESS The method is successful.
708 * @exception E_OBJ_NOT_FOUND The next instance is not found.
709 * @exception E_INVALID_OPERATION The SearchTextAllAsync() method is not called.
710 * @remarks This method operates asynchronously.
711 * @see Tizen::Web::Controls::ITextSearchListener::OnTextFound()
713 result SearchNextAsync(bool searchForward = true);
716 * Sets a text search listener.
720 * @param[in] pTextSearchListener The result of the search operation made by asynchronous methods
722 void SetTextSearchListener(ITextSearchListener* pTextSearchListener);
725 * Gets the favicon image from current page.
731 * @exception E_SUCCESS The method is successful.
732 * @remarks The specific error code can be accessed using the GetLastResult() method.
735 Tizen::Graphics::Bitmap* GetFaviconN(void) const;
738 * Informs the browser engine to stop the screen operations such as updating a screen until %Web calls the Resume() method. @n
739 * It is useful when a Web control is not visible and does not need to update its screen.
746 * Informs the browser engine to resume the handling of screen operations.
754 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
756 // @param[in] item The instance of the %Web class to copy from
757 // @remarks This constructor is hidden.
759 Web(const Web& item);
762 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
764 // @param[in] item The instance of the %Web class to assign from
765 // @remarks This operator is hidden.
767 Web& operator =(const Web& item);
770 }}} // Tizen::Web::Controls
771 #endif // _FWEB_CTRL_WEB_H_