net.rim.device.api.browser.field2
Class BrowserField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.ScrollView
          net.rim.device.api.ui.Manager
              net.rim.device.api.browser.field2.BrowserField

All Implemented Interfaces:

AdjustmentListener

public final class BrowserField
extends Manager

The BrowserField class is used to embed web content within a BlackBerry Java application. This field will take up the dimensions of web content rendered within it. However, it does not provide the ability to scroll implicitly. Instead it is the BrowserField's container's responsibility to implement scrolling.

A simple example of using the BrowserField to render a web page is as follows:

 // create new instance of the BrowserField
 BrowserField browserField = new BrowserField();

 // add the browser field to a ui manager or screen
 screen.add( browserField );

 // request the content you wish to display
 // this method call is typically called once
 browserField.requestContent( "http://blackberry.com" );
 

Since:

BlackBerry API 5.0.0

Field Summary

Fields inherited from class net.rim.device.api.ui.Manager

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

BrowserField()
This contructor will create an instance of the BrowserField with the default configuration.

BrowserField(BrowserFieldConfig config)
This contructor will create an instance of the BrowserField with the default configuration overridden by any configuration explicitly provided by the config parameter.

Method Summary
void	addListener(BrowserFieldListener listener) This method will register a BrowserFieldListener to be notified for various events pertaining to this instance of a BrowserField.
void	addStandardRequestHeaders(Hashtable headers, boolean usingMDS) Add the standard headers used when making HTTP requests
boolean	back() This method will find the previous page loaded into this BrowserField instance and reload it
void	displayContent(byte[] data, String contentType, String baseUrl) This method will display the byte[] content in this BrowserField instance using the specified content type.
void	displayContent(String html, String baseUrl) This method will display the provided HTML content in this BrowserField instance.
void	displayContent(InputConnection connection, String baseUrl) This method will display the content returned from the provided InputConnection Note: this call does not affect the BrowserField's history.
Object	executeScript(String script) This method executes an arbitrary string of JavaScript code and returns a result when appropriate.
void	extendScriptEngine(String name, Scriptable scriptable) This method will extend the current ScriptEngine at the place specified.
boolean	forward() This method will find the next page in this BrowserField instance's history and reload it
BrowserFieldConfig	getConfig() This method will return the currently active BrowserFieldConfig for this BrowserField instance.
BrowserFieldConnectionManager	getConnectionManager() This method will return the currently active BrowserFieldConnectionManager for this BrowserField instance.
BrowserFieldController	getController() This method will return the currently active BrowserFieldController for this BrowserField instance.
BrowserFieldCookieManager	getCookieManager() This method will return the currently active BrowserFieldCookieManager for this BrowserField instance.
BrowserFieldDebugger	getDebugger() This method will return the currently active BrowserFieldDebugger for this BrowserField instance.
Document	getDocument() This method will return the Document object for the currently loaded page of this BrowserField instance.
String	getDocumentTitle() This method will return the title of the currently loaded page of this BrowserField instance.
String	getDocumentUrl() This method will return the URL of the currently loaded page of this BrowserField instance.
BrowserFieldErrorHandler	getErrorHandler() This method will return the currently active BrowserFieldErrorHandler for this BrowserField instance.
BrowserFieldHistory	getHistory() This method will return the currently active BrowserFieldHistory for this BrowserField instance.
BrowserFieldListener[]	getListeners() This method will return an array containing all listeners registered on this BrowserField
XYRect	getNodePosition(Node node) This method will return an XYRect object that contains the position of the node as laid out on the BrowserField.
RenderingOptions	getRenderingOptions() Deprecated.
ScriptEngine	getScriptEngine() This method will return the currently active ScriptEngine for this BrowserField instance.
Node	getTopmostNode(int x, int y) This method will return the topmost node found at the provided x,y coordinates.
float	getZoomScale() This method will return the current zoom scale (zoom level) of this BrowserField instance
boolean	hasHoverStyle(Node node) This method determines whether or not a node has a hover style associated with it
void	refresh() This method will reload the current page in this BrowserField instance's history
void	removeListener(BrowserFieldListener listener) This method will deregister the specified BrowserFieldListener so that it no longer receives events from this instance of a BrowserField
void	requestContent(String url) This method will request the page specified and display the resulting content into the BrowserField If the url specified is an HTTP URL, the resulting request will be an HTTP GET request
void	requestContent(String url, byte[] postData, Hashtable requestHeaders) This method will request the page specified and display the resulting content into the BrowserField If the url specified is an HTTP URL and the postData parameter is not null, the resulting request will be an HTTP POST request.
void	requestContent(BrowserFieldRequest request) This method will make a request as specified by the request parameter and display the resulting content into this BrowserField instance
void	setBackground(int color) This method will set the background color of this BrowserField instance.
void	setDebugger(BrowserFieldDebugger debugger) This method will register the BrowserFieldDebugger instance that will capture debugging output for this BrowserField instance.
boolean	setFocus(Node node, boolean on) This method will set focus on or off for a particular node
boolean	setHover(Node node, boolean on) This method will enable hover for a particular node (results in node's hover style to be used)
void	setZoomScale(float scale) This method will set the current zoom scale (zoom level) of this BrowserField instance If there is currently no content loaded, this method will do nothing

Methods inherited from class net.rim.device.api.ui.Manager

add, addAll, delete, deleteAll, deleteRange, getAccessibleContext, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getHorizontalScroll, getLeafFieldWithFocus, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insert, insertAll, invalidate, invalidate, invalidateFieldRange, invokeAction, isDataValid, isDirty, isDownArrowShown, isFocusable, isMuddy, isSelecting, isUpArrowShown, isValidLayout, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, layoutChild, makeMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, nextFocus, nextFocus, onFocus, onUnfocus, paint, paintChild, replace, setDirty, setFocus, setHorizontalQuantization, setPositionChild, setScrollingInertial, setVerticalQuantization, setVirtualExtent, sublayout, subpaint, touchEvent, trackwheelClick, trackwheelUnclick

Methods inherited from class net.rim.device.api.ui.ScrollView

configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onDisplay, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BrowserField

public BrowserField()

This contructor will create an instance of the BrowserField with the default configuration.

Since:

BlackBerry API 5.0.0

BrowserField

public BrowserField(BrowserFieldConfig config)

This contructor will create an instance of the BrowserField with the default configuration overridden by any configuration explicitly provided by the config parameter.

Parameters:

config - the BrowserFieldConfig object containing the configuration for this BrowserField instance

Since:

BlackBerry API 5.0.0

Method Detail

setBackground

public void setBackground(int color)

This method will set the background color of this BrowserField instance.
By default, this value is white.

Parameters:

color - the color to set the background to (in the form: 0xRRGGBB)

Since:

BlackBerry API 5.0.0

getTopmostNode

public Node getTopmostNode(int x,
                           int y)

This method will return the topmost node found at the provided x,y coordinates.

Parameters:

the - x coordinate

the - y coordinate

Since:

BlackBerry API 5.0.0

getNodePosition

public XYRect getNodePosition(Node node)

This method will return an XYRect object that contains the position of the node as laid out on the BrowserField.

Parameters:

node - the node whose position is requested

Returns:

A non-null XYRect if the node is visible, null otherwise

Since:

BlackBerry API 5.0.0

setFocus

public boolean setFocus(Node node,
                        boolean on)

This method will set focus on or off for a particular node

Parameters:

node - the node to which to change focus on or off

on - whether or not to turn focus on or off

Since:

BlackBerry API 5.0.0

setHover

public boolean setHover(Node node,
                        boolean on)

This method will enable hover for a particular node (results in node's hover style to be used)

Parameters:

node - the node to which to change hover on or off

on - whether or not to turn hover on or off

Returns:

true if this node has a hover style and false otherwise

Since:

BlackBerry API 5.0.0

hasHoverStyle

public boolean hasHoverStyle(Node node)

This method determines whether or not a node has a hover style associated with it

Parameters:

node - the node in question

Returns:

true if this node has a hover style and false otherwise

Since:

BlackBerry API 5.0.0

addListener

public void addListener(BrowserFieldListener listener)

This method will register a BrowserFieldListener to be notified for various events pertaining to this instance of a BrowserField.

Parameters:

listener - the BrowserFieldListener instance that will be notified when various events occur in this BrowserField

Since:

BlackBerry API 5.0.0

removeListener

public void removeListener(BrowserFieldListener listener)

This method will deregister the specified BrowserFieldListener so that it no longer receives events from this instance of a BrowserField

Parameters:

listener - the BrowserFieldListener instance that will no longer receive event notifications occurred in this BrowserField

Since:

BlackBerry API 6.0.0

getListeners

public BrowserFieldListener[] getListeners()

This method will return an array containing all listeners registered on this BrowserField

Since:

BlackBerry API 6.0.0

getConnectionManager

public BrowserFieldConnectionManager getConnectionManager()

This method will return the currently active BrowserFieldConnectionManager for this BrowserField instance. The BrowserFieldManager is used to execute BrowserFieldRequests on behalf of the BrowserField.

Returns:

the currently active BrowserFieldConnectionManager for this BrowserField instance

Since:

BlackBerry API 5.0.0

getConfig

public BrowserFieldConfig getConfig()

This method will return the currently active BrowserFieldConfig for this BrowserField instance.

Returns:

the currently active BrowserFieldConfig for this BrowserField instance

Since:

BlackBerry API 5.0.0

getCookieManager

public BrowserFieldCookieManager getCookieManager()

This method will return the currently active BrowserFieldCookieManager for this BrowserField instance.

Since:

BlackBerry API 5.0.0

getController

public BrowserFieldController getController()

This method will return the currently active BrowserFieldController for this BrowserField instance.

Since:

BlackBerry API 5.0.0

getErrorHandler

public BrowserFieldErrorHandler getErrorHandler()

This method will return the currently active BrowserFieldErrorHandler for this BrowserField instance.

Since:

BlackBerry API 5.0.0

setDebugger

public void setDebugger(BrowserFieldDebugger debugger)

This method will register the BrowserFieldDebugger instance that will capture debugging output for this BrowserField instance.

Parameters:

debugger - the BrowserFieldDebugger object that will capture debugging output output for this BrowserField instance

Since:

BlackBerry API 5.0.0

getDebugger

public BrowserFieldDebugger getDebugger()

This method will return the currently active BrowserFieldDebugger for this BrowserField instance.

Since:

BlackBerry API 5.0.0

getHistory

public BrowserFieldHistory getHistory()

This method will return the currently active BrowserFieldHistory for this BrowserField instance.

Since:

BlackBerry API 5.0.0

getScriptEngine

public ScriptEngine getScriptEngine()

This method will return the currently active ScriptEngine for this BrowserField instance.

Since:

BlackBerry API 5.0.0

executeScript

public Object executeScript(String script)

This method executes an arbitrary string of JavaScript code and returns a result when appropriate.

Parameters:

script - A string representation of arbitrary JavaScript code

Returns:

The result of the executed JavaScript code

Throws:

IllegalStateException - this exception is thrown if this method invoked before this BrowserField's document has been created. This event is communicated via the BrowserFieldListener.documentCreated() method.

Since:

BlackBerry API 5.0.0

extendScriptEngine

public void extendScriptEngine(String name,
                               Scriptable scriptable)
                        throws Exception

This method will extend the current ScriptEngine at the place specified. The Scriptable provided to extend the ScriptEngine can correspond to an object (Scriptable), a function (ScriptableFunction) or any set of objects and functions. Extensions added will then be available to be used by JavaScript loaded into this BrowserField instance. A simple example is as follows: // Java code browserField.extendScriptEngine("interesting.test", new ScriptableFunction() { public Object invoke(Object thiz, Object[] args) { // do something interesting } }); // JavaScript code interesting.test(); // now something interesting happens!

Parameters:

name - The name by which the added Scriptable will be accessible by JavaScript

scriptable - The implementation of the ScriptEngine extension itself.

Throws:

Exception

Since:

BlackBerry API 5.0.0

getDocument

public Document getDocument()

This method will return the Document object for the currently loaded page of this BrowserField instance.

Returns:

A Document object if a page is currently loaded, null otherwise

Since:

BlackBerry API 5.0.0

getDocumentUrl

public String getDocumentUrl()

This method will return the URL of the currently loaded page of this BrowserField instance.

Returns:

The URL of the currently loaded page. If no page is loaded, this method will return null

Since:

BlackBerry API 5.0.0

getDocumentTitle

public String getDocumentTitle()

This method will return the title of the currently loaded page of this BrowserField instance.

Returns:

The title of the currently loaded page. If no page is loaded, this method will return null

Since:

BlackBerry API 5.0.0

requestContent

public void requestContent(String url)

This method will request the page specified and display the resulting content into the BrowserField If the url specified is an HTTP URL, the resulting request will be an HTTP GET request

Parameters:

url - The url for the page content to display

Since:

BlackBerry API 5.0.0

requestContent

public void requestContent(String url,
                           byte[] postData,
                           Hashtable requestHeaders)

This method will request the page specified and display the resulting content into the BrowserField If the url specified is an HTTP URL and the postData parameter is not null, the resulting request will be an HTTP POST request. If the postData parameter is null, then an HTTP GET request will be made.

Parameters:

url - The url for the page content to display

postData - The data to be used for a HTTP POST request. In the case of non-HTTP requests, this parameter is ignored.

requestHeaders - A set of name-value pairs to be inserted into an HTTP request. In the case of non-HTTP requests, this parameter is ignored.

Since:

BlackBerry API 5.0.0

requestContent

public void requestContent(BrowserFieldRequest request)

This method will make a request as specified by the request parameter and display the resulting content into this BrowserField instance

Parameters:

request - An object containing specifics about the request to be made to retrieve the page content

Since:

BlackBerry API 5.0.0

getRenderingOptions

public RenderingOptions getRenderingOptions()

Deprecated.

This method returns the RenderingOptions used by this BrowserField instance. RenderingOptions are exposed for use only when BrowserFieldConfig does not contain the necessary config option. When using RenderingOptions to configure how content is rendered, keep in mind that these options may override what has been configured via BrowserFieldConfig. Note that not all options available on RenderingOptions will work.

Since:

BlackBerry API 5.0.0

displayContent

public void displayContent(String html,
                           String baseUrl)

This method will display the provided HTML content in this BrowserField instance. Note: this call does not affect the BrowserField's history.

Parameters:

html - The HTML content to be displayed

baseUrl - The URL identifying this content. This will be used to resolve relative urls.

Since:

BlackBerry API 5.0.0

displayContent

public void displayContent(byte[] data,
                           String contentType,
                           String baseUrl)

This method will display the byte[] content in this BrowserField instance using the specified content type. Note: this call does not affect the BrowserField's history.

Parameters:

data - The content to be displayed

contentType - The content type of the byte data provided

baseUrl - The URL identifying this content. This will be used to resolve relative urls.

Since:

BlackBerry API 5.0.0

displayContent

public void displayContent(InputConnection connection,
                           String baseUrl)

This method will display the content returned from the provided InputConnection Note: this call does not affect the BrowserField's history.

Parameters:

connection - This connection should have an input stream that will be used to provide content to load into this BrowserField instance.

baseUrl - The URL identifying this content. This will be used to resolve relative urls.

Since:

BlackBerry API 5.0.0

setZoomScale

public void setZoomScale(float scale)

This method will set the current zoom scale (zoom level) of this BrowserField instance If there is currently no content loaded, this method will do nothing

Parameters:

scale - The new zoom scale for this BrowserField instance

Since:

BlackBerry API 5.0.0

getZoomScale

public float getZoomScale()

This method will return the current zoom scale (zoom level) of this BrowserField instance

Returns:

The current zoom scale or 0 if no content is currently loaded

Since:

BlackBerry API 5.0.0

back

public boolean back()

This method will find the previous page loaded into this BrowserField instance and reload it

Returns:

true if a previous page exists, false otherwise

Since:

BlackBerry API 5.0.0

forward

public boolean forward()

This method will find the next page in this BrowserField instance's history and reload it

Returns:

true if a next page exists, false otherwise

Since:

BlackBerry API 5.0.0

refresh

public void refresh()

This method will reload the current page in this BrowserField instance's history

Since:

BlackBerry API 5.0.0

addStandardRequestHeaders

public void addStandardRequestHeaders(Hashtable headers,
                                      boolean usingMDS)

Add the standard headers used when making HTTP requests

Parameters:

requestHeaders - The current set of request headers to add to

usingMDS - Indicating whether or not an MDS transport service is being used to make the HTTP request

Since:

BlackBerry API 5.0.0