Help Center

Local Navigation

Object: Window

Availability

BlackBerry® Device Software version 3.8 or later

The Window object is created automatically when the BlackBerry® Browser encounters a <body> or <frameset> tag. It returns information about the window.

Window properties

Property name

Type

Description

Status

Support level

Availability

applicationCache

ApplicationCache

Returns the ApplicationCache object that applies to the active document of that browser window.

read only

HTML 5 Offline Applications

6.0 or later

blackberry

blackberry

Returns a reference to the blackberry object.

read only

Not part of any standard

3.8 or later

closed

boolean

Returns whether the window is open or closed. This property always has a value of false.

read only

Not part of any standard

3.8 or later

document

Document

Returns the Document object that is contained within the window.

read only

Not part of any standard

3.8 or later

frameElement

HTMLElement

Returns the element in which the window is embedded, or null if the window is not embedded in any frame.

read only

Not part of any standard

3.8 or later

frames

NamedFrameMap

Returns a NamedFrameMap object that contains a collection of the frames contained by the frameset.

read only

Not part of any standard

3.8 or later

history

History

Returns the History object that contains a collection of recently accessed URLs.

read only

Not part of any standard

3.8 or later

innerHeight

int

Returns the height of the content area, including the horizontal scroll bar, if rendered.

read only

Not part of any standard

3.8 or later

innerWidth

int

Returns the width of the content area, including the vertical scroll bar, if rendered.

read only

Not part of any standard

3.8 or later

length

unsigned long

Returns the number of frames in the parent window.

read only

Not part of any standard

3.8 or later

localStorage

Storage

Returns a Storage object associated with the local storage area for the document's origin domain.

readonly

HTML 5 Web Storage

6.0 or later

location

Location

Specifies the URL of the document displayed in the browser window.

writable

Not part of any standard

3.8 or later

navigator

Navigator

Returns the Navigator object, which provides information about the BlackBerry® Browser.

read only

Not part of any standard

3.8 or later

name

String

Specifies the name of the window.

writable

Not part of any standard

3.8 or later

opener

Window

Returns the Window object that created the window.

read only

Not part of any standard

3.8 or later

orientation

int

Returns an integer that represents the current orientation of a BlackBerry device that has an accelerometer, such as a BlackBerry® Storm™ Series device.

This property can have one of the following values:

  • 0: The BlackBerrydevice is in portrait mode.
  • -90: The BlackBerry device is in landscape mode and is turned to the right
  • 90: the BlackBerry device is in landscape mode and turned to the left.

read only

Not part of any standard

4.7 or later

parent

Window

Returns the parent Window object.

read only

Not part of any standard

3.8 or later

screen

Screen

Returns the Screen object, which provides information about the BlackBerry device screen.

read only

Not part of any standard

3.8 or later

self

Window

Returns a reference to the current window.

read only

Not part of any standard

3.8 or later

sessionStorage

Storage

Returns a Storage object associated with the session storage area, which is available only for the current browser session.

readonly

HTML 5 Web Storage

6.0 or later

top

Window

Returns a reference to the top window.

read only

Not part of any standard

3.8 or later

window

Window

Returns a reference to the current window. Using the window property lets you invoke methods or call properties on the current window without confusion when multiple browser windows are open.

Because the BlackBerry Browser is a single document interface, a new window is opened each time a new URL is opened.

read only

Not part of any standard

3.8 or later

Window event handlers

Property name

Type

Description

Status

Availability

onabort

EventListener

Specifies the function to perform when the loading of a page or image is aborted.

writable

4.6 or later

onchange

EventListener

Specifies the function to perform when a form control loses focus after the user has modified the value.

writable

4.6 or later

onclick

EventListener

Specifies the function to perform when the user clicks the trackball or trackwheel on a BlackBerry® device.

writable

3.8 or later

onerror

EventListener

Specifies the function to perform when an ErrorEvent occurs in the worker thread.

writable

6.0 or later

onkeydown

EventListener

Specifies the function to perform when a key is pressed down while the pointer is over an element.

writable

4.6 or later

onkeypress

EventListener

Specifies the function to perform when a key is pressed and released while the pointer is over an element.

writable

4.6 or later

onkeyup

EventListener

Specifies the function to perform when a key is released while the pointer is over an element.

writable

4.6 or later

onload

EventListener

Specifies the function to perform when the BlackBerry® Browser finishes loading a new page or a complete frameset.

writable

4.6 or later

onmessage

EventListener

Specifies the function to perform when a MessageEvent occurs in the worker thread.

writable

6.0 or later

onmousedown

EventListener

Specifies the function to perform when the user depresses the trackwheel or trackball on a BlackBerry device.

writable

4.6 or later

onmousemove

EventListener

Specifies the function to perform when the user moves the pointer while it is over an element.

writable

4.6 or later

onmouseout

EventListener

Specifies the function to perform when the user moves the pointer off of an element.

writable

4.6 or later

onmouseover

EventListener

Specifies the function to perform when the user moves the pointer over an element.

writable

4.6 or later

onmouseup

EventListener

Specifies the function to perform when the user releases the trackwheel or trackball on a BlackBerry device.

writable

4.6 or later

onorientationchange

EventListener

Specifies the function to perform when the user changes the orientation of a BlackBerry device that has an accelerometer, such as a BlackBerry® Storm™ Series device.

writable

4.7 or later

onreset

EventListener

Specifies the function to perform when the user resets a form.

writable

3.8 or later

onselect

EventListener

Specifies the function to perform when the user selects some text in a text field.

writable

4.6 or later

onsubmit

EventListener

Specifies the function to perform when the user submits a form.

writable

3.8 or later

onunload

EventListener

Specifies the function to perform when the BlackBerry Browser removes a new page or a frameset.

writable

4.6 or later

Window methods

Method name

Description

Support level

Availability

addEventListener()

Adds an EventListener object to a set of event listeners for the window.

DOM 2 Events

4.6 or later

alert()

Displays a standard alert dialog box with an OK button.

Not part of any standard.

3.8 or later

atob()

Decodes a string of text that has been encoded using base-64 encoding.

Not part of any standard.

6.0 or later

blur()

Removes focus from the window.

Not part of any standard.

3.8 or later

btoa()

Encodes a string of text using base-64 encoding. The string can be decoded using atob().

Not part of any standard.

6.0 or later

clearInterval()

Cancels the interval set with setInterval().

HTML 5

6.0 or later

clearTimeout()

Cancels the timeout set with setTimeout().

HTML 5

6.0 or later

close()

Closes the active window.

Not part of any standard.

3.8 or later

confirm()

Displays a standard confirmation dialog box with an OK button and a Cancel button.

Not part of any standard.

3.8 or later

dispatchEvent()

Dispatches an Event object created by Document.createEvent().

DOM 2 Events

4.6 or later

find()

Displays a dialog box that allows a user to enter a string of text and search for it in the current document.

Not part of any standard.

4.6 or later

focus()

Gives focus to the current window.

Not part of any standard.

3.8 or later

getComputedStyle()

Retrieves the computed style values for an element.

DOM 2 Style

4.6 or later

moveBy()

Moves the window a specified number of pixels in relation to its current co-ordinates.

Not part of any standard.

3.8 or later

moveTo()

Moves the window's left and top edge to the specified co-ordinates.

Not part of any standard.

3.8 or later

open()

Opens a new browser window.

Not part of any standard.

3.8 or later

openDatabase()

Opens the given database on the BlackBerry device. If the database doesn't already exist, then a new database with the given name is created.

HTML 5

6.0 or later

postMessage()

Sends a message to the main thread of the Window object. The message contains the data to be passed between threads.

HTML 5

6.0 or later

print()

Prints the current contents of the window.

Not part of any standard.

3.8 or later

prompt()

Displays a prompt dialog box that prompts users for input.

Not part of any standard.

3.8 or later

removeEventListener()

Removes an event listener from an EventTarget.

DOM 2 Events

4.6 or later

resizeBy()

Resizes the viewport relative to the current viewport size.

Not part of any standard.

3.8 or later

resizeTo()

Resizes the viewport to the specified width and height.

Not part of any standard.

3.8 or later

scroll()

Scrolls the content to a given set of coordinates.

Not part of any standard.

3.8 or later

scrollBy()

Scrolls the content by the given number of pixels.

Not part of any standard.

3.8 or later

scrollTo()

Scrolls the content to a given set of coordinates.

Not part of any standard.

3.8 or later

setInterval()

Schedules a function or some code to run repeatedly at the specified interval.

HTML 5

6.0 or later

setTimeout()

