Browser Control API: API Description

The Web 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).

The Browser Control API enables developers to do the following:

Logical and Technical Classification

The Browser Control API is classified as a Library API. It provides classes and functions that are used in the context of the client's thread. The classes and functions can be used independently of each other.

The Browser Control API is a Method Call API. The interface uses only local objects.

Audience

This API is intended for developers who wish to use a browser control plug-in in their applications. The reader should be familiar with the C++ programming language and the Symbian operation system.

Standards Compliance

The Browser Control API complies with the following standards:

Browser Control Functionality

Basic Browser Control functionality includes:

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

Table 1: Functions that the Browser Control Provides
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.
GetBitmapDataAssociates a favorites icon (favicon) with a specified URL or with a thumbnail of the current page. Favicons can be displayed in the Bookmarks, Adaptive Bookmarks, and News & Blogs lists, and in the Saved Pages view.

Returns the bitmap of the current page or the favicon of a specified URL.

ZoomLevels Returns the array of possible zoom levels.
FindKeyword Finds a specified string in the current page.
FindKeywordAgain Searches for the next location of the keyword on the page.

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.

Table 2: Interfaces implemented by the host application
Class Header file Description
MBrCtlDataLoadSupplier BrCtlInterface.h Interface that provides the Browser Control with incremental content to display.

Implement this interface if the host application receives content incrementally.

MBrCtlDialogsProvider BrCtlDialogsProvider.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 BrCtlDownloadObserver.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 BrCtlLayoutObserver.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 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 ECapabilityClientNotifyURL to enable the Browser Control to callback to the host application to obtain the content.

MBrCtlLoadEventObserver 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 BrCtlSoftKeysObserver.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 BrCtlSpecialLoadObserver.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 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 BrCtlWindow Observer.h

Handles window events such as opening a URL in a new window, closing a window, and finding a window of a specified name.

Use cases

This section describes the types of things you can do with the Browser Control API. The main use cases are as follows:

API Class Structure

Figure 1 shows the class diagram of the new classes created for the Browser Control feature.

Figure 1: Browser Control Class Diagram

The following table contains descriptions of the structural classes shown in Figure 1.

Table 3: Browser Control Structural Classes
Class NameHeader FileClass Description
CCoeControl

CoeControl.h

Standard Symbian class that is the parent class for all Browser Control API classes.

For more information about this class, see the Symbian Developer Library at the following URL: http://www.symbian.com/developer/techlib/v70sdocs/doc_source/reference/cpp/UIControlFramework/CCoeControlClass.html#%3a%3aCCoeControl

CBrCtlInterface

BrCtlInterface.h

Base class of the Browser Control API. All clients of the Browser Control must use this class.

Provides functions that:

  • Create the Browser Control
  • Pass commands to the Browser Control
  • Pass download commands from the host application to the Browser Control and then to the Download Manager
  • Return the display size required to see all of the content
  • Update Browser Control settings
  • Get settings from the Browser Control
  • Pass a list of content types that should not use the Download Manager to the Browser Control
  • Query the Browser Control as to whether a particular URL is in the cache
  • Query the Browser Control as to whether forward or backward navigation is available
  • Return the number of images in the current page
  • Return the type of focused element
  • Register or un-register an observer for state changes
  • Request the Browser Control to:
    • Display the content of a buffer
    • Display content incrementally
    • Load a URL
    • Load the contents of a saved page buffer
    • Enter the UID of a saved page into the History list
    • Load and display a file from the file system
    • POST to a URL
    • Return the WML options associated with the current page
    • Add its own options to the top of the option menu
    • Clear the cache
    • Clear a particular URL from the cache
    • Return the title, URL, or content of the current page
    • Pass server certificate information for the current page to the reader
    • Register for load events
    • Un-register for load events
    • Return information about the Browser Control version
  • Update the value of a Browser Control parameter
  • Return the minimum size of the Browser Control
  • Pass key events to the Browser Control
  • Set keyboard focus for the Browser Control

CBrCtl

BrCtl.h

Implementation class for the Browser Control
MBrCtlDialogsProvider

BrCtlDialogsProvider.h

