Object: Window

Help Center

Search This Document

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.

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

Previous topic: Method: Selection.selectAllChildren()

Was this information helpful? Send us your comments.

Global Navigation

Help Center

Local Navigation

Object: Window

Window properties

Window event handlers

Window methods

Method: window.alert()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.back()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.blur()

Syntax

Parameters

Return values

Exceptions

Method: window.close()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.confirm()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.find()

Syntax

Parameters

Return values

Exceptions

Method: window.focus()

Syntax

Parameters

Return values

Exceptions

Method: window.forward()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.home()

Syntax

Parameters

Return values

Exceptions

Method: window.moveBy()

Syntax

Parameters

Return values

Exceptions

Method: window.moveTo()

Syntax

Parameters

Return values

Exceptions

Method: window.open()

Syntax

Parameters

Return values

Exceptions

See also

Method: window.print()

Syntax

Parameters

Return values

Exceptions

Method: window.prompt()

Syntax