Schedules a function or some code to run after a specified amount of time.

HTML 5

6.0 or later

stop()

Stops the current download.

Not part of any standard.

3.8 or later

Method: window.alert()

Availability

BlackBerry® Device Software version 3.8 or later

The alert() method displays a standard alert dialog box with an OK button.

You should use an alert dialog box for those cases in which no input is required by the user.

Syntax

window.alert( message )

Parameters

Parameter

Type

Description

message

String

The text that is displayed as the dialog box message.

Return values

None.

Exceptions

None.

Method: window.back()

Availability

BlackBerry® Device Software version 3.8 or later

The back() method displays the previous URL in the history list. This method is functionally equivalent to history.back().

Syntax

window.back()

Parameters

None.

Return values

None.

Exceptions

None.

Method: window.blur()

Availability

BlackBerry® Device Software version 3.8 or later

The blur() method removes focus from the window.

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax

window.blur()

Parameters

None.

Return values

This method is ignored. No values are returned.

Exceptions

None.

Method: window.close()

Availability

BlackBerry® Device Software version 3.8 or later

The close() method closes the active window. In the BlackBerry® Browser, this is functionally equivalent to window.back() and history.back().

If no earlier item exists in the window.history array, the BlackBerry Browser is closed and the browser session ends.

Syntax

window.close()

Parameters

None.

Return values

This method is ignored. No values are returned.

Exceptions

None.

Method: window.confirm()

Availability

BlackBerry® Device Software version 3.8 or later

The confirm() method displays a standard confirmation dialog box with an OK button and a Cancel button.

Use a confirm dialog box when you want to give the user the option to proceed with or cancel some action. The user may not continue to browse or use the current page until they have closed the dialog box.

Syntax

window.confirm( message )

Parameters

Parameter

Type

Description

message

String

The text that is displayed as the dialog box message.

Return values

Returns a value of true if the OK button was clicked; returns false if Cancel was clicked.

Exceptions

None.

Method: window.find()

Availability

BlackBerry® Device Software version 4.6 or later

The find() method searches for a given string in the current window. If the search term was located within the window, the search stops and returns a value of true.

If the search is restarted with the same term, the browser continues searching from the location of the last search result. If you provide a new search term, the browser begins searching at the start of the document and stops and returns a value of true when the given term is found.

Note that the caseSensitive and searchInFrames parameters are optional, but mutually inclusive. That is, you must either specify both of the parameters or neither of them.

Syntax

window.find( str [, caseSensitive, searchInFrames ] )

Parameters

Parameter

Type

Description

str

String

The string of text to search for in the current document.

caseSensitive

boolean

Optional. If true, indicates that the case of the search term should be considered when searching.

searchInFrames

boolean

Optional. If true, indicates that the browser should search for the given term in all currently displayed frames.

Return values

Return a value of true if the string is found; otherwise, returns false.

Exceptions

None.

Method: window.focus()

Availability

BlackBerry® Device Software version 3.8 or later

The focus() method gives focus to the window.

Syntax

window.focus()

Parameters

None.

Return values

None.

Exceptions

None.

Method: window.forward()

Availability

BlackBerry® Device Software version 3.8 or later

The forward() method displays the next URL in the history list of the browser. This method is functionally equivalent to history.forward().

Syntax

window.forward()

Parameters

None.

Return values

None.

Exceptions

None.

Method: window.home()

Availability

BlackBerry® Device Software version 3.8 or later

The home() method displays the page that the user set as the BlackBerry® Browser home page.

Syntax

window.home()

Parameters

None.

Return values

None.

Exceptions

None.

Method: window.moveBy()

Availability

BlackBerry® Device Software version 3.8 or later

The moveBy() method moves the window a specified number of pixels in relation to its current co-ordinates.

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax

window.moveBy ( deltaX, deltaY )

Parameters

Parameter

Type

Description

deltaX

int

The number of pixels to move the window horizontally.

deltaY

int

The number of pixels to move the window vertically.

Return values

This method is ignored. No values are returned.

Exceptions

None.

Method: window.moveTo()

Availability

BlackBerry® Device Software version 3.8 or later

The moveTo() method moves the window's left and top edge to the specified co-ordinates.

This method is a stub implementation. It has no effect on the BlackBerry® Browser .

Syntax

window.moveTo ( deltaX, deltaY )

Parameters

Parameter

Type

Description

deltaX

int

The number of pixels from the left edge of the screen to move the window.

deltaY

int

The number of pixels from the top edge of the screen to move the window.

Return values

This method is ignored. No values are returned.

Exceptions

None.

Method: window.open()

Availability

BlackBerry® Device Software version 3.8 or later

The open() method opens a new browser window.

The BlackBerry® Browser is a single document interface. It opens a new window and places it at the top of the stack whenever the user opens a link on a page or enters a new URL via the Go to menu item. Consequently, this method essentially has the same net effect in the BlackBerry Browser as specifying a new value for Window.location.

Syntax

window.open( URL [, name ] )

Parameters

Parameter

Type

Description

URL

int

The URL to be displayed in the child window.

name

String

Optional. The name of the window that is being opened.

Return values

Returns a reference to the new Window object.

Exceptions

None.

See also

window.close()

Method: window.print()

Availability

BlackBerry® Device Software version 3.8 or later

The print() method prints the current contents of the window.

This method is a stub implementation. It has no effect on the BlackBerry® Browser.

Syntax

window.print()

Parameters

None.

Return values

This method is ignored. No values are returned.

Exceptions

None.

Method: window.prompt()

Availability

BlackBerry® Device Software version 3.8 or later

The prompt() method displays a prompt dialog box that prompts users for input. A prompt dialog box includes a single line input field.

Use a prompt dialog when you need immediate feedback from the user. The user may not continue to browse or use the current page until they have closed the dialog box.

Syntax

window.prompt( message, defaultValue )

Parameters

Parameter

Type

Description

message

String

The text that is displayed as the dialog box message.

defaultValue

String

The default value of the input field, or null if no default is to be provided.

Return values

Returns the user input as a string. If the user enters no input, this method returns an empty string.

Exceptions

None.

Method: window.resizeBy()

Availability

BlackBerry® Device Software version 3.8 or later

The resizeBy() method resizes the viewport relative to the current window size.

To resize the viewport to an absolute size, use window.resizeTo().

Syntax

window.resizeBy( deltaX, deltaY )

Parameters

Parameter

Type

Description

deltaX

int

The number of pixels to resize the window by horizontally.

deltaY

int

The number of pixels to resize the window by vertically.

Return values

None.

Exceptions

None.

Method: window.resizeTo()

Availability

BlackBerry® Device Software version 3.8 or later

The resizeTo() method resizes the window to the specified width and height.

Syntax

window.resizeTo( width, height )

Parameters

Parameter

Type

Description

width

int

The new width of the viewport, in pixels.

height

int

The new height of the viewport, in pixels.

Return values

None.

Exceptions

None.

Method: window.scrollBy()

Availability

BlackBerry® Device Software version 3.8 or later

The scrollBy() method scrolls the content by the given number of pixels.

Syntax

window.scrollBy( deltaX, deltaY )

Parameters

Parameter

Type

Description

deltaX

int

The distance, in pixels, to scroll the document horizontally.

deltaY

int

The distance, in pixels, to scroll the document vertically.

Return values

None.

Exceptions

None.

Method: window.scrollTo()

Availability

BlackBerry® Device Software version 3.8 or later

The scrollTo() method scrolls the content to a given set of coordinates. This method is functionally equivalent to window.scroll().

Syntax

window.scrollTo( x, y )

void

Parameters

Parameter

Type

Description

x

int

The position along the horizontal access, in pixels, to which to scroll the document.

y

int

The position along the vertical access, in pixels, to which to scroll the document.

Return values

None.

Exceptions

None.

Method: window.scroll()

Availability

BlackBerry® Device Software version 3.8 or later

The scroll() method scrolls the content to a given set of coordinates. This method is functionally equivalent to window.scrollTo().

Syntax

window.scroll( x, y )

Parameters

Parameter

Type

Description

x

int

The position along the horizontal access, in pixels, to which to scroll the document.

y

int

The position along the vertical access, in pixels, to which to scroll the document.

Return values

None.

Exceptions

None.

Method: window.stop()

Availability

BlackBerry® Device Software version 3.8 or later

The stop() method stops the current download.

This method is equivalent to the user clicking the Stop item in the BlackBerry® Browser menu.

Syntax

window.stop()

Parameters

None.

Return values

None.

Exceptions

None.

Next topic: XML API

Was this information helpful? Send us your comments.