Platform Browser Control API: Overview of the Browser Control API

Platform Browser Control API: Overview of the Browser Control API

The browser for S60 enables mobile phone users to browse the World Wide Web. Web pages can be implemented in Hypertext Markup Language (HTML), Extended Hypertext Markup Language (XHTML), or Wireless Markup Language (WML).

A Browser Control is a browser that you embed into an application to enable users to view Web content from within that application. The host application can control the way the Browser Control displays the Web content, dialogs, softkeys, scroll bars, and so on.

The Browser Control API enables developers to do the following:

Display XHTML, HTML, WML, CSS, or scripted content inside an application
Customize the Browser Control for your specific application. For example, you can:
Draw scroll bars
Design options menus
Display notification messages
Customize softkeys
Change the display size of a Web page

Environmental Requirements

The Browser Control API is compatible with any application that complies with S60 3 ^rd Edition.

Standards Compliance

The Browser Control API complies with the following standards:

ECMA Script Mobile Profile
HTML 4.0.1
Java Script
Wireless CSS
WML 1.3
WML Script
XHTML Mobile Profile

Browser Control Functionality

Basic Browser Control functionality includes:

Downloading and displaying Web content
Resolving links
Retrieving the following information about the downloaded content:
Display size needed to see all of the content ( ContentSize function)
WML options associated with the current page ( WMLOptionMenuItemsL function)
Value of a specified browser setting ( BrowserSettingL function)
Indication of whether or not a particular URL is in the cache ( IsUrlInCache function)
Information about the page, such as its title, URL, and content ( PageInfoLC function)
Indication of whether there is a previous or next element in the history stack ( NavigationAvailable function)
Build version of the Browser Control ( VersionInfoLC function)
Number of images in the current page ( ImageCountL function)
Type of focused element ( FocusedElementType function)
Minimum size of the Browser Control ( MinimumSize function)

The functions defined in the CBrCtlInterface class implement basic Browser Control functionality. The following table lists and describes these functions.

Function name	Description
HandleCommandL	Passes a command to the Browser Control
HandleDownloadCommandL	Passes the following commands to the Download Manager by means of the Browser Control: `EDownloadCmdPause` `EDownloadCmdResume` `EDownloadCmdCancel` `EDownloadCmdMarkAsProgressive` `EDownloadCmdMarkAsNotProgressive`
ContentSize	Returns the display size needed to see all of the selection options of the Browser Control.
SetBrowserSettingL	Updates a Browser Control setting.
LoadDataL	Displays the content of a buffer.
InitLoadDataL	Displays the content of a buffer incrementally.
LoadUrlL	Loads a URL.
LoadFileL	Loads a file.
PostUrlL	Requests the Browser Control to POST to a URL.
WMLOptionMenuItemsL	Returns the WML options associated with the current page.
AddOptionMenuItemsL	Adds options to the options menu.
ClearCache	Clears the cache.
IsUrlInCache	Queries whether or not a specified URL is in the cache.
ClearItemInCache	Clears a URL from the cache.
PageInfoLC	Returns information about the page, such as its title, URL, and content.
NavigationAvailable	Queries whether a previous or subsequent element exists in the history stack.
CertInfo	Passes server certificate information for the current page to the reader.
AddLoadEventObserverL	Registers load events.
RemoveLoadEventObserver	Unregisters load events.
ImageCountL	Returns the number of images in the current page.
FocusedElementType	Returns the type of focused element.
AddStateChangeObserverL	Registers an observer for state changes.
RemoveStateChangeObserver	Unregisters an observer for state changes.
MinimumSize	Returns the minimum size that the Browser Control can be.
OfferKeyEventL	Passes key events to the Browser Control.
SetFocus	Sets the keyboard focus for the Browser Control.
VersionInfoLC	Requests the Browser Control to return information about the Browser Control version.
SetSelfDownloadContentTypesL	Passes a list of content types to the Browser Control.
SetParamL	Updates a Browser Control parameter. Subsequent calls to update the same parameter result in replacing its value.
LoadSavedPageL	Requests the Browser Control to load a saved page.
ZoomLevels	For future use only.
FindKeyword	For future use only.
FindKeywordAgain	For future use only.

: Functions that the Browser Control provides

You can customize the Browser Control to extend its functionality by implementing additional interface classes in the host application. The following table lists the interfaces implemented by the host application.

Class	Header file	Description
MBrCtlDataLoadSupplier class	BrCtlInterface.h	Interface that provides the Browser Control with incremental content to display. Implement this interface if the host application receives content incrementally.
MBrCtlDialogsProvider class	BrCtlDialogs Provider.h	Interface that provides dialogs used by the Browser Control. Implement this interface to change the default dialogs provided by the Browser Control. To use the default dialogs provided by the Browser Control, do not specify this interface.
MBrCtlDownloadObserver class	BrCtlDownload Observer.h	Interface that passes download events from the Download Manager through the Browser Control to the host application. Examples of download events include: Pause download Resume download Cancel download This interface also provides a callback mechanism that enables the Download Manager to contact the host application. Implement this interface to enable the host application to display the content progressively as it is downloading.
MBrCtlLayoutObserver class	BrCtlLayout Observer.h	Interface used to receive scrolling events. Implement this interface when the host application draws the scroll bars around the Browser Control. Set the capability EscapabilityDisplayScrollBar if you want the Browser Control to draw the scroll bars.
MBrCtlLinkResolver class	BrCtlLinkResolver.h	Interface that provides a callback mechanism for receiving the content of an embedded link or the content of a user-initiated load request. Implement this interface if the host application must control page navigation or if the host application stores its content in a private store. Set the capability ECapabilityClientResolve EmbeddedURL or ECapabilityClientNotify URL to enable the Browser Control to callback to the host application to obtain the content.
MBrCtlLoadEventObserver class	BrCtlInterface.h	Interface used to receive load progress events. Implement this interface if the host application implements a load-progress indicator. Multiple components of the host application can implement this interface.
MBrCtlSoftkeysObserver class	BrCtlSoftKeys Observer.h	Interface that handles requests to change the softkeys. Implement this interface if the host application requires a change in the softkeys as a result of changes in the state of the Browser Control. The Browser Control may request the host application to change one or both softkeys when: the browser is downloading content, or the focused element requires special handling The host application has the option of honoring the request or ignoring it.
MBrCtlSpecialLoadObserver class	BrCtlSpecialLoad Observer.h	Interface that handles special load needs. Implement this interface if the host application requires: Handling of non-HTTP(S) load requests Handling of non-markup content Control over network connections This interface should use the Document Handler and the Download Manager for non-markup responses. The Proxy Filter establishes the network connection if this interface is not implemented.
MBrCtlStateChangeObserver class	BrCtlInterface.h	Interface used to receive state-changed events. Multiple components of the host application can implement this interface. Currently the only state-change event is generated when the Browser Control switches into and out of the Image Map view, in which only the image map is displayed.
MBrCtlWindowObserver class	BrCtlWindow Observer.h	Reserved for future use.