com.nokia.mid.ui
Class BrowserItem

java.lang.Object
  com.nokia.mid.ui.CanvasItem
      com.nokia.mid.ui.BrowserItem

public class BrowserItem
extends CanvasItem

BrowserItem renders an html page defined by a URL. It can be placed on a Canvas or on a CustomItem To invoke a URL and upload a file or download an image to the file system the appropriate permissions are needed like: javax.microedition.io.Connector.http, javax.microedition.io.Connector.https javax.microedition.io.Connector.file.read or javax.microedition.io.Connector.file.write When an application goes to background and releasing its UI it must also release the BrowserItem by calling the destroy function.

Field Summary

Fields inherited from class com.nokia.mid.ui.CanvasItem

SCALE_AVERAGE, SCALE_NEAREST, SCALE_NOT_ALLOWED

Method Summary

void	confirmDialogDone(boolean yesno) This function should be called when the user has selected yes or no from a confirm dialog
void	destroy() Destroys the BrowserItem, releases its resources after the call this item cannot be used any more, but a new one can be aquired
void	fileSelectDialogDone(java.lang.String file) This function should be called when the user has finished file selection
static BrowserItem	getBrowserItem() Returns the BrowserItem the application can use (currently only 1 per application) The system supports only 2 BrowserItems in total shared by the applications
int	getHeight() Gets the height of this BrowserItem in pixels.
java.lang.Object	getParent() Gets the current parent of this CanvasItem
int	getPositionX() Gets the rendering position of this BrowserItem.
int	getPositionY() Sets the rendering position of this BrowserItem.
java.lang.String	getTitle() Gets the title of the currently loaded page
java.lang.String	getUrl() Gets the url of the currently loaded page
int	getWidth() Gets the width of this BrowserItem in pixels.
int	getZPosition() Returns the Z-position, or the elevation, of the item.
void	invokeUrl(java.lang.String url) Invokes a url
boolean	isVisible() Returns the visibility of the browser
void	loadHistoryByUrl(java.lang.String url) Makes the browser to load a url from the history
void	noteDialogDone() This function should be called when the note dialog has been closed
void	reload() Reloads the current page
int	saveSelectedImage(java.lang.String filePath) Saves the selected image to the file system
void	scale(int width, int height) Overrides the CanvasItem's scale method as on BrowserItem it is not supported
void	scale(int x, int y, int width, int height) Overrides the CanvasItem's scale method as on BrowserItem it is not supported
void	selectListDialogDone(int[] ids) This function should be called when the user has finished list selection
void	setBrowserListener(BrowserListener listener) Sets the BrowserItem's listener to get notifications from the BrowserItem
void	setParent(java.lang.Object theParent) Set the parent object of this BrowserItem.
void	setPosition(int x, int y) Sets the rendering position of this BrowserItem.
void	setScalingMode(int scaleMode, boolean aspectRatioPreserved, int anchor) Overrides the CanvasItem's method as on BrowserItem it is not supported
void	setSize(int width, int height) Sets the size of this BrowserItem in pixels.
void	setSize(int x, int y, int width, int height) Sets the size of this BrowserItem in pixels and resets the current anchor position.
void	setVisible(boolean visible) Sets the visibility value of BrowserItem.
void	setZPosition(int z) Sets the Z-position, or the elevation, of the item.
void	stop() Stops loading

Methods inherited from class com.nokia.mid.ui.CanvasItem

isValidImageAnchor

Methods inherited from class java.lang.Object

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

Method Detail

getBrowserItem

public static BrowserItem getBrowserItem()
                                  throws java.lang.IllegalStateException

Returns the BrowserItem the application can use (currently only 1 per application) The system supports only 2 BrowserItems in total shared by the applications

Returns:

the BrowserItem

Throws:

java.lang.IllegalStateException - if there is no free BrowserItem available in the system to return

setParent

public void setParent(java.lang.Object theParent)

Set the parent object of this BrowserItem.

Typically the parent object would be Canvas or CustomItem. Setting the parameter to null removes the association to the parent. If setParent(null) is called for a BrowserItem yet not having any parent or setParent(parent) is called with the same parent, the call is silently ignored.

Overrides:

setParent in class CanvasItem

Parameters:

theParent - the parent object

Throws:

java.lang.IllegalArgumentException - if parent is not a valid object with which a BrowserItem can be associated, or if BrowserItem is already set to another another parent

java.lang.IllegalStateException - if the item is already destroyed

setSize

public void setSize(int width,
                    int height)

Sets the size of this BrowserItem in pixels.

Overrides:

setSize in class CanvasItem

Parameters:

width - width in pixels

height - height in pixels

Throws:

java.lang.IllegalArgumentException - if the width or height is less than one pixel

java.lang.IllegalStateException - if the item is already destroyed

See Also:

for more details

setSize

public void setSize(int x,
                    int y,
                    int width,
                    int height)

Sets the size of this BrowserItem in pixels and resets the current anchor position.

This call has the same effect as calling consecutively the following two methods setSize(int, int) and setPosition(int, int).

Overrides:

setSize in class CanvasItem

Parameters:

x - the x coordinate of the anchor point

y - the y coordinate of the anchor point

width - the new width in pixels

height - the new height in pixels

Throws:

java.lang.IllegalArgumentException - if the width or height is less than one pixel

java.lang.IllegalStateException - if the item is already destroyed

See Also:

setPosition(int, int), setSize(int, int)

getHeight

public int getHeight()

Gets the height of this BrowserItem in pixels.

Overrides:

getHeight in class CanvasItem

Returns:

height in pixels

Throws:

java.lang.IllegalStateException - if the item is already destroyed

getWidth

public int getWidth()

Gets the width of this BrowserItem in pixels.

Overrides:

getWidth in class CanvasItem

Returns:

width in pixels

Throws:

java.lang.IllegalStateException - if the item is already destroyed

setPosition

public void setPosition(int x,
                        int y)

Sets the rendering position of this BrowserItem. The anchor point given is relative to the upper left corner of the parent, Canvas or CustomItem.

The BrowserItem may be placed fully off or partially of the visible area of the parent, Canvas or CustomItem, by the setPosition method; in this case the BrowserItem is just partly visible.

Overrides:

setPosition in class CanvasItem

Parameters:

x - the x coordinate of the anchor point, in pixels.

y - the y coordinate of the anchor point, in pixels.

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

java.lang.IllegalStateException - if the item is already destroyed

See Also:

setParent(java.lang.Object parent)

getPositionX

public int getPositionX()

Gets the rendering position of this BrowserItem. The origin is relative to the coordinate system of parent.

Overrides:

getPositionX in class CanvasItem

Returns:

X location of the BrowserItem

Throws:

java.lang.IllegalStateException - if the item is already destroyed

getPositionY

public int getPositionY()

Sets the rendering position of this BrowserItem. The origin is relative to the coordinate system of parent.

Overrides:

getPositionY in class CanvasItem

Returns:

Y location of the BrowserItem

Throws:

java.lang.IllegalStateException - if the item is already destroyed

setVisible

public void setVisible(boolean visible)

Sets the visibility value of BrowserItem. Initially BrowserItem is not visible so it must be explicitly set to visible in order it to appear on UI.

Setting visibility to true shows the BrowserItem with its content. If the BrowserItem is already visible calling setVisible(true) does nothing.

Setting the visibility to false hides the BrowserItem and its content. If the BrowserItem is already hidden calling setVisible(false) does nothing.

Overrides:

setVisible in class CanvasItem

Parameters:

visible - visibility of the BrowserItem

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set.

java.lang.IllegalStateException - if the item is already destroyed

See Also:

setParent(java.lang.Object parent)

setZPosition

public void setZPosition(int z)

Sets the Z-position, or the elevation, of the item.

The elevation decides the stacking order of neighboring items. An item of high Z-position will be drawn on top of an item with a lower Z-position if they share the same parent item.

The z-position is unique for each item meaning that changing a Z-position of an item may change the Z-position of the items that share the same parent item. The Z-position does not affect the item's size in any way.

When items are added with CanvasItem.setParent(java.lang.Object) they will get a Z-position that is increased by 1 from the item that is the top most item at that time.

Overrides:

setZPosition in class CanvasItem

Parameters:

z - the Z-position of the item.

Throws:

java.lang.IllegalArgumentException - If z < 0

java.lang.IllegalStateException - if a valid parent object has not been set or item is destroyed

See Also:

getZPosition(), setParent(java.lang.Object parent)

getZPosition

public int getZPosition()

Returns the Z-position, or the elevation, of the item. The Z-position decides the stacking order of neighboring items.

Overrides:

getZPosition in class CanvasItem

Returns:

the Z-position of the item.

Throws:

java.lang.IllegalStateException - if a valid parent object has not been set or item is destroyed

See Also:

setZPosition(int), setParent(java.lang.Object parent)

scale

public void scale(int width,
                  int height)

Overrides the CanvasItem's scale method as on BrowserItem it is not supported

Overrides:

scale in class CanvasItem

Parameters:

width - the new width in pixels

height - the new height in pixels

Throws:

java.lang.IllegalStateException - if the item is already destroyed

See Also:

scalling mode settings

scale

public void scale(int x,
                  int y,
                  int width,
                  int height)

Overrides the CanvasItem's scale method as on BrowserItem it is not supported

Overrides:

scale in class CanvasItem

Parameters:

x - the x coordinate of the anchor point

y - the y coordinate of the anchor point

width - the new width in pixels

height - the new height in pixels

Throws:

java.lang.IllegalStateException - if the item is already destroyed

See Also:

scaling mode settings, setPosition(int, int), scale(int, int)

setScalingMode

public void setScalingMode(int scaleMode,
                           boolean aspectRatioPreserved,
                           int anchor)

Overrides the CanvasItem's method as on BrowserItem it is not supported

Overrides:

setScalingMode in class CanvasItem

Parameters:

