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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.ScrollView
          extended by net.rim.device.api.ui.Manager
              extended by 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 constructor will create an instance of the BrowserField with the default configuration.
BrowserField(BrowserFieldConfig config)
          This constructor 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()
          Deprecated. Debugger is deprecated in 6.0
 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)
          Deprecated. Debugger is deprecated in 6.0
 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, cursorClick, cursorMovement, cursorUnclick, 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, shouldCursorScroll, sublayout, subpaint, touchEvent, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onExposed, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidateAll, isEditable, isEnabled, isFocus, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onDisplay, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocus, setFocusListener, setFont, 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 constructor will create an instance of the BrowserField with the default configuration.

Since:
BlackBerry API 5.0.0

BrowserField

public BrowserField(BrowserFieldConfig config)
This constructor 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)
Deprecated. Debugger is deprecated in 6.0

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()
Deprecated. Debugger is deprecated in 6.0

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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal