Window Covers
The cover namespace allows you to modify the app's window cover, which is displayed when the application is in thumbnail mode.
The Window Covers API had significant updates between WebWorks 2.0 and WebWorks 2.1. For more information, see the Release Notes.
If you need to continue using the WebWorks 2.0 version of the API, you can refer to the WebWorks 1.0 Window Covers API documentation. The only change to this API between WebWorks 1.0 and WebWorks 2.0 is that instead of including a <feature> element in your config.xml file, you add the cover plugin using the following command:
webworks plugin add com.blackberry.ui.cover
The following image shows window covers on a device:

Installation:
To use this API in your project, add the cover plugin:
webworks plugin add com.blackberry.ui.cover
Function Type | Function Name |
---|---|
void | getCoverSizes() (new in 2.1) |
void | resetCover() (updated in 2.1) |
void | updateCovers() (new in 2.1) |
Events |
---|
entercover |
exitcover |
Constant Type | Constant Name |
---|---|
String | TRANSITION_DEFAULT |
String | TRANSITION_FADE |
String | TRANSITION_NONE |
String | TRANSITION_SLIDE |
String | TYPE_IMAGE |
String | TYPE_SNAPSHOT |
getCoverSizes()
Gets the names and sizes of the covers. Cover sizes may vary between devices, and some devices may have more than one size.
New in BlackBerry WebWorks 2.1.
Synopsis:
void blackberry.ui.cover.getCoverSizes(onSuccess, onError)
Parameters:
- onSuccess(sizes)
-
Callback function that will be triggered when cover sizes are successfully retrieved.
- sizes
- Type: Object[]
Array with name, width, and height for each cover.
- onError( )
-
Callback function that will be triggered if cover sizes cannot be retrieved.
Example:
<script type="text/javascript"> blackberry.ui.cover.getCoverSizes( function (sizes) { console.log('List of cover sizes:'); for (var cover in sizes) { if (sizes.hasOwnProperty(cover)) { console.log(cover + ': ' + sizes[cover].width + ',' + sizes[cover].height); } } }, function (e) { console.log('Error getting cover sizes: ' + e); } ); </script>
resetCover()
Resets the window cover to default behavior: use a scaled snapshot.
Updated in BlackBerry WebWorks 2.1.
The name parameter is new in BlackBerry WebWorks 2.1.
Synopsis:
void blackberry.ui.cover.resetCover(name, onSuccess, onError)
Parameters:
- name
- Type: String
The name of the cover to be reset.
- onSuccess( )
-
Callback function that will be triggered when cover sizes are successfully retrieved.
- onError( )
-
Callback function that will be triggered if covers sizes cannot be retrieved.
Example:
<script type="text/javascript"> blackberry.ui.cover.resetCover( 'fullSize', function () { console.log('Cover reset'); }, function (e) { console.log('Cover reset error ' + e); } ); </script>
updateCovers()
Updates the app's window covers.
New in BlackBerry WebWorks 2.1.
Synopsis:
void blackberry.ui.cover.updateCovers(coverInfo, onSuccess, onError)
Parameters:
- coverInfo[ ]
- Type: Cover
Information about the covers to update.
- onSuccess( )
-
Callback function that will be triggered when covers are successfully updated.
- onError( )
-
Callback function that will be triggered if covers cannot be updated.
Example:
<script type="text/javascript"> var covers = [ ], fullsize = new blackberry.ui.cover.Cover('fullSize', blackberry.ui.cover.TYPE_SNAPSHOT), halfsize = new blackberry.ui.cover.Cover('halfSize', blackberry.ui.cover.TYPE_IMAGE); fullsize.capture.x = 10; fullsize.capture.y = 10; fullsize.capture.width = 334; fullsize.capture.height = 396; fullsize.text.push(new blackberry.ui.cover.Label('fullSize snapshot', 12)); halfsize.text.push(new blackberry.ui.cover.Label('halfSize image', 12)); halfsize.path = 'local:///window2.jpg'; covers.push(fullsize); covers.push(halfsize); blackberry.ui.cover.updateCovers( covers, function () { console.log('Covers updated'); }, function (e) { console.log('Cover update error ' + e); } ); </script>
entercover
The entercover event is triggered whenever the app displays the window cover in thumbnail mode.
Synopsis:
Event
Example:
<script type="text/javascript"> function onEnterCover() { console.log("app is entering cover mode"); } document.addEventListener('enterCover', onEnterCover); </script>
exitcover
The exitcover event is triggered whenever the app removes the window cover, exiting thumbnail mode.
Synopsis:
Event
Example:
<script type="text/javascript"> function onExitCover() { console.log("app is exiting cover mode"); } document.addEventListener('exitCover', onExitCover); </script>
TRANSITION_DEFAULT
Specifies default window cover transition.
Synopsis:
constant
String blackberry.ui.cover.TRANSITION_DEFAULT = 'default'
TRANSITION_FADE
Specifies the fade window cover transition.
Synopsis:
constant
String blackberry.ui.cover.TRANSITION_FADE = 'fade'
TRANSITION_NONE
Specifies no window cover transition.
Synopsis:
constant
String blackberry.ui.cover.TRANSITION_NONE = 'none'
TRANSITION_SLIDE
Specifies the slide window cover transition.
Synopsis:
constant
String blackberry.ui.cover.TRANSITION_SLIDE = 'slide'
TYPE_IMAGE
Specifies image mode.
Synopsis:
constant
String blackberry.ui.cover.TYPE_IMAGE = 'file'
TYPE_SNAPSHOT
Specifies snapshot mode.
Synopsis:
constant
String blackberry.ui.cover.TYPE_SNAPSHOT = 'snapshot'
Last modified: 2015-02-19
Got questions about leaving a comment? Get answers from our Disqus FAQ.
comments powered by Disqus