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:

Device showing window covers.

Installation:

To use this API in your project, add the cover plugin:

webworks plugin add com.blackberry.ui.cover
Functions:
void getCoverSizes() (new in 2.1)
void resetCover() (updated in 2.1)
void updateCovers() (new in 2.1)
Constants:
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) {Function}

Callback function that will be triggered when cover sizes are successfully retrieved.

sizes {Object[]}

Array with name, width, and height for each cover.

onError() {Function}

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);
            }
        }            
    });

</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 {String}

The name of the cover to be reset.

onSuccess() {Function}

Callback function that will be triggered when cover sizes are successfully retrieved.

onError() {Function}

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 () { console.log('Cover reset error'); }        
    );

</script>

updateCovers()

Updates the app's window covers.

New in BlackBerry WebWorks 2.1.

Synopsis:

void blackberry.ui.cover.updateCovers(coverInfo)

Parameters:

coverInfo[] {Cover}

Information about the covers to update.

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.width = 334;        
    fullsize.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 () { console.log('Cover update error'); }        
    );      

</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() {
        blackberry.ui.cover.updateCovers();
    }

    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: 2014-09-29



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus