S60 3rd Edition SDK for Symbian OS
Example Applications Guide |
Browser Control Sample Application
1. About the Browser Control Sample Application Example
2. Prerequisites
3. Design and Implementation
4. Class Hierarchy
This example shows how easy it is to create a browser control that will enable you to display web related content. In addition, this sample application demonstrates how to customize the browser control to fit the unique needs of your host application, by showing you how to customize soft keys, dialogs, scroll bars, etc.
Symbian OS key concepts
The Browser Control Sample Application was designed to accompany the Browser Control API Developers Guide. Each of the menu options in the Sample App Menu 1 and 2 demonstrate various functional use cases that could be useful when developing your own application. For a more detailed explaination of these use cases please refer to the API Guide.
When you start the Browser Control Sample Application you will notice the Options softkey.
Opening the Options menu displays 3 menu choices:
1. Tools
2. Sample App Menu 1
3. Sample App Menu 2
4. Exit
Tools menu options:
1. Restore settings
- Restores the settings for small screen, security warnings, loading images, and enabling ecma script
2. Reload
3. Back
- Loads the previous page in the history stack
4. Forward
- Loads the next page in the history stack
Sample App Menu 1 options:
1. Basic BrCtl
2. BrCtl Observers
3. Load Content using File Handle
4. Load Content using Buffer
5. Incremental Loading
6. Special Load Requests
7. Customized Dialogs
8. Customized Softkeys
9. Embedded Links
10. Customized Scrollbars
Sample App Menu 2 options:
1. Handle State Changed
2. Change Size Extents
3. Page Info
4. Content Size and Image Count
Basic Browser Control functionality includes:
- Downloading and displaying Web content
- 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)
To create a basic Browser Control within your application to display Web-related content, call the following function of the CBrCtlInterface class:
- CreateBrowserControlL() which creates an instance of a basic Browser Control.
To call this function, supply the following data:
- Parent window of the Browser Control which is a pointer to the parent of the Browser Control window.
- Bounding rectangle of the Browser Control which is the size and location of the Browser Control window.
- Capabilities desired for the Browser Control, for example, displaying scroll bars, allowing network access for HTTP requests.
The Basic BrCtl menu option in the sample application creates an instance of a basic Browser Control. In this sample, the capabilities are set so that the Browser Control can:
- Make external HTTP requests (ECapabilityLoadHttpFw)
- Handle scroll bars (ECapabilityDisplayBar)
This relieves the host application of these responsibilities.
An observer is an interface, implemented by the host application, which listens for Browser Control events and performs customized actions based on those events. Table 6 lists and describes the observer interfaces.
- Dialogs Provider Provides the dialogs used by the Browser Control.
Implement this interface if you wish to customize the dialogs.
- Download Observer Handles download events received from the Download Manager. It provides a callback mechanism that enables the Download Manager to inform the host application about new downloads and downloads to resume.
Implement this interface if you wish to display the content progressively as it is downloading.
- Layout Observer Receives scrolling events and updates the scroll bar.
Implement this interface if you wish to customize the scroll bars.
- Link Resolver 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.
- Load Event Observer Receives load progress events and updates the progress bar every time the Browser Control receives a data chunk.
Implement this interface if the host application implements a progress bar.
- Softkey Observer Listens for events and changes the softkeys based on those events.Handles requests from the Browser Control for the host application to change one or both softkeys.
Implement this interface if changes in the state of the Browser Control require the host application to change the softkeys.
- Special Load Observer Handles special load requests.
Implement this interface if the host application requires:
- Control over network connections
- State Change Observer Receives state-changed events.
Implement this interface if the Browser Control switches to and from the Image Map view.
- Window Observer is reserved for future use.
To create a Browser Control with observer interfaces, follow these steps:
1. Select the observer class you wish to add.
2. Implement the functions defined for the observer class you selected in step1.
3. Call the CreateBrowserControlL() function of the CBrCtlInterface class with the pointers to the newly created interface class(es).
Note: The LoadEventObserver class can be added and removed dynamically. The other observers must be created and passed in to the CreateBrowserControlL function.
The BrCtl Observers menu option in the sample application creates an instance of a Browser Control with observer interfaces.
A host application can load content by calling a number of different load methods on the Browser Control. In the Load Content using File Handle menu option, we call LoadFileL() and pass it a RFile handle to an already open file. An RFile is a Symbian object that contains a handle to a resource that is maintained by the file server.
A host application can load content by calling a number of different load methods on the Browser Control. In the Load Content using Buffer menu option, we call LoadDataL() and pass it a data buffer.
The host application can pass content to the Browser Control in small chunks, if desired. The Browser Control displays this content incrementally. To pass content from the host application to the Browser Control incrementally, follow these steps:
1. Inherit from the MBrCtlDataLoadSupplier class and implement the CancelLoad() function to stop the load operation.
2. Call the InitLoadDataL() function of the CBrCtlInterface class to request the Browser Control to display content incrementally. *
3. Call the HandleNextDataChunk() function of the MBrCtlDataLoadConsumer class to pass the data chunks to the Browser Control.
4. Call the HandleLoadComplete() function when the data chunk has finished loading.
5. If an error occurs, call the HandleError() function.
In the Incremental Loading menu option, we demonstrate how to pass content to the Browser Control incrementally.
Special load requests consist of the following:
- Non-HTTP(S) load requests
- Control over network connections
In these cases, the host application can handle the requests instead of the Browser Control.
HandleDownloadL() requests the host application to handle a download. The host application should call the Download Manager to handle non-HTML content. Only GET requests are supported because the Browser Control must cancel the transaction before the Download Manager can take over. In the case of a POST request, the Browser Control downloads the content and passes it to the host application. The host application should look for the parameter EParamLocalFileName to determine whether or not the Browser Control downloaded the content.
HandleRequestL() checks the scheme of a URL to determine whether or not the Browser Control supports it. If the Browser Control does not support it, then the host application should pass the content to an application that does support that scheme.
NetworkConnectionNeededL() requests a new network connection. The Browser Control calls this function for each HTTP(S) load request. It is up to the host application to ensure that the network connection is available.
In the Special Load Requests menu option we demonstrate how to handle a request to load non-HTML content.
Note: Because there is no Scheme Handler API shipped with the SDK, you as a developer are responsible for implementing your own scheme handling mechanism. By this we mean, inspecting the file type, and then trying to locate the appropriate application to handle this file. There are comments in the code as to where this implementation should take place. Without a scheme handler, this code is unable to locate the appropriate application that would handle this unknown scheme, so the unknown scheme is ignored.
The Browser Control provides dialogs to communicate with the user of the host application. You can customize these dialogs by implementing the MBrCtlDialogsProvider interface to:
- Remove one or more dialogs
- Change the format or content of dialogs
- Selectively implement some of the default dialogs
The Customized Dialogs menu option demonstrates how to customize the alert dialog.
The host application can change the labels of the softkeys as a response to softkey events received from the Browser Control. The Browser Control transmits one or more softkey events under the following conditions:
- A plug-in control is activated or deactivated
- An input box is activated or deactivated
- The browser view changes to and from the Image Map view
To specify the softkeys, follow these steps:
1. Implement the UpdateSoftkeyL() function to change the softkeys.
2. Use the event to query the FocusedElementType() function to learn what the focused element is. All events are issued the EChangeReasonIdle reason code.
3. Change the softkeys based on the focused element.
The Customized Softkeys menu option demonstrates how to customize the softkeys.
If the content of an embedded link is to be loaded from the private store of a host application, such as an e-mail application, then the developer should implement the MBrCtlLinkResolver class. This interface provides a callback mechanism to the host application to transmit the content of an embedded link or the content of a user-initiated load request to the Browser Control. To enable this callback mechanism, the host application must set the ECapabilityClientResolveEmbeddedURL capability or the ECapabilityClientNotifyURL capability. If the host application is unable to resolve the embedded link, then the Browser Control tries to handle the request through the HTTP framework. The following functions of the MBrCtlLinkResolver interface provide the content of an embedded link.
- CancelAll() cancels all outstanding link resolution operations.
- ResolveEmbeddedLinkL() retrieves the content of an embedded link. For example, the Browser Control calls this function to display images embedded within an e-mail message.
The Browser Control implements this interface after a link is resolved or an error occurs. Table 16 lists the functions called by the host application after a link is resolved or after an error occurs in resolving the link.
- HandleResolveComplete() called by the host application when the content of a link has finished loading.
- HandleResolveError() Called by the host application if an error occurred while downloading the content of a link.
The Embedded Links menu option demonstrates how to resolve an embedded link.
To customize a scroll bar based upon one or more layout (scrolling) events, follow these steps:
1. When you create the Browser Control, do not specify the EcapabilityDisplayScrollBar flag.
2. Implement the MBrCtlLayoutObserver interface.
This enables the host application to display and update the scroll bars. If you wish to have no scroll bars at all, follow step 1 but do not implement step 2. The following functions of the MBrCtlLayoutObserver interface receive scrolling events when the host application draws the scrollbar.
- NotifyLayoutChange() determines whether the page is to be read from right-to-left or from left-to-right.
- UpdateBrowserHScrollBarL() updates the position of the horizontal scrollbar.
- UpdateBrowserVScrollBarL() updates the position of the vertical scrollbar.
- UpdateTitleL() updates the page title in the History view.
The Customized Scrollbars menu option demonstrates how you would go about customizing a scroll bar.
Note: This sample doesn't acutally customize the scrollbars, that is left as an excercise for the reader, so to speak. What we do in this example is to show you how to set up the observer interface in order to receive these layout events. You will notice that we resize the browser control screen and write a text string below the browser control. This is to show that the methods on this observer are getting called. There are comments in the code which tell you that this is where you would implement your own scrolling implementation, if that is what you wish to do with the layout events.
A change-of-state-event indicates that the state of the browser has changed. For example, the browser may switch to or from the Image Map view. To receive change-of-state events, inherit from the MBrCtlStateChangeObserver interface and implement the StateChanged function. The following function indicates that the browser has changed its state:
- StateChanged() called by the browser when its state has changed.
NOTE: The only state change currently supported is the change to and from the Image Map view.
The Handle State Changed menu option demonstrates how to receive an event that indicates that the state of the browser has changed.
The Change Size Extents menu options, allows you to change the size of the browser control.
The Page Info menu option, uses the PageInfoLC() method on the Browser Control to request the Browser Control to return information about the page, such as the page title, URL, or content.
The Content Size and Image Count menu option uses the ContentSize() and ImageCountL() methods on the Browser Control to return this information to the host application.
NetworkServices
This sample application handles multiple screen modes and the screen size can change dynamically.
The right softkey with the title "Back" is not integrated into the application and will not take you back to the previous page in the history list. If you want to go to the previous page in the history list please go to Options->Tools->Back
EMULATOR SDK
------------------
cd to
bldmake bldfiles
abld build winscw udeb
start the emulator
HARDWARE (ARMV5)
------------------
cd to
bldmake bldfiles
abld build armv5 urel
makesis BrCtlSampleApp_armv5.pkg
HARDWARE (GCCE)
------------------
cd to
bldmake bldfiles
abld build gcce urel
makesis BrCtlSampleApp_gcce.pkg
HARDWARE (ARMV5_ABIV2)
------------------
cd to
bldmake bldfiles
abld build armv5_abiv2 urel
makesis BrCtlSampleApp_armv5_abiv2.pkg
Copy the sis file to the phone (memory card, bluetooth, etc) Run the sis file to install the application
This inheritance list is sorted roughly, but not completely, alphabetically:
|
© Nokia 2006 |
|