Provides functions, implemented by the Browser Control, that:
  • Notify the user of an error encountered during a download, such as insufficient memory, unrecognized URL, and DNS not found
  • Notify the user of an error from the HTTP server during a download, such as a file not found or a redirect error
  • Navigate through the file system and select a file; analogous to the Browsecommand in Windows
  • Display selection dialog, such as check boxes, radio buttons, or single selection with an OK response
  • Authenticate a user
  • Display a message to the user
  • Display a message requesting confirmation of a user action
  • Display dialog requesting the user to input information
  • Display information about a Netscape plug-in object and request information before downloading the object
  • Display the images contained in the current page
  • Cancel the dialog displayed due to Browser exit
  • Display a dialog box for searching on the current page
MBrCtlDownloadObserver

BrCtlDownloadObserver.h

Handles download events. Provides functions that:
  • Inform the host application that one of the following download events is in progress:
    • EventStarted
    • EventCompleted
    • EventProgress
    • EventCanceled
    • EventError
    • EventPaused
    • EventResumed
    • EventPausable
  • Inform the host application that the Download Manager has begun a new download
  • Tells the host application to resume an incomplete download.
MBrCtlSpecialLoadObserver

BrCtlSpecialLoadObserver.h

Handles special load events, such as:
  • Network connection
  • Non-HTTP(S) load requests
  • Non-HTML responses

Provides functions that:

  • Request a new network connection
  • Request the host application to call the Scheme Dispatcher to handle non-HTTP(S) request
  • Request the host application to handle downloads. The host application should call the Download Manager to handle non-HTML content.

MBrCtlSoftkeysObserver

BrCtlSoftkeysObserver.h

Handles requests to change the softkeys. Provides functions that request the host application to change a softkey. The host application may or may not change the softkey.
MBrCtlLinkResolver

BrCtlLinkResolver.h

Provides the content of an embedded link or the content of a load request that was initiated by the user. This class is used when the host application stores markup text or other information in a private store. For example, this class could be used for email applications.

Provides functions that:

  • Resolve embedded links
  • Load new content identified by a link
  • Cancel all outstanding link resolution operations

MBrCtlLinkContent

BrCtlLinkResolver.h

Interface that returns the response from the MBrCtlLinkResolver interface and loads the resolved content.

Provides functions that are called when:

  • Content is resolved
  • An error occurs while resolving the content

MBrCtlLayoutObserver

BrCtlLayoutObserver.h

Receives scrolling events when the host application draws the scrollbar. Provides functions that:
  • Update the position of the vertical scrollbar
  • Update the position of the horizontal scrollbar
  • Determine whether the page is to be read right-to-left or left-to-right
  • Update the title of the page in the History view.
MBrCtlLoadEventObserver

BrCtlInterface.h

Receives load progress events. The host application can implement this interface.

Provides functions that notify the Browser Control of a load event.

This class is located in the BrowserEngine.lib library.

MBrCtlDataLoadSupplier

BrCtlInterface.h

Callback interface that enables the Browser Control to display content incrementally. It does this by providing a means for the Browser Control to cancel the load operation if an error occurs.

For example, if the Browser Control runs out of memory during the load operation, it can cancel that operation by means of this interface.

This class is stored in the BrowserEngine.lib library.

MBrCtlDataLoadConsumer

BrCtlInterface.h

Callback interface that enables the Browser Control to receive content incrementally. This class is stored in the BrowserEngine.lib library.

Provides functions that:

  • Pass the next data chunk to the Browser Control for display
  • Inform the Browser Control that the data load is complete
  • Inform the Browser Control if an error occurs

MBrCtlStateChangeObserver

BrCtlInterface.h

Receives state-changed events. At the present time, there is only one state-changed event. This event is generated when the Browser switches to and from the Image Map view. In Image Map view, only an image map is displayed, which enables the user to navigate.

Provides functions that notify the Browser Control of a state-changed event.

This class is located in the BrowserEngine.lib library.

MBrCtlWindowObserver

BrCtlWindowObserver.h

Handles window events such as requesting the host application to open a URL in a new window, closing a window, and finding a window of a specified name.

The following table contains the auxiliary class that contains the enumerations for the Browser Control.

Table 4: Browser Control Auxiliary Class
ClassHeader FileDescription
TBrCtlDefs

TBrCtlDefs.h

Helper class that provides a namespace for the enumerations used by the Browser Control.
Copyright © Nokia Corporation 2001-2008
Back to top