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.