scaleMode - scaling mode: SCALE_NEAREST or SCALE_AVERAGE or SCALE_NOT_ALLOWED

aspectRatioPreserved - set to true to preserve aspect ration when scaling

anchor - the anchor point for positioning the window

Throws:

java.lang.IllegalArgumentException - if scaleMode or/and anchor are not a legal values.

java.lang.IllegalStateException - if the item is already destroyed

See Also:

for more details

getParent

public java.lang.Object getParent()

Gets the current parent of this CanvasItem

Overrides:

getParent in class CanvasItem

Returns:

the current parent

Throws:

java.lang.IllegalStateException - if the item is already destroyed

destroy

public void destroy()

Destroys the BrowserItem, releases its resources after the call this item cannot be used any more, but a new one can be aquired

Throws:

java.lang.IllegalStateException - if the item is already destroyed

isVisible

public boolean isVisible()

Returns the visibility of the browser

Overrides:

isVisible in class CanvasItem

Returns:

is the item is visible

Throws:

java.lang.IllegalStateException - if the item is already destroyed

getUrl

public java.lang.String getUrl()

Gets the url of the currently loaded page

Returns:

the url of the current page

Throws:

java.lang.IllegalStateException - if the item is already destroyed

getTitle

public java.lang.String getTitle()

Gets the title of the currently loaded page

Returns:

the title

Throws:

java.lang.IllegalStateException - if the item is already destroyed

invokeUrl

public void invokeUrl(java.lang.String url)
               throws java.io.IOException,
                      java.lang.SecurityException,
                      java.lang.IllegalArgumentException,
                      javax.microedition.io.ConnectionNotFoundException

Invokes a url

Parameters:

url - the url to be loaded and rendered

Throws:

java.lang.IllegalStateException - if the item is already destroyed

java.io.IOException - if network connection problem happens

java.lang.SecurityException - if no permission to open network connection

java.lang.IllegalArgumentException - If a parameter is invalid

javax.microedition.io.ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol type is not supported

loadHistoryByUrl

public void loadHistoryByUrl(java.lang.String url)
                      throws java.io.IOException,
                             java.lang.SecurityException,
                             java.lang.IllegalArgumentException,
                             javax.microedition.io.ConnectionNotFoundException

Makes the browser to load a url from the history

Parameters:

url - the url to be loaded from history

Throws:

java.lang.IllegalStateException - if the item is already destroyed

java.io.IOException - if network connection problem happens

java.lang.SecurityException - if no permission to open network connection

java.lang.IllegalArgumentException - If a parameter is invalid

javax.microedition.io.ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol type is not supported

reload

public void reload()

Reloads the current page

Throws:

java.lang.IllegalStateException - if the item is already destroyed

stop

public void stop()

Stops loading

Throws:

java.lang.IllegalStateException - if the item is already destroyed

noteDialogDone

public void noteDialogDone()

This function should be called when the note dialog has been closed

Throws:

java.lang.IllegalStateException - if the item is already destroyed

confirmDialogDone

public void confirmDialogDone(boolean yesno)

This function should be called when the user has selected yes or no from a confirm dialog

Parameters:

yesno - the user's selection

Throws:

java.lang.IllegalStateException - if the item is already destroyed

fileSelectDialogDone

public void fileSelectDialogDone(java.lang.String file)
                          throws java.io.IOException,
                                 java.lang.SecurityException,
                                 java.lang.IllegalArgumentException,
                                 javax.microedition.io.ConnectionNotFoundException

This function should be called when the user has finished file selection

Parameters:

file - the path to the file

Throws:

java.lang.IllegalStateException - if the item is already destroyed

java.io.IOException - if file connection problem happens

java.lang.SecurityException - if no permission to access the file

java.lang.IllegalArgumentException - If a parameter is invalid

javax.microedition.io.ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol type is not supported

selectListDialogDone

public void selectListDialogDone(int[] ids)

This function should be called when the user has finished list selection

Parameters:

ids - the selected ids

Throws:

java.lang.IllegalStateException - if the item is already destroyed

java.lang.IllegalArgumentException - if the ids are not from list provided at onSelectListDialog()

saveSelectedImage

public int saveSelectedImage(java.lang.String filePath)
                      throws java.io.IOException,
                             java.lang.SecurityException,
                             java.lang.IllegalArgumentException,
                             javax.microedition.io.ConnectionNotFoundException

Saves the selected image to the file system

Parameters:

filePath - the path where the image should be saved

Returns:

0 when successful, 1 when failed

Throws:

java.lang.IllegalStateException - if the item is already destroyed

java.io.IOException - if file connection problem happens

java.lang.SecurityException - if no permission to access the file

java.lang.IllegalArgumentException - If a parameter is invalid

javax.microedition.io.ConnectionNotFoundException - If the target of the name cannot be found, or if the requested protocol type is not supported

setBrowserListener

public void setBrowserListener(BrowserListener listener)

Sets the BrowserItem's listener to get notifications from the BrowserItem

Parameters:

listener - to be notified

Throws:

java.lang.IllegalStateException - if the item is already destroyed