BrowserField Sample Code - Using the BrowserFieldListener class

by Administrator on ‎05-04-2010 09:45 AM - edited on ‎09-20-2010 05:00 PM by BlackBerry Development Advisor (10,023 Views)

This article applies to BlackBerry Device Software 5.0 and higher.

 

 

The BrowserFieldListener class can be used to capture various events raised by the browser rendering engine when web content is displayed within a BrowserField object. 

 

You can use these events to respond to certain browsing activities, or to simply monitor the level of successful usage of the web content being rendered within your application.

 

 

Some of the different types of browser events that can be captured when using this object include:

  • progress of downloading a resource
  • notification when document has finished loaded
  • notification of any errors that occured while loading the page

 

In order to use the BrowserFieldListener class in your application, follow these three steps:

 

  1. Create a BrowserField object
  2. Create a BrowserFieldListener object
  3. Call the addListener method to register the listener with the BrowserField

 

Here is an example of using the BrowserFieldListener class in your application (See Creating your first BrowserField2 application for more info):

 

 

BrowserField _bf2 = new BrowserField();

_listener = new MyBrowserFieldListener();
_bf2.addListener(_listener);

_screen = new MainScreen();
_screen.add(_bf2);
pushScreen(_screen);

_bf2.requestContent("http://devblog.blackberry.com");

 

Note: You can register multiple listeners with a BrowserField object.  When an event is raised by the browser rendering engine, all corresponding listeners will be notified.

 

 

The previous code snippet uses a custom class named MyBrowserFieldListener, that simply extends BrowserFieldListener as a superclass.  This provides a straightforward way of demonstrating how you can easily override event handlers within this class to capture and respond to specific browsing events.

 

 

As shown in the following example, messages for captured events are simply written to the debug window and the event is raised to the super class:

 

package samplecode;

import org.w3c.dom.Document;

import net.rim.device.api.browser.field.ContentReadEvent;
import net.rim.device.api.browser.field2.BrowserField;
import net.rim.device.api.browser.field2.BrowserFieldListener;
import net.rim.device.api.script.ScriptEngine;

/**
* @description Demonstration of using the BrowserFieldListener class
* added to version 5.0 of the BlackBerry Device Software
* @version 1.0
* @author Adam Stanley (astanley@rim.com), Developer Relations
* @category BlackBerry BrowserField Development: BrowserFieldListener API
* @since April 30, 2010
* @see http://www.blackberry.com/developers/docs/5.0.0api/net/rim/device/api/browser/field2/BrowserFieldListener.html
*/

/**
* This class is to be extended for the purpose of
* listening for events pertaining to a BrowserField component.
*/
public class MyBrowserFieldListener extends BrowserFieldListener
{
/**
* @param browserField - The BrowserField to which the document belongs
* @param document - The document for which this event belongs.
* Can be null or partially created depending on when the abort occurred.
*/
public void documentAborted(BrowserField browserField, Document document) throws Exception
{
if ((browserField != null) && (document != null))
{
String title = browserField.getDocumentTitle();
String url = document.getBaseURI();
browserField.getErrorHandler().displayContentError(url, "Aborted loading document '" + title + "'");
}
super.documentAborted(browserField, document);
}

/**
* @param browserField - The BrowserField to which the document belongs
* @param scriptEngine - The ScriptEngine associated with the document
* @param document - The document for which this event belongs.
* At this point the document will be a new and empty document object.
*/
public void documentCreated(BrowserField browserField, ScriptEngine scriptEngine, Document document) throws Exception
{
if ((browserField != null) && (document != null))
{
String title = browserField.getDocumentTitle();
String url = document.getBaseURI();
System.out.println("[" + this.getClass().getName() + "] Document '" + title + "' created for URL " + url);
}
super.documentCreated(browserField, scriptEngine, document);
}

/**
*
* @param browserField - The BrowserField to which the document belongs
* @param document - The document for which this event belongs.
*/
public void documentError(BrowserField browserField, Document document) throws Exception
{
if ((browserField != null) && (document != null))
{
String title = browserField.getDocumentTitle();
String url = document.getBaseURI();
browserField.getErrorHandler().displayContentError(url, "Error loading document '" + title + "'");
}
super.documentError(browserField, document);
}

/**
*
* @param browserField - The BrowserField to which the document belongs
* @param document - The document for which this event belongs.
*/
public void documentLoaded(BrowserField browserField, Document document) throws Exception
{
if ((browserField != null) && (document != null))
{
String title = browserField.getDocumentTitle();
System.out.println("[" + this.getClass().getName() + "] Document '" + title + "' loaded");
}
super.documentLoaded(browserField, document);
}

/**
*
* @param browserField - The BrowserField to which the document belongs
* @param document - The document for which this event belongs.
*/
public void documentUnloading(BrowserField browserField, Document document) throws Exception
{
if ((browserField != null) && (document != null))
{
String title = browserField.getDocumentTitle();
System.out.println("[" + this.getClass().getName() + "] Document '" + title + "' unloading");
}
super.documentUnloading(browserField, document);
}

/**
*
* @param browserField - The BrowserField to which the document belongs
* @param event - The details the download progress
*/
public void downloadProgress(BrowserField browserField, ContentReadEvent event) throws Exception
{
if ((browserField != null) && (event != null))
{
String title = browserField.getDocumentTitle();
double amtComplete = event.getItemsRead() / event.getItemsToRead();
System.out.println("[" + this.getClass().getName() + "] Document '" + title + "' loading " + String.valueOf(amtComplete) + "% complete");
}
super.downloadProgress(browserField, event);
}
}

 

For more information on the BrowserFieldListener class, see the following learning resources: